@minniexcode/codex-switch 0.0.5 → 0.0.7

package/docs/cli-usage.md

@@ -89,7 +89,7 @@ CLI 的交互行为遵循以下规则：
 
 典型受影响命令包括：
 
-- `setup`
+- `migrate`
 - `add`
 - `edit`
 - `switch`
@@ -207,40 +207,89 @@ codexs backups list --json
 
 ## 5. 变更类命令
 
-### 5.1 `setup`
+### 5.1 `init`
 
-从现有 Codex 目录初始化 `providers.json`。
+轻量初始化目标 Codex 目录，确保 `providers.json` 已存在。
 
 ```bash
-codexs setup [--json] [--codex-dir <path>] [--merge|--overwrite]
+codexs init [--json] [--codex-dir <path>]
 ```
 
 示例：
 
 ```bash
-codexs setup
-codexs setup --overwrite --json
-codexs setup --merge --codex-dir ./.tmp-codex
+codexs init
+codexs init --json
+codexs init --codex-dir ./.tmp-codex
+```
+
+行为说明：
+
+- 不依赖 `codex` 可执行文件
+- 不要求 `config.toml` 或 `auth.json` 已存在
+- `providers.json` 不存在时创建空 registry：`{ "providers": {} }`
+- `providers.json` 已存在时返回成功 no-op，不改写文件，也不会创建备份
+- 成功 JSON 结果固定包含：`codexDir`、`createdCodexDir`、`createdProvidersFile`、`providersAlreadyExisted`、`configExists`、`authExists`
+
+交互模式：
+
+- 未显式传 `--codex-dir` 时，会复用候选目录发现并允许你选择或手动输入目录
+- 如果目标目录不存在，会确认是否创建目录
+
+非交互模式：
+
+- `--json` 或非 TTY 下绝不会进入 prompt
+- 目标目录不存在时直接返回结构化错误
+
+### 5.2 `migrate`
+
+从现有 `config.toml` adopt unmanaged profiles，并写入受管理的 `providers.json`。
+
+```bash
+codexs migrate [--json] [--codex-dir <path>] [--merge|--overwrite]
+```
+
+示例：
+
+```bash
+codexs migrate
+codexs migrate --overwrite --json
+codexs migrate --merge --codex-dir ./.tmp-codex
 ```
 
 行为说明：
 
 - 读取 `config.toml` 中已有 profile
+- 仅 adopt 已具备 `model`、`model_provider` 且能解析到匹配 `model_providers.*.base_url` 和 `env_key` 的 unmanaged profile
 - 收集每个 profile 对应的 provider 记录
-- 在受管备份流程下写入 `providers.json`
-- 成功后会自动运行一次 `doctor`
+- 保持现有受管备份、锁、`auth.json` mirror 和 post-run `doctor` 流程
 
 交互模式：
 
 - 如果 `providers.json` 已存在，会让你选择 `merge`、`overwrite` 或取消
-- 如果需要补全 provider 细节，会在 TTY 中询问
+- profile 选择和 provider 细节收集仍然只在 TTY 中进行
 
 非交互模式：
 
 - `providers.json` 已存在时，必须显式传入 `--merge` 或 `--overwrite`
 - `--json` 模式下不会进入任何引导式输入
+- 由于 adopt profile 选择和 provider secret 收集仍然是交互契约，当前版本会直接失败
+
+### 5.3 `setup`
+
+`setup` 已弃用，不再执行实际初始化或迁移工作。
+
+```bash
+codexs setup
+```
+
+行为说明：
 
-### 5.2 `add`
+- 该命令现在返回 `COMMAND_DEPRECATED`
+- 错误详情中包含 `replacements: ["init", "migrate"]`
+- 应改用 `codexs init` 或 `codexs migrate`
+
+### 5.4 `add`
 
 新增一个 provider。
 
@@ -262,7 +311,7 @@ codexs add
 - `provider`：provider 名称，也是后续 `switch/show/edit/remove` 的标识
 - `--profile`：写入到 `config.toml` 的 profile 名称
 - `--api-key`：provider API key
-- `--base-url`：可选的 API base URL
+- `--base-url`：可选的 provider 元数据，不会写回 `[profiles.*]`
 - `--note`：备注
 - `--tag`：标签，可重复传多次
 
