@minniexcode/codex-switch 0.0.4 → 0.0.6

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/testing.md

@@ -0,0 +1,131 @@
+# Testing Guide
+
+`codex-switch` now has four test layers:
+
+- `tests/domain.spec.js`: pure domain/unit coverage
+- `tests/app.spec.js`: file-backed application integration coverage
+- `tests/cli.spec.js`: CLI dispatch and prompt simulation coverage
+- `tests/dev-sandbox.spec.js`: real `node dist/cli.js` read-only smoke tests against `dev-codex/local-sandbox`
+- `tests/e2e.spec.js`: write-command regression tests against temporary copies of `dev-codex/local-sandbox`
+
+## Commands
+
+Build the CLI:
+
+```bash
+npm run build
+```
+
+Run the full suite:
+
+```bash
+npm test
+```
+
+Run a single suite manually:
+
+```bash
+node -e "require('./tests/dev-sandbox.spec').run()"
+node -e "require('./tests/e2e.spec').run()"
+```
+
+## Development Fixture
+
+The repository fixture lives at:
+
+```text
+dev-codex/local-sandbox/
+```
+
+It is used in two different ways:
+
+- read-only dispatcher tests point at it directly
+- mutation tests copy it into a temporary directory before running writes
+
+Do not point destructive automation directly at `dev-codex/local-sandbox` unless you intentionally want to update the fixture.
+
+## Read-Only Smoke Tests
+
+`tests/dev-sandbox.spec.js` verifies the built CLI against the real development fixture.
+
+Covered commands:
+
+- `list --json`
+- `current --json`
+- `status --json`
+- `config show --json`
+- `backups list --json`
+- `doctor --json`
+
+These tests check two execution styles:
+
+- development default resolution with `NODE_ENV=development`
+- explicit `--codex-dir dev-codex/local-sandbox`
+
+This is the fastest way to validate that `0.0.x` builds still read the repo sandbox correctly.
+
+## Mutation Regression Tests
+
+`tests/e2e.spec.js` uses `fs.cpSync()` to clone `dev-codex/local-sandbox` into a temp directory, then exercises the real CLI command dispatcher against the copy.
+
+Covered write scenarios:
+
+- `switch` with login and backup creation
+- `rollback` restoring `config.toml` and `auth.json`
+- `add`, `edit`, `remove`
+- `add --create-profile`
+- blocking destructive remove of the active profile provider
+- `import --merge`
+- `export`
+- `backups list` with corrupt backup entries
+- `rollback <missing-id>`
+- corrupt `backups/latest.json`
+
+It also includes mixed workflow scenarios where multiple commands operate on the same sandbox copy end-to-end, for example:
+
+- `add -> switch -> edit -> show -> config show -> export -> rollback`
+- `import --merge -> switch --no-login -> remove -> doctor -> backups list -> rollback <backup-id>`
+
+The setup flow is covered with `executeCommand()` plus mocked Codex CLI checks because `setup` currently depends on external `codex --version` availability and interactive adopt input.
+
+## Fixture Rules
+
+- Prefer `--codex-dir <temp-copy>` for all write tests.
+- Prefer `--json` when assertions need stable output.
+- Treat `show --json` output as sensitive because it includes unmasked API keys.
+- If a test needs `codex login` or `codex --version`, prefer mocking the spawn layer.
+- Keep fixture assertions focused on stable data such as provider names, active profile, backup count, and typed error codes.
+
+## Reporting Template
+
+Use this template for release checks:
+
+```text
+Version under test: 0.0.x
+Build: PASS/FAIL
+Suite results:
+- domain: PASS/FAIL
+- app: PASS/FAIL
+- cli: PASS/FAIL
+- dev-sandbox: PASS/FAIL
+- e2e: PASS/FAIL
+
+Read-only smoke checks:
+- list/current/status/config/backups/doctor
+
+Mutation checks:
+- switch/rollback/add/edit/remove/import/export/setup
+
+Open risks:
+- <risk 1>
+- <risk 2>
+```
+
+## Current Gaps
+
+Known areas that still deserve more coverage:
+
+- true subprocess coverage for `setup`
+- explicit tests for `rollback-latest`
+- more backup corruption cases inside historical manifests
+- README and release docs should stay in sync with the package version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minniexcode/codex-switch",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Local-first CLI for managing and switching Codex provider/profile configuration.",
   "license": "MIT",
   "type": "commonjs",