mirror of
https://github.com/tiennm99/ccs.git
synced 2026-07-16 22:16:41 +00:00
fix(repo): remove tracked plans workspace files
This commit is contained in:
Tam Nhu Tran
@@ -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.
|
||||
@@ -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.
|
||||
-121
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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."
|
||||
|
||||
Reference in New Issue
Block a user