@@ -271,13 +320,13 @@ codexs add
 - 如果缺少 `provider`、`profile`、`apiKey`，会在 TTY 中补问
 - profile 选择会优先复用现有 `config.toml` profile
 - API key 的隐藏输入会做二次确认
-- tag 支持预设多选和自定义逗号分隔输入
+- tag 仅支持预设选项多选
 
 非交互模式：
 
 - 必须显式传入所有必填字段
 
-### 5.3 `edit`
+### 5.5 `edit`
 
 编辑单个 provider 的字段。
 
@@ -308,39 +357,35 @@ codexs edit packycode --tag daily --tag paid
 
 - 至少要提供一个需要修改的字段
 
-### 5.4 `switch`
+### 5.6 `switch`
 
 切换当前使用的 provider/profile。
 
 ```bash
-codexs switch <provider> [--no-login] [--json] [--codex-dir <path>]
+codexs switch <provider> [--json] [--codex-dir <path>]
 ```
 
 示例：
 
 ```bash
 codexs switch freemodel
-codexs switch freemodel --no-login
-codexs switch --no-login
+codexs switch freemodel --json
+codexs switch
 ```
 
 行为说明：
 
 - 根据 `providers.json` 找到目标 provider
 - 更新相关运行态配置
-- 默认会执行 Codex 登录刷新流程
+- 重写当前 active provider 对应的 `auth.json` mirror
 - 会先备份 `config.toml` 和 `auth.json`
 
-参数说明：
-
-- `--no-login`：切换后不执行登录刷新
-
 交互模式：
 
 - 如果没有传 `<provider>`，TTY 下会弹出 provider 选择器
 - 如果已经传了 `<provider>`，则直接执行，不再额外确认
 
-### 5.5 `remove`
+### 5.7 `remove`
 
 删除一个 provider 记录。
 
@@ -369,7 +414,7 @@ codexs remove freemodel --force --json
 
 - 必须同时传入 `<provider>` 和 `--force`
 
-### 5.6 `import`
+### 5.8 `import`
 
 从外部 JSON 文件导入 provider 配置。
 
@@ -400,7 +445,7 @@ codexs import ./providers.json --merge --json
 - 不会弹出路径向导或确认框
 - 会先验证输入文件，再执行写入
 
-### 5.7 `export`
+### 5.9 `export`
 
 导出当前 `providers.json` 到指定文件。
 
@@ -498,7 +543,7 @@ codexs <command> --json
 ```bash
 codexs list --json
 codexs show packycode --json
-codexs switch packycode --no-login --json
+codexs switch packycode --json
 codexs export ./providers.snapshot.json --force --json
 codexs rollback 20260511-221457-switch --json
 ```
@@ -508,7 +553,8 @@ codexs rollback 20260511-221457-switch --json
 ### 8.1 第一次接管现有 Codex 配置
 
 ```bash
-codexs setup
+codexs init
+codexs migrate
 codexs list
 codexs doctor
 ```
@@ -546,7 +592,8 @@ codexs rollback <backup-id>
 
 以下命令会修改本地配置或覆盖文件，使用前应明确预期：
 
-- `setup`
+- `init`
+- `migrate`
 - `add`
 - `edit`
 - `switch`
@@ -572,6 +619,8 @@ codexs --help
 也可以查看单个命令帮助：
 
 ```bash
+codexs help init
+codexs help migrate
 codexs help setup
 codexs help add
 codexs help switch

package/docs/codex-switch-technical-architecture.md

@@ -130,6 +130,13 @@ Infrastructure 层
 
 这意味着未来即使引入 GUI / MCP / HTTP 适配层，核心同步目标仍然是 runtime files，而不是把 runtime files 本身当成长期管理数据库。
 
+`0.0.6` 的实现边界还需要区分“逻辑主层”和“兼容层”：
+
+- 逻辑主层已经迁移到 `src/commands/`、`src/interaction/`、`src/storage/`、`src/runtime/`
+- `src/cli/` 和 `src/infra/` 当前主要承担兼容 re-export 与入口收敛职责
+- 这意味着 `0.0.6` 的完成标准是“边界和契约已经统一”，而不是“所有旧路径文件都物理删除”
+- 后续版本可以在兼容窗口结束后继续删除旧 facade，但这不属于 `0.0.6` 的必须交付范围
+
 ### 3.3 模块依赖图
 
 当前代码依赖关系可以抽象为：
@@ -194,10 +201,14 @@ argv
 ```text
 src/
   cli.ts
