mirror of
https://github.com/CopilotKit/CopilotKit.git
synced 2026-09-14 16:26:20 +08:00
Jordan Ritter
5b37a94571
## Summary Companion structural PR to #5971. It fixes the **root cause** behind the a2ui divergence #5971 patched: the showcase's single-source symlinks eroded to real, drifting copies. `showcase/integrations/*/tools`, `*/shared-tools`, `*/_shared` are meant to be **symlinks into `showcase/shared/...`** — `stage_shared()` dereferences them for the Docker build, `restore_symlinks()` restores them. An **accidental `stage_shared()` leak** (commit `534cd1efa7`, PR #4449 "D5 all-green") committed the dereferenced real files instead of restoring the symlinks. Once they were real files, they drifted — which is exactly how the a2ui `render_a2ui` vs `_design_a2ui_surface` split (fixed in #5971) arose. ## Changes - **Restore 12 Python `tools/` dirs to symlinks** → `../../shared/python/tools` (ag2, agno, claude-sdk-python, crewai-crews, google-adk, langgraph-fastapi, langgraph-python, langroid, llamaindex, ms-agent-python, pydantic-ai, strands). Content is byte-adopted from shared — verified no load-bearing per-integration code is lost (only `render_a2ui` naming + shared `roll_dice`/sanitize additions). Integrations' intentional internal-planner names (llamaindex, ms-agent-python) live in `src/`, not `tools/`, and are untouched. - **`showcase/AGENTS.md` (+ `CLAUDE.md`, root pointers, INTEGRATION-CHECKLIST section)** — canonical statement of the 4 iron rules (identical tests, near-identical frontends, minimal backends, per-integration fixtures) + the single-source symlink mechanism ("edit the shared source only; a real file there is a bug"). These were previously written down nowhere. - **`validate-shared-symlinks` CI guard** — fails on any NEW erosion (real dir where a symlink belongs), with a shrink-only baseline that tightens to fully-enforcing as symlinks are restored. Mirrors the existing `validate-*` ratchet pattern. ## Scope / independence - **No overlap with #5971** — this PR touches nothing under `showcase/shared/typescript/` and does not modify the 3 TS integration `shared-tools/` dirs (verified: empty file-set intersection). Mergeable independently. - Build-safe: `stage_shared()` correctly dereferences the restored symlinks (targets resolve within the build context); `restore_symlinks()` recreates them post-build. ## Verified - `validate-shared-symlinks` test suite: 7/7 pass; validator EXIT 0 (no new erosion). - Reviewed by a full panel (correctness, content-integrity, build/CI, docs, scope, silent-failure, simplicity) — zero mandatory findings. ## Follow-ups (deliberately out of scope) 1. **3 TS `shared-tools` dirs** (mastra, claude-sdk-typescript, langgraph-typescript) remain real (baselined) — symlink them in a follow-up **after #5971 merges**, to avoid overlapping its TS edits. 2. **Guard hardening**: validate the symlink *target* (not just that it's a symlink), fail-loud on a malformed baseline, and code-enforce the shrink-only ratchet. (This PR's guard catches the real-file erosion — the actual failure mode; these are robustness extras.) 3. Pre-existing `shared/python` a2ui test failures (#5971-adjacent) and a couple of stale doc line-refs, noted during review. Companion: #5971.