From bc4ab98af41e9c9f049cc5da2e6ff356832ef14b Mon Sep 17 00:00:00 2001 From: Tam Nhu Tran Date: Sun, 19 Apr 2026 17:22:40 -0400 Subject: [PATCH] fix(repo): remove tracked plans workspace files --- .../phase-01-cli-routing-namespacing.md | 127 --------------- .../phase-02-storage-api-boundaries.md | 140 ----------------- .../phase-03-dashboard-deprecation-ux.md | 121 -------------- .../phase-04-tests-docs-rollout.md | 148 ------------------ .../plan.md | 93 ----------- scripts/ci-parity-gate.sh | 11 ++ 6 files changed, 11 insertions(+), 629 deletions(-) delete mode 100644 plans/20260415-1016-cursor-provider-legacy-split/phase-01-cli-routing-namespacing.md delete mode 100644 plans/20260415-1016-cursor-provider-legacy-split/phase-02-storage-api-boundaries.md delete mode 100644 plans/20260415-1016-cursor-provider-legacy-split/phase-03-dashboard-deprecation-ux.md delete mode 100644 plans/20260415-1016-cursor-provider-legacy-split/phase-04-tests-docs-rollout.md delete mode 100644 plans/20260415-1016-cursor-provider-legacy-split/plan.md diff --git a/plans/20260415-1016-cursor-provider-legacy-split/phase-01-cli-routing-namespacing.md b/plans/20260415-1016-cursor-provider-legacy-split/phase-01-cli-routing-namespacing.md deleted file mode 100644 index 44d44c4b..00000000 --- a/plans/20260415-1016-cursor-provider-legacy-split/phase-01-cli-routing-namespacing.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -phase: 1 -title: "CLI Routing & Namespacing" -status: complete -effort: "6h" ---- - -# Phase 1: CLI Routing & Namespacing - -## Context Links - -- `plan.md` -- `src/ccs.ts` -- `src/auth/profile-detector.ts` -- `src/cursor/constants.ts` -- `src/commands/root-command-router.ts` -- `src/commands/command-catalog.ts` -- `src/commands/help-command.ts` -- `src/commands/cursor-command.ts` -- `src/commands/cursor-command-display.ts` -- `src/types/profile.ts` -- `src/config/reserved-names.ts` - -## Overview - -- Priority: P1 -- Owner scope: CLI entry, help, profile detection, command naming -- Goal: make `cursor` provider-first and move the deprecated bridge under `legacy cursor` - -## Key Insights - -- The current collision is structural, not cosmetic. `ccs cursor` means "legacy bridge" in `src/ccs.ts` and `src/auth/profile-detector.ts`, but `cursor` is also listed as a built-in CLIProxy provider. -- `shouldUseCursorCliproxyShortcut()` is only a heuristic escape hatch. It does not fix bare `ccs cursor`, quoted prompts, or help routing. -- Help is currently inconsistent: provider help exists generically, but `cursor` is excluded and routed to bridge help instead. - -## Requirements - -- Reserve `cursor` for CLIProxy runtime and CLIProxy admin flags. -- Introduce explicit legacy syntax: `ccs legacy cursor ...`. -- Keep a release-N alias for old legacy admin subcommands only. -- Rename internal bridge-only profile typing from ambiguous `cursor` to explicit `legacy-cursor`. -- Keep file ownership isolated to CLI/router/help files in this phase. - -## Data Flow - -- Provider path: - `argv -> root command resolution -> provider shortcut/help path -> ProfileDetector(type=cliproxy, provider=cursor) -> CLIProxy runtime` -- Legacy path: - `argv -> legacy root command -> legacy cursor subrouter -> ProfileDetector(type=legacy-cursor) or direct handler -> local bridge runtime` -- Deprecated alias path, release N only: - `argv=ccs cursor auth|status|... -> alias shim -> warning -> dispatch to legacy cursor handler` - -## Architecture - -- Add a new root command namespace: `ccs legacy`. -- Add nested routing under `legacy` with `cursor` as the first migrated leaf. Do not overload `cursor` itself any longer. -- Remove provider exceptions for `cursor` from the generic provider help/routing logic. `ccs cursor --help` should now use provider shortcut help. -- Convert bridge-only type checks from `profileInfo.type === 'cursor'` to `profileInfo.type === 'legacy-cursor'`. -- Keep `ccs cursor help` only as a release-N compatibility shim that prints: - - `Use "ccs cursor --help" for CLIProxy Cursor` - - `Use "ccs legacy cursor help" for the deprecated bridge` - -## Related Code Files - -- Modify: - - `src/ccs.ts` - - `src/auth/profile-detector.ts` - - `src/cursor/constants.ts` - - `src/commands/root-command-router.ts` - - `src/commands/command-catalog.ts` - - `src/commands/help-command.ts` - - `src/commands/cursor-command.ts` - - `src/commands/cursor-command-display.ts` - - `src/types/profile.ts` - - `src/config/reserved-names.ts` - - `src/shared/claude-extension-setup.ts` - - `src/targets/target-runtime-compatibility.ts` -- Create: - - `src/commands/legacy-command.ts` or `src/commands/legacy/index.ts` - - `src/commands/legacy/cursor-command.ts` if the team wants physical separation immediately - -## Implementation Steps - -1. Add the `legacy` root command route and its help surface. -2. Flip `src/ccs.ts` so `cursor` goes through normal CLIProxy provider routing; remove the special-case that gives the bridge ownership of the name. -3. Replace the `shouldUseCursorCliproxyShortcut()` hack with provider-first dispatch plus a compatibility alias table for the old legacy subcommands. -4. Update `ProfileDetector` priority order so `cursor` resolves as `cliproxy`, while `legacy cursor` resolves as `legacy-cursor`. -5. Rename bridge-only help text, summaries, and status text to say "legacy Cursor bridge" explicitly. -6. Audit all `profileType === 'cursor'` checks and convert only the bridge-specific ones to `legacy-cursor`. - -## Todo List - -- [x] Add `legacy cursor` routing -- [x] Make `ccs cursor` provider-first for bare, prompt, and `--help` usage -- [x] Add deprecated alias forwarding for old admin subcommands -- [x] Rename internal bridge profile path to `legacy-cursor` -- [x] Update provider help, completion, and command catalog summaries - -## Success Criteria - -- `ccs cursor "task"` resolves to CLIProxy Cursor. -- `ccs legacy cursor "task"` resolves to the old bridge. -- `ccs cursor --help` shows provider shortcut help. -- `ccs cursor auth` still works in release N, but prints an exact replacement warning. -- No CLI path depends on `shouldUseCursorCliproxyShortcut()` to disambiguate runtime meaning. - -## Risk Assessment - -- High likelihood / high impact: users with scripts calling `ccs cursor "task"` will hit the provider path immediately. - Mitigation: call this out in release notes, keep admin aliases, add explicit warning when legacy files/config are detected and the user invokes `ccs cursor` with no flags. -- Medium likelihood / medium impact: bridge-only type renames may break target compatibility checks or extension setup. - Mitigation: grep audit every `profileType === 'cursor'` branch before tests. - -## Rollback Plan - -- Re-enable the old `cursor` special-case in `src/ccs.ts` and `ProfileDetector`. -- Keep the new `legacy` namespace in place even if dormant; it is additive and safe to leave. -- Do not roll back migrated files in this phase; routing rollback alone is enough. - -## Security Considerations - -- No auth material moves in this phase. -- Preserve existing `CCS_HOME`-aware path resolution. Do not introduce `os.homedir()` shortcuts while adding the new namespace. - -## Next Steps - -- Phase 2 depends on the new command contract from this phase. diff --git a/plans/20260415-1016-cursor-provider-legacy-split/phase-02-storage-api-boundaries.md b/plans/20260415-1016-cursor-provider-legacy-split/phase-02-storage-api-boundaries.md deleted file mode 100644 index 05cf43e8..00000000 --- a/plans/20260415-1016-cursor-provider-legacy-split/phase-02-storage-api-boundaries.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -phase: 2 -title: "Storage & API Boundaries" -status: partial -effort: "6h" ---- - -# Phase 2: Storage & API Boundaries - -## Context Links - -- `plan.md` -- `src/config/unified-config-types.ts` -- `src/config/unified-config-loader.ts` -- `src/cursor/cursor-auth.ts` -- `src/cursor/cursor-daemon-pid.ts` -- `src/cliproxy/config/path-resolver.ts` -- `src/cliproxy/config/env-builder.ts` -- `src/web-server/routes/index.ts` -- `src/web-server/routes/cursor-routes.ts` -- `src/web-server/routes/cursor-settings-routes.ts` -- `src/web-server/routes/cliproxy-stats-routes.ts` -- `src/api/services/profile-lifecycle-service.ts` - -## Overview - -- Priority: P1 -- Owner scope: config schema, path resolution, backend APIs, migration readers -- Goal: make legacy bridge storage explicit and guarantee CLIProxy Cursor never writes the legacy raw settings file - -## Key Insights - -- Top-level `config.cursor` is bridge-only configuration today and must move. -- The legacy bridge owns `~/.ccs/cursor.settings.json`, `~/.ccs/cursor/credentials.json`, and `~/.ccs/cursor/daemon.pid`. -- CLIProxy provider settings currently resolve through generic provider settings helpers and can still collide with the legacy file for provider `cursor`. -- `~/.ccs/cursor.settings.json` is historically documented as legacy-owned, so it is unsafe to auto-import it into provider storage by default. - -## Requirements - -- Canonical legacy config key: `legacy.cursor` -- Canonical legacy files: - - `~/.ccs/legacy/cursor.settings.json` - - `~/.ccs/legacy/cursor/credentials.json` - - `~/.ccs/legacy/cursor/daemon.pid` -- Canonical provider file for CLIProxy Cursor only: - - `~/.ccs/cliproxy/cursor.settings.json` -- Canonical legacy API namespace: - - `/api/legacy/cursor/*` -- Compatibility reads: - - read old `config.cursor` - - read old `~/.ccs/cursor.settings.json` - - read old `~/.ccs/cursor/*` -- Compatibility writes: - - write only the new `legacy.*` and `cliproxy/*` paths - -## Data Flow - -- Legacy config: - `load config -> prefer legacy.cursor -> fallback config.cursor -> normalize -> write legacy.cursor only` -- Legacy raw settings: - `load /api/legacy/cursor/settings/raw -> prefer ~/.ccs/legacy/cursor.settings.json -> fallback ~/.ccs/cursor.settings.json -> write new legacy path` -- Provider settings: - `CLIProxy env builder/stats updater -> read ~/.ccs/cliproxy/cursor.settings.json -> if absent use defaults -> never read/write ~/.ccs/cursor.settings.json` - -## Architecture - -- Add a `legacy` section to unified config types and loader. Keep old `cursor` as read-only migration input during the compatibility window. -- Move legacy bridge filesystem helpers under a `legacy/cursor` path prefix. -- Split API routing: - - new canonical mount: `/api/legacy/cursor` - - release-N alias: `/api/cursor` -> same handlers + deprecation header -- Special-case CLIProxy provider settings for `cursor` only in the provider path resolver. Do not expand this migration to every provider in this issue. -- Treat existing `~/.ccs/cursor.settings.json` as legacy-owned. Do not auto-copy it into provider storage unless a future explicit provider migration is added. - -## Related Code Files - -- Modify: - - `src/config/unified-config-types.ts` - - `src/config/unified-config-loader.ts` - - `src/cursor/cursor-auth.ts` - - `src/cursor/cursor-daemon-pid.ts` - - `src/cliproxy/config/path-resolver.ts` - - `src/cliproxy/config/env-builder.ts` - - `src/web-server/routes/index.ts` - - `src/web-server/routes/cursor-routes.ts` - - `src/web-server/routes/cursor-settings-routes.ts` - - `src/web-server/routes/cliproxy-stats-routes.ts` - - `src/api/services/profile-lifecycle-service.ts` -- Create: - - `src/web-server/routes/legacy-cursor-routes.ts` - - `src/web-server/routes/legacy-cursor-settings-routes.ts` - - `src/config/migrations/cursor-legacy-migration.ts` if migration logic should stay out of the loader - -## Implementation Steps - -1. Extend config types and loader to support `legacy.cursor`, with `legacy.cursor` taking precedence over old `cursor`. -2. Update legacy bridge credential and pid helpers to use `~/.ccs/legacy/cursor/`. -3. Update the raw settings route to use `~/.ccs/legacy/cursor.settings.json` as canonical and old root path as read fallback only. -4. Move legacy API mounts to `/api/legacy/cursor/*` and keep `/api/cursor/*` as a warned alias for release N. -5. Change CLIProxy Cursor provider settings resolution to `~/.ccs/cliproxy/cursor.settings.json`. -6. Update orphan detection and cleanup logic so old `cursor.settings.json` is treated as a migration target, not a permanent provider-owned file. - -## Todo List - -- [ ] Add `legacy.cursor` config schema and loader precedence -- [ ] Move bridge credentials/pid/raw settings under `~/.ccs/legacy/` -- [x] Add canonical `/api/legacy/cursor/*` routes -- [x] Keep release-N `/api/cursor/*` alias -- [x] Isolate CLIProxy Cursor settings away from `~/.ccs/cursor.settings.json` -- [ ] Update cleanup/orphan handling - -## Success Criteria - -- Saving legacy bridge settings writes only to `legacy.cursor` and `~/.ccs/legacy/*`. -- CLIProxy Cursor model/env updates write only to `~/.ccs/cliproxy/cursor.settings.json`. -- Existing legacy users can still read old config/files during the compatibility window. -- No backend route that serves the provider path references `~/.ccs/cursor.settings.json`. - -## Risk Assessment - -- High likelihood / high impact: old `~/.ccs/cursor.settings.json` contents are ambiguous between bridge and provider expectations. - Mitigation: treat the file as legacy-owned and do not auto-import it into provider storage. -- Medium likelihood / medium impact: route aliasing may mask which API is canonical. - Mitigation: add explicit response headers or payload flags marking `/api/cursor/*` as deprecated. - -## Rollback Plan - -- Keep read fallback from old paths even if the canonical write path changes back. -- If the new legacy API namespace causes regressions, remount `/api/cursor/*` as canonical temporarily and keep the new namespace dormant. -- Do not delete old files during release N; cleanup stays opt-in until release N+2. - -## Security Considerations - -- Preserve `0600` for migrated credentials and `0700` for directories. -- Use atomic temp-file writes exactly as current routes do. -- Never copy provider tokens into the legacy namespace or legacy tokens into provider storage automatically. - -## Next Steps - -- Phase 3 depends on the canonical API and path names from this phase. diff --git a/plans/20260415-1016-cursor-provider-legacy-split/phase-03-dashboard-deprecation-ux.md b/plans/20260415-1016-cursor-provider-legacy-split/phase-03-dashboard-deprecation-ux.md deleted file mode 100644 index 00f22c6f..00000000 --- a/plans/20260415-1016-cursor-provider-legacy-split/phase-03-dashboard-deprecation-ux.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -phase: 3 -title: "Dashboard & Deprecation UX" -status: partial -effort: "4h" ---- - -# Phase 3: Dashboard & Deprecation UX - -## Context Links - -- `plan.md` -- `ui/src/App.tsx` -- `ui/src/components/layout/app-sidebar.tsx` -- `ui/src/pages/cursor.tsx` -- `ui/src/hooks/use-cursor.ts` -- `ui/src/lib/i18n.ts` -- `src/web-server/routes/index.ts` -- `src/commands/cursor-command-display.ts` - -## Overview - -- Priority: P1 -- Owner scope: dashboard route ownership, labels, user-facing deprecation messaging -- Goal: align dashboard semantics with CLI semantics so `/cursor` means provider and legacy UI is clearly marked and isolated - -## Key Insights - -- The current dashboard already admits the bridge is deprecated, but the route `/cursor` still belongs to it. -- The page includes direct navigation to CLIProxy Cursor, which means the UX already wants a split; the route layer just has not caught up. -- Keeping `/cursor` for legacy while CLI uses `cursor` for provider would create the same ambiguity in a different surface. - -## Requirements - -- `/cursor` must become the provider-owned dashboard surface. -- The legacy bridge page must move to `/legacy/cursor`. -- Legacy bridge API hooks must move to `/api/legacy/cursor/*`. -- The deprecated UX must contain exact replacements, not generic warnings. -- Sidebar grouping must reflect support level: - - provider view under provider/cliproxy navigation - - legacy bridge under deprecated navigation - -## Data Flow - -- Provider dashboard: - `browser /cursor -> provider view or redirect wrapper -> /cliproxy?provider=cursor -> existing CLIProxy provider APIs` -- Legacy dashboard: - `browser /legacy/cursor -> legacy bridge page -> useLegacyCursor hook -> /api/legacy/cursor/*` -- Compatibility API path, release N only: - `old UI/tests -> /api/cursor/* -> alias handler -> same legacy payload + deprecation signal` - -## Architecture - -- Keep provider UI DRY by making `/cursor` a thin redirect or preselected wrapper around the existing CLIProxy provider page instead of building a second Cursor-provider page. -- Move the current `ui/src/pages/cursor.tsx` implementation to a new `legacy-cursor` page and rename its hook to `useLegacyCursor`. -- Change nav labels from generic "Cursor IDE" to explicit "Cursor Bridge (Legacy)" in the deprecated section. -- Update CLI and dashboard warnings to show both paths side-by-side: - - `ccs cursor --auth` / `/cursor` - - `ccs legacy cursor auth` / `/legacy/cursor` - -## Related Code Files - -- Modify: - - `ui/src/App.tsx` - - `ui/src/components/layout/app-sidebar.tsx` - - `ui/src/lib/i18n.ts` - - `src/commands/cursor-command-display.ts` -- Move or rename: - - `ui/src/pages/cursor.tsx` -> `ui/src/pages/legacy-cursor.tsx` - - `ui/src/hooks/use-cursor.ts` -> `ui/src/hooks/use-legacy-cursor.ts` -- Create: - - `ui/src/pages/cursor-provider-redirect.tsx` if a wrapper is preferred over direct router config - -## Implementation Steps - -1. Move the legacy page and hook to `legacy-*` names and update all imports. -2. Reassign `/cursor` to the provider path and add `/legacy/cursor` for the bridge page. -3. Update sidebar grouping and labels so the provider path is no longer listed under Deprecated. -4. Replace vague deprecated copy with concrete migration copy: - - old command - - new command - - old route - - new route -5. Keep the legacy page banner persistent until release N+2, not dismissible per session. - -## Todo List - -- [ ] Move legacy page/hook module names to `legacy-*` -- [x] Reassign `/cursor` and add `/legacy/cursor` -- [x] Update deprecated nav group and labels -- [x] Rewrite key banners, button copy, and path labels with exact replacements -- [x] Keep provider and legacy links visible from both surfaces during release N - -## Success Criteria - -- Opening `/cursor` lands on the CLIProxy Cursor provider surface. -- Opening `/legacy/cursor` lands on the bridge page with a persistent deprecation banner. -- No dashboard component serving the provider route uses the legacy API hook. -- Every warning banner shows the exact before/after command and route. - -## Risk Assessment - -- Medium likelihood / medium impact: users with bookmarked `/cursor` expect the legacy page. - Mitigation: provider page shows a top-level "Looking for the old bridge?" callout linking to `/legacy/cursor`. -- Low likelihood / medium impact: UI rename churn breaks lazy imports or tests. - Mitigation: do route and hook rename in one phase and leave compatibility API alias in place until tests pass. - -## Rollback Plan - -- Point `/cursor` back to the legacy page if the provider redirect breaks. -- Keep `/legacy/cursor` additive; it does not block rollback. -- Do not remove the deprecation banner on rollback; it still communicates future intent. - -## Security Considerations - -- No auth secrets should be exposed in UI copy or route params. -- Keep manual auth dialogs scoped to the legacy page only. Provider auth remains in CLIProxy flows. - -## Next Steps - -- Phase 4 owns test rewrites, docs updates, and release gating for these UI changes. diff --git a/plans/20260415-1016-cursor-provider-legacy-split/phase-04-tests-docs-rollout.md b/plans/20260415-1016-cursor-provider-legacy-split/phase-04-tests-docs-rollout.md deleted file mode 100644 index 9fcd17d1..00000000 --- a/plans/20260415-1016-cursor-provider-legacy-split/phase-04-tests-docs-rollout.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -phase: 4 -title: "Tests Docs & Rollout" -status: complete -effort: "4h" ---- - -# Phase 4: Tests Docs & Rollout - -## Context Links - -- `plan.md` -- `docs/cursor-integration.md` -- `README.md` -- `docs/system-architecture/provider-flows.md` -- `docs/system-architecture/index.md` -- `tests/unit/cursor/cursor-shortcut-routing.test.ts` -- `tests/unit/web-server/cursor-settings-routes.test.ts` -- `tests/unit/web-server/cursor-routes.test.ts` -- `ui/tests/unit/hooks/use-cursor.test.tsx` -- `ui/tests/unit/ui/pages/cursor-page.test.tsx` - -## Overview - -- Priority: P1 -- Owner scope: compatibility rollout, validation, docs/help updates, release notes -- Goal: ship the namespace split without surprising existing bridge users or leaving docs/help inconsistent - -## Key Insights - -- This change has one intentional breaking behavior: positional `ccs cursor` stops being the legacy bridge. -- Everything else can use a compatibility window: admin subcommands, API aliases, old config reads, old file-path reads. -- Tests must lock both meanings so the ambiguity does not regress later. - -## Requirements - -- Document exact before/after commands and routes. -- Add a concrete migration path for three user groups: - - legacy bridge users - - CLIProxy Cursor users - - dashboard bookmark users -- Define removal windows for aliases and old path fallbacks. -- Run repo quality gates after implementation: - - root: `bun run format && bun run lint:fix && bun run validate && bun run validate:ci-parity` - - UI: `cd ui && bun run format && bun run lint:fix && bun run validate` - -## Test Matrix - -- Unit: - - provider-first cursor routing - - legacy alias forwarding - - `legacy.cursor` loader precedence - - path resolvers for legacy vs provider files - - deprecation help text snapshots -- Integration: - - `ccs cursor "task"` -> provider - - `ccs legacy cursor "task"` -> bridge - - `/api/legacy/cursor/*` canonical behavior - - `/api/cursor/*` alias behavior during release N -- UI: - - `/cursor` route ownership - - `/legacy/cursor` banner and actions - - hook path changes and raw settings save targets -- Manual release validation: - - migrate old config/files in a temp `CCS_HOME` - - verify provider path never writes `~/.ccs/cursor.settings.json` - -## User Migration Plan - -1. Legacy bridge users: - - replace `ccs cursor ...` with `ccs legacy cursor ...` - - run `ccs legacy cursor status` - - update scripts and dashboard bookmarks to `/legacy/cursor` -2. CLIProxy Cursor users: - - keep using `ccs cursor ...` - - if provider-specific settings are needed, re-save them under the new provider-owned path instead of relying on `~/.ccs/cursor.settings.json` -3. Mixed/unclear state: - - `ccs migrate` should move `config.cursor` and legacy files into the new legacy namespace - - do not auto-copy the old raw settings file into provider storage - -## Deprecation UX Plan - -- CLI warning text, release N: - - `ccs cursor auth` is deprecated. Use `ccs legacy cursor auth` for the old bridge or `ccs cursor --auth` for CLIProxy Cursor. -- Dashboard banner: - - visible on `/legacy/cursor` - - provider route links back to legacy route with "Looking for the old bridge?" -- Docs banner: - - top callout in `docs/cursor-integration.md` pointing users to CLIProxy Cursor as the supported path - -## Related Code Files - -- Modify tests: - - `tests/unit/cursor/cursor-shortcut-routing.test.ts` - - `tests/unit/web-server/cursor-settings-routes.test.ts` - - `tests/unit/web-server/cursor-routes.test.ts` - - `ui/tests/unit/hooks/use-cursor.test.tsx` - - `ui/tests/unit/ui/pages/cursor-page.test.tsx` -- Modify docs: - - `docs/cursor-integration.md` - - `README.md` if root command examples mention Cursor - - `docs/system-architecture/provider-flows.md` - - `docs/system-architecture/index.md` - - CLI help snapshots or generated references if present - -## Implementation Steps - -1. Rewrite tests around the new command contract and route ownership before removing aliases in later releases. -2. Update docs/help text in the same PR as code changes so the new syntax ships atomically. -3. Add migration notes to changelog/release notes with a bold callout that `ccs cursor "task"` now means CLIProxy Cursor. -4. Keep a removal checklist for release N+1 and N+2 in the plan or roadmap so the compatibility window does not become permanent. - -## Todo List - -- [x] Update unit, integration, and selected UI tests -- [x] Update docs and CLI help text -- [x] Add migration note and deprecation wording -- [x] Run root and UI quality gates -- [x] Record alias-removal follow-up for N+1 and old-path-removal follow-up for N+2 - -## Success Criteria - -- Test suite covers both provider and legacy cursor paths explicitly. -- Docs and help text match the shipped command contract exactly. -- Release notes include the migration table and deprecation window. -- Quality gates pass in both root and `ui/`. - -## Risk Assessment - -- High likelihood / medium impact: docs or tests lag behind the command flip and users keep invoking the wrong surface. - Mitigation: block merge until help text, docs, and tests all match the new contract. -- Medium likelihood / medium impact: compatibility shims never get removed. - Mitigation: create follow-up issues or roadmap entries for N+1 and N+2 removal work before merge. - -## Rollback Plan - -- If rollout messaging is incomplete, revert the command flip before removing aliases. -- If only docs/help are wrong, fix docs first and keep aliases until corrected. -- Old-path readers stay in place through N+1, so rollback does not strand migrated users. - -## Security Considerations - -- Use temp `CCS_HOME` in tests and manual verification. Never touch the real `~/.ccs`. -- Sanitize any migration logs or warnings so they mention paths, not token contents. - -## Next Steps - -- Implementation is complete when all four phases land together; do not ship phase 1 without phases 2-4. diff --git a/plans/20260415-1016-cursor-provider-legacy-split/plan.md b/plans/20260415-1016-cursor-provider-legacy-split/plan.md deleted file mode 100644 index f57f3f29..00000000 --- a/plans/20260415-1016-cursor-provider-legacy-split/plan.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: "Separate legacy Cursor bridge from CLIProxy Cursor provider" -description: "Reserve `cursor` for the CLIProxy provider, move the reverse-engineered bridge under `legacy`, and split storage/UI with a staged migration." -status: in_progress -priority: P1 -effort: 2d -branch: kai/feat/1016-missing-provider-integration -tags: [cursor, cliproxy, migration, dashboard, deprecation] -created: 2026-04-15 -blockedBy: [] -blocks: [] ---- - -# Separate legacy Cursor bridge from CLIProxy Cursor provider - -## Goal - -Make `cursor` mean one thing everywhere: the CLIProxy-backed provider. Move the deprecated local bridge to `legacy`, stop provider writes to `~/.ccs/cursor.settings.json`, and ship a low-risk migration window. - -## Current Collision Points - -- `src/ccs.ts` hardcodes `cursor` as a legacy command/profile, then reclaims only `--auth|--logout|--config|--accounts` for CLIProxy. -- `src/auth/profile-detector.ts` resolves `cursor` to the legacy runtime before CLIProxy provider detection. -- `src/commands/command-catalog.ts` and `src/commands/help-command.ts` advertise `cursor` as both bridge and provider. -- `src/config/unified-config-types.ts` + `src/config/unified-config-loader.ts` store bridge config under top-level `cursor`. -- `src/cliproxy/config/path-resolver.ts`, `src/cliproxy/config/env-builder.ts`, and `src/web-server/routes/cliproxy-stats-routes.ts` still use provider settings paths that collide with the legacy raw file. -- `src/web-server/routes/cursor-*.ts`, `ui/src/pages/cursor.tsx`, `ui/src/hooks/use-cursor.ts`, `ui/src/App.tsx`, and `ui/src/components/layout/app-sidebar.tsx` dedicate `/cursor` and `/api/cursor/*` to the legacy bridge. -- `docs/cursor-integration.md` documents `ccs cursor` as the bridge even though CLIProxy already exposes a `cursor` provider shortcut. - -## Command Contract - -Before: -```text -ccs cursor -> legacy bridge runtime -ccs cursor "task" -> legacy bridge runtime -ccs cursor auth|status|... -> legacy bridge admin -ccs cursor --auth|--config -> CLIProxy Cursor shortcut -``` - -After release N: -```text -ccs cursor -> CLIProxy Cursor runtime -ccs cursor "task" -> CLIProxy Cursor runtime -ccs cursor --auth|--config -> CLIProxy Cursor admin -ccs legacy cursor -> legacy bridge runtime -ccs legacy cursor "task" -> legacy bridge runtime -ccs legacy cursor auth|... -> legacy bridge admin -``` - -Compatibility window, release N only: -- `ccs cursor auth|status|probe|models|start|stop|enable|disable|help` forwards to `ccs legacy cursor ...` with a deprecation warning. -- Bare and positional `ccs cursor` switch immediately to the provider path; no silent legacy fallback. - -## Phase Plan - -| Phase | Scope | Output | -| --- | --- | --- | -| 1 | [CLI Routing & Namespacing](./phase-01-cli-routing-namespacing.md) | Provider-first `cursor`, explicit `legacy cursor`, updated help/catalog/type names | -| 2 | [Storage & API Boundaries](./phase-02-storage-api-boundaries.md) | `legacy.cursor` config, split file paths, `/api/legacy/cursor/*`, provider path isolation | -| 3 | [Dashboard & Deprecation UX](./phase-03-dashboard-deprecation-ux.md) | `/cursor` -> provider view, `/legacy/cursor` -> bridge view, clear migration UX | -| 4 | [Tests Docs & Rollout](./phase-04-tests-docs-rollout.md) | Compatibility plan, migration steps, test matrix, docs updates, rollback gates | - -## Rollout Sequence - -1. Release N: add new legacy namespace, flip `ccs cursor` to provider, keep old admin subcommands and `/api/cursor/*` as warned aliases, and split provider settings away from `~/.ccs/cursor.settings.json`. -2. Release N+1: move the remaining legacy backend/config namespaces fully under `legacy.cursor`, keep old file-path fallback and `/api/cursor/*` alias for one more release. -3. Release N+2: remove old `config.cursor` and root-level `~/.ccs/cursor*` fallback reads, delete stale alias docs/help, and let cleanup/migrate remove leftovers. - -## Current Implementation Status - -- Completed in this branch: - - `ccs cursor` is provider-first for runtime and `--help` - - `ccs legacy cursor` works as the explicit legacy bridge namespace - - old legacy admin subcommands under `ccs cursor ...` forward with deprecation warnings - - CLIProxy Cursor settings no longer collide with `~/.ccs/cursor.settings.json` - - `/cursor` redirects to the provider surface while `/legacy/cursor` serves the deprecated bridge page - - `/api/legacy/cursor/*` is mounted and the legacy page uses that namespace - - docs, completion, and core regression tests were updated -- Intentionally deferred follow-up: - - move top-level `config.cursor` to `legacy.cursor` - - move legacy credentials/pid/raw settings fully under `~/.ccs/legacy/cursor/*` - - rename `use-cursor` and `CursorPage` modules to explicit `legacy-*` - -## Success Criteria - -- `cursor` is provider-owned in CLI help, routing, dashboard nav, and docs. -- Legacy bridge is reachable only through `legacy cursor` and `legacy.cursor` storage. -- CLIProxy Cursor never reads or writes `~/.ccs/cursor.settings.json`. -- Existing legacy users have an explicit migration path, warning UX, and rollback-safe compatibility window. - -## Docs Impact - -Major. CLI reference, Cursor docs, dashboard tour, provider docs, and migration notes all change in the same release. diff --git a/scripts/ci-parity-gate.sh b/scripts/ci-parity-gate.sh index bb507ae8..5e1c7a1f 100755 --- a/scripts/ci-parity-gate.sh +++ b/scripts/ci-parity-gate.sh @@ -15,6 +15,17 @@ if [[ ! -f AGENTS.md ]]; then exit 1 fi +TRACKED_PLANS="$(git ls-files -- plans)" +if [[ -n "$TRACKED_PLANS" ]]; then + echo "[X] Tracked files found under plans/." + echo " plans/ is workspace-only and must stay ignored." + while IFS= read -r tracked_path; do + echo " $tracked_path" + done <<< "$TRACKED_PLANS" + echo " Remove them from the index with: git rm -r --cached plans" + exit 1 +fi + CURRENT_BRANCH="$(git rev-parse --abbrev-ref HEAD)" if [[ -z "$CURRENT_BRANCH" || "$CURRENT_BRANCH" == "HEAD" ]]; then echo "[i] Detached HEAD detected. Skipping pre-push CI parity gate."