+  commands/
+  interaction/
   app/
   cli/
   domain/
+  runtime/
   infra/
+  storage/
 
 tests/
   app.spec.js
@@ -220,7 +231,65 @@ scripts/
 
 它不直接做文件读写，不直接写业务逻辑，也不直接实现备份或校验规则。
 
-### 4.2 `src/cli/`
+### 4.2 `src/commands/`
+
+这一层是 `0.0.6` 新增的命令表面层，负责把“公开 CLI 形态”收敛为单一 registry。
+
+它承担的职责是：
+
+- 定义每个命令的公开 token 形态，例如 `config show`、`config list-profiles`、`backups list`
+- 统一保存 `summary`、`usage`、`details`、`examples`
+- 绑定 command handler，供 dispatch 直接执行
+- 让 help、解析和 dispatch 共享同一份事实源
+
+它不负责：
+
+- 具体文件读写
+- prompt 交互细节
+- human output 渲染
+
+### 4.3 `src/interaction/`
+
+这一层是 `0.0.6` 中显式抽出的交互层，负责所有 CLI 级 prompt 组合逻辑。
+
+它承担的职责是：
+
+- 判断哪些路径允许交互
+- 组合 provider 选择、确认、rollback 预览等交互动作
+- 组织 add/edit/setup 中的渐进式输入收集
+
+它不负责：
+
+- 业务状态变更
+- 文件系统写入
+- 运行时探测
+
+`setup` 是这一层边界最强的命令之一。在 `0.0.6` 中，它的 adopt profile 选择和 provider 详情输入仍然是交互式 contract，因此非交互路径会显式失败，而不是隐式进入空输入分支。
+
+### 4.4 `src/storage/`
+
+这一层是 `0.0.6` 的文件和状态访问层，负责把以前分散在 `infra/` 的能力收口成稳定存储边界。
+
+它承担的职责是：
+
+- `config.toml` / `providers.json` / backup manifest / lock file 的读写
+- Codex home 目录路径展开
+- 原子写入、备份、回滚、锁定
+
+`src/infra/` 在当前版本主要保留兼容 re-export，以便逐步迁移，不再作为新的业务入口继续扩张。
+
+### 4.5 `src/runtime/`
+
+这一层是 `0.0.6` 新增的运行时边界，负责本地 Codex CLI 的外部依赖探测和登录调用。
+
+它承担的职责是：
+
+- Codex 可用性检查
+- Codex 版本检查
+- Codex login 调用
+- 未来可扩展为第三方 runtime adapter 的能力边界
+
+### 4.6 `src/cli/`
 
 #### `src/cli/args.ts`
 
@@ -272,7 +341,7 @@ scripts/
 
 这两个纯渲染入口的作用是让 CLI 层本身也能被测试，而不依赖真实子进程。
 
-### 4.3 `src/app/`
+### 4.7 `src/app/`
 
 这一层是应用服务 / 用例编排层。每个文件基本对应一个命令或一个用例：
 
@@ -301,7 +370,7 @@ scripts/
 - `stdout` / `stderr` 怎么写
 - argv 怎么解析
 
-### 4.4 `src/domain/`
+### 4.8 `src/domain/`
 
 #### `errors.ts`
 
@@ -463,7 +532,7 @@ scripts/
   - 用于 `codex login --with-api-key`
 - `baseUrl`
   - 选填
-  - 当前版本只存储，不回写 `config.toml`
+  - 当前版本只存储在 `providers.json`；`config show` 中展示的 runtime `baseUrl` 由 `model_provider -> model_providers.*.base_url` 解析
 - `note`
   - 选填
   - 面向人类和 AI 的说明字段

package/docs/test-report-0.0.5.md

