@minniexcode/codex-switch 0.0.6 → 0.0.8

package/docs/cli-usage.md

@@ -89,7 +89,7 @@ CLI 的交互行为遵循以下规则：
 
 典型受影响命令包括：
 
-- `setup`
+- `migrate`
 - `add`
 - `edit`
 - `switch`
@@ -207,41 +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` 的 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。
 
@@ -272,13 +320,13 @@ codexs add
 - 如果缺少 `provider`、`profile`、`apiKey`，会在 TTY 中补问
 - profile 选择会优先复用现有 `config.toml` profile
 - API key 的隐藏输入会做二次确认
-- tag 支持预设多选和自定义逗号分隔输入
+- tag 仅支持预设选项多选
 
 非交互模式：
 
 - 必须显式传入所有必填字段
 
-### 5.3 `edit`
+### 5.5 `edit`
 
 编辑单个 provider 的字段。
 
@@ -309,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 记录。
 
@@ -370,7 +414,7 @@ codexs remove freemodel --force --json
 
 - 必须同时传入 `<provider>` 和 `--force`
 
-### 5.6 `import`
+### 5.8 `import`
 
 从外部 JSON 文件导入 provider 配置。
 
@@ -401,7 +445,7 @@ codexs import ./providers.json --merge --json
 - 不会弹出路径向导或确认框
 - 会先验证输入文件，再执行写入
 
-### 5.7 `export`
+### 5.9 `export`
 
 导出当前 `providers.json` 到指定文件。
 
@@ -499,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
 ```
@@ -509,7 +553,8 @@ codexs rollback 20260511-221457-switch --json
 ### 8.1 第一次接管现有 Codex 配置
 
 ```bash
-codexs setup
+codexs init
+codexs migrate
 codexs list
 codexs doctor
 ```
@@ -547,7 +592,8 @@ codexs rollback <backup-id>
 
 以下命令会修改本地配置或覆盖文件，使用前应明确预期：
 
-- `setup`
+- `init`
+- `migrate`
 - `add`
 - `edit`
 - `switch`
@@ -573,6 +619,8 @@ codexs --help
 也可以查看单个命令帮助：
 
 ```bash
+codexs help init
+codexs help migrate
 codexs help setup
 codexs help add
 codexs help switch

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

package/docs/testing.md

@@ -1,12 +1,12 @@
 # Testing Guide
 
-`codex-switch` now has four test layers:
+`codex-switch` currently ships with five active 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`
+- `tests/commands.spec.js`: argument parsing, help rendering, and command dispatch contracts
+- `tests/cli-e2e.spec.js`: built CLI entrypoint checks for user-visible command behavior and rendered output
+- `tests/interaction.spec.js`: prompt boundary and interactive data collection behavior
+- `tests/runtime.spec.js`: Codex runtime probing and version checks
+- `tests/workflows.spec.js`: file-backed app workflow coverage for write operations and rollback paths
 
 ## Commands
 
@@ -22,11 +22,18 @@ Run the full suite:
 npm test
 ```
 
-Run a single suite manually:
+`npm test` is not compile-only. It runs:
 
 ```bash
-node -e "require('./tests/dev-sandbox.spec').run()"
-node -e "require('./tests/e2e.spec').run()"
+npm run build
+node tests/run-tests.js
+```
+
+Run one suite manually:
+
+```bash
+node -e "require('./tests/cli-e2e.spec').tests[0].run()"
+node -e "require('./tests/workflows.spec').tests[0].run()"
 ```
 
 ## Development Fixture
@@ -39,61 +46,74 @@ 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
+- read-oriented CLI subprocess tests point at it directly
+- write-oriented tests copy it into a temporary directory before running mutations
 
 Do not point destructive automation directly at `dev-codex/local-sandbox` unless you intentionally want to update the fixture.
 
-## Read-Only Smoke Tests
+## Built CLI Coverage
+
+`tests/cli-e2e.spec.js` executes the built CLI entrypoint logic from `dist/` and asserts the same JSON and human-readable payloads users see.
 
-`tests/dev-sandbox.spec.js` verifies the built CLI against the real development fixture.
+Covered entrypoint checks:
 
-Covered commands:
+- `--help`
+- `--version`
+
+Covered read commands against the repository sandbox:
 
 - `list --json`
+- `show --json`
 - `current --json`
 - `status --json`
 - `config show --json`
+- `config list-profiles --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`
+Covered write commands against temporary sandbox copies:
 
-This is the fastest way to validate that `0.0.x` builds still read the repo sandbox correctly.
+- `init --json`
+- `add --json`
+- `add --create-profile --json`
+- `edit --json`
+- `switch --json`
+- `remove --force --json`
+- `import --json`
+- `export --force --json`
+- `rollback --json`
+- `setup --json`
 
-## Mutation Regression Tests
+Covered non-interactive failure contracts:
 
-`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.
+- `add` without an existing profile or `--create-profile`
+- blocking destructive removal of the active provider profile
+- `rollback <missing-id>`
+- `migrate --overwrite --json`
+- `setup --json`
 
-Covered write scenarios:
+This harness intentionally avoids `child_process` subprocess spawning because the current Windows sandbox used by automation blocks nested process launches with `EPERM`. The suite still validates the built CLI layer rather than calling app functions directly.
 
-- `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`
+## Workflow Coverage
 
-It also includes mixed workflow scenarios where multiple commands operate on the same sandbox copy end-to-end, for example:
+`tests/workflows.spec.js` keeps the deeper file-backed mutation coverage at the app/dispatch layer.
 
-- `add -> switch -> edit -> show -> config show -> export -> rollback`
-- `import --merge -> switch --no-login -> remove -> doctor -> backups list -> rollback <backup-id>`
+Important workflow scenarios already covered there include:
 
-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.
+- non-interactive `init`
+- non-interactive `migrate` failure behavior
+- interactive `migrate` adoption via injected runtime
+- `add`, `edit`, `remove`
+- `switch` plus rollback
+- `export` and `import`
+- auth write rollback on failure
 
 ## 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.
+- If a test needs `codex login` or `codex --version`, prefer mocking the spawn layer instead of assuming an installed local binary.
 - Keep fixture assertions focused on stable data such as provider names, active profile, backup count, and typed error codes.
 
 ## Reporting Template
@@ -104,17 +124,17 @@ Use this template for release checks:
 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
+- commands: PASS/FAIL
+- cli-e2e: PASS/FAIL
+- interaction: PASS/FAIL
+- runtime: PASS/FAIL
+- workflows: PASS/FAIL
 
-Read-only smoke checks:
-- list/current/status/config/backups/doctor
+Read command checks:
+- help/version/list/show/current/status/config/backups/doctor
 
 Mutation checks:
-- switch/rollback/add/edit/remove/import/export/setup
+- init/add/edit/switch/remove/import/export/rollback/migrate/setup
 
 Open risks:
 - <risk 1>
@@ -125,7 +145,7 @@ Open risks:
 
 Known areas that still deserve more coverage:
 
-- true subprocess coverage for `setup`
+- true subprocess automation for interactive TTY-only flows such as prompt-driven `migrate`
 - explicit tests for `rollback-latest`
 - more backup corruption cases inside historical manifests
-- README and release docs should stay in sync with the package version
+- docs and report snapshots should stay in sync with the current package version

package/package.json

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