@@ -0,0 +1,163 @@
+# Test Report: 0.0.5
+
+Date: 2026-05-13
+
+## Environment
+
+- Platform: Windows (`win32`)
+- Node.js: `v24.11.1`
+- npm: `11.13.0`
+- Workspace: `C:\Users\A200477427\Developers\Github\codex-switch`
+
+## Commands Run
+
+```bash
+npm run build
+npm test
+```
+
+## Overall Result
+
+- Build: PASS
+- Test suites: 5/5 PASS
+
+Suite results:
+
+- `domain`: PASS
+- `app`: PASS
+- `cli`: PASS
+- `dev-sandbox`: PASS
+- `e2e`: PASS
+
+## Coverage Added In This Pass
+
+New test assets:
+
+- `tests/dev-sandbox.spec.js`
+- `tests/e2e.spec.js`
+- `docs/testing.md`
+
+Updated wiring:
+
+- `tests/helpers.js`
+- `tests/run-tests.js`
+
+## Detailed Results
+
+### 1. Domain Suite
+
+Status: PASS
+
+Focus:
+
+- config patch planning
+- managed profile view generation
+- provider normalization and masking
+- runtime drift helpers
+- backup list helpers
+
+### 2. App Suite
+
+Status: PASS
+
+Focus:
+
+- list/current/status
+- add/edit/show/remove
+- import/export
+- switch/login/rollback
+- setup
+- doctor
+- lock conflict and rollback behavior
+
+### 3. CLI Suite
+
+Status: PASS
+
+Focus:
+
+- arg parsing
+- help rendering
+- JSON success/failure envelopes
+- interactive add/edit/remove/import/export/rollback/setup flows
+- config commands
+
+### 4. Dev Sandbox Suite
+
+Status: PASS
+
+Fixture:
+
+- `dev-codex/local-sandbox`
+
+Validated with the built CLI command dispatcher against the real development fixture:
+
+- `list --json`
+- `current --json`
+- `status --json`
+- `config show --json`
+- `backups list --json`
+- `doctor --json`
+
+Observed state during test:
+
+- active profile: `packycode`
+- managed providers: `freemodel`, `packycode`
+- status issues: `0`
+- backups found: `>= 1`
+
+### 5. End-to-End Suite
+
+Status: PASS
+
+Fixture strategy:
+
+- copy `dev-codex/local-sandbox` into a temp directory
+- run write commands against the temp copy
+- keep the repository fixture unchanged
+
+Validated flows:
+
+- `switch freemodel` updates active profile and refreshes `auth.json`
+- `rollback` restores `config.toml` and `auth.json`
+- `add` creates a provider in `providers.json`
+- `edit` updates note and tags
+- `remove --force` deletes a non-active provider
+- `add --create-profile` creates a managed profile section in `config.toml` when a same-named `[model_providers.*]` runtime section already exists
+- destructive removal of the active provider fails with `PROFILE_IN_USE`
+- `import --merge` replaces overlapping providers and keeps merged state valid
+- `export` writes a valid providers file
+- `backups list` skips corrupt backup folders with warnings
+- `rollback missing-backup` fails with `BACKUP_NOT_FOUND`
+- corrupt `backups/latest.json` fails with `ROLLBACK_FAILED`
+- `setup` adopt flow works through CLI dispatch with mocked Codex CLI availability
+
+Validated mixed workflows:
+
+- `add -> switch -> edit -> show -> config show -> export -> rollback`
+- `import --merge -> switch --no-login -> remove -> doctor -> backups list -> rollback <backup-id>`
+
+## Release Confidence
+
+Current confidence for `0.0.5`: medium-high.
+
+Why:
+
+- core read and write workflows now have automated coverage
+- the development fixture is exercised directly by the built CLI
+- backup/rollback behavior is covered by both existing and new tests
+
+## Residual Risks
+
+- `setup` is not yet covered as a true subprocess end-to-end command because it depends on interactive adopt input and external `codex` availability
+- `rollback-latest` still has no direct dedicated test case even though `rollback` coverage is strong
+- `README.md` still shows version `0.0.4` in the documentation text and should be updated separately
+
+## Recommended Pre-Release Checklist
+
+Before the next publish:
+
+- run `npm test`
+- run a manual smoke check of `node dist/cli.js --help`
+- run one real local `switch --no-login` against a temp `--codex-dir`
+- update user-facing docs if the package version changes

package/docs/test-report-0.0.7.md

@@ -0,0 +1,118 @@
+# Test Report: 0.0.7
+
+Date: 2026-05-14
+
+## Environment
+
+- Platform: Windows (`win32`)
+- Workspace: `C:\Users\A200477427\Developers\Github\codex-switch`
+- Node.js: `v24.11.1`
+- npm: `11.13.0`
+
+## Scope
+
+This report covers the current automated suite plus the new built-CLI entrypoint checks added in `tests/cli-e2e.spec.js`.
+
+Chinese summary:
+
+- `npm test` is not compile-only. It rebuilds `dist/` and then runs the full automated suite.
+- `add` now has explicit built-CLI non-interactive regression coverage.
+- `migrate` is verified in two ways: built CLI non-interactive failure contract, plus injected interactive workflow coverage.
+- `setup` is verified as deprecated and must fail with `COMMAND_DEPRECATED`.
+
+## Commands Run
+
+```bash
+npx tsc --noEmit
+npm test
+```
+
+## Overall Result
+
+- TypeScript check: PASS
+- Build and suites: PASS
+- Full suite total: `39 passed, 0 failed`
+
+Suite results:
+
+- `commands`: PASS (`10/10`)
+- `cli-e2e`: PASS (`7/7`)
+- `interaction`: PASS (`8/8`)
+- `runtime`: PASS (`2/2`)
+- `workflows`: PASS (`12/12`)
+
+## Built CLI Command Matrix
+
+Read commands covered through the built CLI entrypoint:
+
+- `--help`
+- `--version`
+- `list --json`
+- `show --json`
+- `current --json`
+- `status --json`
+- `config show --json`
+- `config list-profiles --json`
+- `backups list --json`
+- `doctor --json`
+
+Write commands covered through the built CLI entrypoint on temp copies:
+
+- `init --json`
+- `add --json`
+- `add --create-profile --json`
+- `edit --json`
+- `switch --json`
+- `remove --force --json`
+- `import --json`
+- `export --force --json`
+- `rollback --json`
+
+Negative contract checks through the built CLI entrypoint:
+
+- `add` against a missing profile without `--create-profile`
+- removing the active provider profile
+- `rollback <missing-id>`
+- `migrate --overwrite --json`
+- `setup --json`
+
+## Key Findings
+
+### 1. `npm test` behavior
+
+`npm test` rebuilds the project first and then executes the JavaScript test harness in `tests/run-tests.js`. It is not a compile-only command.
+
+### 2. `add`
+
+Validated behaviors:
+
+- succeeds non-interactively when all required flags are provided
+- creates `providers.json` entries with derived `envKey`
+- supports `--create-profile` to add missing profile and model provider sections
+- fails with `PROFILE_NOT_FOUND` when targeting a missing profile without `--create-profile`
+
+### 3. `migrate`
+
+Validated behaviors:
+
+- built CLI non-interactive path currently fails by design with `INVALID_ARGUMENT`
+- error payload includes adoptable profile metadata and a suggestion to run in an interactive TTY
+- interactive adopt flow remains covered in `tests/workflows.spec.js` through runtime injection
+
+This means the current implementation does not support a full non-interactive `migrate` workflow yet. The new tests lock that behavior in as an explicit contract instead of silently leaving it unverified.
+
+### 4. Repository sandbox observations
+
+Observed from the checked-in `dev-codex/local-sandbox` fixture during this run:
+
+- active profile: `freemodel`
+- managed providers in `list --json`: `alpha`, `bestmodel`, `beta`, `freemodel`
+- `doctor --json` returns `healthy: false` in this automation environment because runtime probing reports `CODEX_NOT_INSTALLED`
+- the `doctor` issue is environmental, not a providers/config parse failure
+
+## Residual Risks
+
+- prompt-driven subprocess automation for true interactive `migrate` is still not covered end-to-end
+- Windows sandbox restrictions currently block nested `child_process` launches with `EPERM`, so automated command checks run through the built CLI entrypoint in-process instead of spawning `node dist/cli.js`
+- `rollback-latest` still lacks a dedicated direct test
+- backup corruption coverage is still focused on selected cases rather than an exhaustive matrix