@minniexcode/codex-switch 0.0.11 → 0.0.12

package/docs/PRD/codex-switch-prd-v0.1.0.md

@@ -1,135 +1,66 @@
-# codex-switch `0.0.6` PRD
+# codex-switch `0.1.0` Release Gate PRD
 
 ## 文档信息
 
-- 状态：Active PRD
+- 状态：Release Gate Draft
 - 产品名：`codex-switch`
 - CLI 命令名：`codexs`
-- 当前基线版本：`0.0.5`
-- 目标版本：`0.0.6`
-- 文档定位：定义 `0.0.5 -> 0.0.6` 的直接需求范围
-- 历史基线 PRD：[`codex-switch-prd.md`](./codex-switch-prd.md)
-- 后续演进 PRD：[`codex-switch-prd-v0.0.5-to-v0.1.0.md`](./codex-switch-prd-v0.0.5-to-v0.1.0.md)
-- 对应研究稿：[`../codex-switch-product-research.md`](../codex-switch-product-research.md)
-- 对应技术架构：[`../codex-switch-technical-architecture.md`](../codex-switch-technical-architecture.md)
-- 对应命令设计：[`../codex-switch-command-design.md`](../codex-switch-command-design.md)
-
-说明：
-
-- 当前文件路径仍沿用历史命名 `codex-switch-prd-v0.1.0.md`
-- 本文档内容语义以当前 active PRD 为准，本次版本更新不处理文件重命名
+- 当前预发布基线：`0.0.12` beta
+- 目标版本：`0.1.0`
+- 文档定位：定义 `codex-switch` 何时可以从 `0.0.x` 进入第一个正式稳定发布版本
+- 关联 beta PRD：[`./codex-switch-prd-v0.0.12.md`](./codex-switch-prd-v0.0.12.md)
+- 关联长期演进稿：[`./codex-switch-prd-v0.0.5-to-v0.1.0.md`](./codex-switch-prd-v0.0.5-to-v0.1.0.md)
 
 ## 一句话定义
 
-`0.0.6` 的目标不是继续扩张命令面，而是先修复 `0.0.5` 的功能稳定性问题，冻结当前 CLI 公共契约，并把实现从“单入口持续膨胀的命令调度器”收敛为适合继续扩展的模块化分层架构。
-
-## 当前基线：`0.0.5`
-
-当前已具备的命令面：
-
-- `config-show`
-- `config-list-profiles`
-- `list`
-- `show`
-- `current`
-- `status`
-- `setup`
-- `edit`
-- `add`
-- `switch`
-- `remove`
-- `import`
-- `export`
-- `backups`
-- `doctor`
-- `rollback`
-
-当前基线已具备的工程特征：
-
-- `providers.json` 继续作为管理态单一事实源
-- `config.toml` 具备结构化读取与受管 section 写入能力
-- 写命令统一走锁、备份、失败回滚
-- `--json` 继续使用统一 envelope
-- CLI 帮助页已经具备稳定命令分组和文案基础
-
-当前主要问题：
-
-- `0.0.5` 需要继续收敛边界行为和失败语义，提升已有功能的稳定性
-- `src/cli.ts` 已经承担过多命令分发、交互编排和参数补全逻辑
-- 当前四层结构仍然成立，但 CLI 入口和应用编排层需要进一步细化职责
-- 未来第三方 auth / 本地代理 / 外部依赖接入已具备现实需求，但当前扩展边界还不够明确
-
-## `0.0.6` 目标
-
-`0.0.6` 需要完成三件事：
-
-- 修复 `0.0.5` 命令行为中的稳定性问题，巩固已有能力
-- 重整 CLI 与应用层分层，解决 `cli.ts` 持续膨胀问题
-- 为未来第三方 auth / 本地 proxy / 外部 SDK 集成建立清晰边界，但本版不交付这些集成功能
-
-## 范围
-
-### In Scope
-
-- 现有命令面的稳定性修复与一致性收敛
-- 顶层 help 文案、命令分组、示例和危险提示的一致性
-- `--json` 契约、TTY 交互规则、非交互失败语义的一致性
-- `setup` / `add` / `edit` / `remove` / `import` / `export` / `switch` / `rollback` 的事务与恢复稳定性
-- `status` / `doctor` / `config-show` / `config-list-profiles` 的读取稳定性
-- CLI 入口再分层
-- 应用编排与运行时集成边界收敛
-- 为未来第三方 integration 预留明确架构边界
-
-### Out of Scope
+`0.1.0` 不是“功能再多一点”的版本，而是 `codex-switch` 第一条可正式对外承诺的稳定产品线：命令入口稳定、输出契约稳定、主工作流清晰、恢复与诊断可信、文档与包内容一致。
 
-- 新增大型命令族
-- 真实 Copilot auth 登录接入
-- 本地代理服务启动、停止、守护和生命周期管理
-- 第三方 SDK 安装器或依赖下载体验
-- GUI / TUI / daemon 化
-- 把 `config.toml` 升级为通用配置编辑器
+## 发布语义
 
-## 稳定公共契约
+一旦进入 `0.1.0`，这个版本就不再只是“作者自己知道怎么用”的工具，而需要满足：
 
-### CLI 命令面
+- 新用户看 README 与 help 就能走通主路径
+- 自动化调用方可以信赖 `--json` 的稳定契约
+- direct provider 和 Copilot provider 都有明确、可解释、可恢复的工作流
+- 文档、包内容、help、测试和实际行为是同一套事实
 
-`0.0.6` 默认锁定当前 help 所表达的命令面与分组，不以“新增命令数量”作为版本目标。
+`0.1.0` 不是自动升级目标。只有当 release gate 满足时，才允许发布。
 
-Usage 级别的公共入口保持：
+## `0.1.0` 必须稳定的内容
 
-```text
-codexs <command> [options]
-codexs help <command>
-```
-
-当前命令分组继续保留：
+### 1. CLI 命令面
 
-- Read Commands
-- Change Commands
-- Diagnostics And Recovery
+以下命令面在 `0.1.0` 时视为稳定：
 
-当前命令名继续保留：
-
-- `config-show`
-- `config-list-profiles`
+- `init`
+- `login`
 - `list`
 - `show`
 - `current`
 - `status`
-- `setup`
-- `edit`
+- `doctor`
+- `config show`
+- `config list-profiles`
 - `add`
+- `edit`
 - `switch`
 - `remove`
 - `import`
 - `export`
-- `backups`
-- `doctor`
+- `bridge start`
+- `bridge status`
+- `bridge stop`
+- `backups list`
 - `rollback`
 
-### JSON Envelope
+说明：
 
-`--json` 继续保持统一 envelope：
+- `setup` 可以继续保留为 deprecated entry
+- `migrate` 可以继续保留，但其“高级 adopt 工具”定位必须明确
+
+### 2. JSON Envelope
+
+`--json` 顶层 envelope 在 `0.1.0` 前必须冻结为：
 
 ```json
 {
@@ -143,175 +74,132 @@ codexs help <command>
 
 要求：
 
-- 顶层 shape 不变
-- 新字段只追加到 `data` / `warnings`
-- 错误信息继续进入 `error`
-- 架构重构不得破坏已有自动化消费方式
-
-### 交互规则
-
-交互能力继续只是 TTY 中的人类增强层，不改变自动化契约：
-
-- `--json` 一律禁用交互
-- 非 TTY 一律不进入交互
-- 危险写命令继续要求显式确认或显式参数
-- 用户取消 prompt 时不得产生文件写入
-
-## 数据与状态边界
-
-### `providers.json`
+- 顶层字段不改名
+- 顶层 shape 不重排
+- 新信息只允许追加到 `data`、`warnings` 或 `error.details`
 
-`providers.json` 继续是 provider registry 的单一事实源：
+### 3. 双路径模型
 
-- `profile` 必填
-- `apiKey` 仍按完整 managed provider 处理
-- 不引入“半初始化 provider”作为稳定状态
+`0.1.0` 前必须把以下边界视为正式产品 contract：
 
-### `config.toml`
+- tool home：
+  - `codex-switch.json`
+  - `providers.json`
+  - `backups/`
+  - `runtime/`
+  - `runtimes/`
+- target Codex runtime：
+  - `config.toml`
+  - `auth.json`
 
-到 `0.0.6` 为止，`config.toml` 的定位继续保持：
+其中：
 
-- 顶层 active `profile`
-- 与 provider 关联的 `[profiles.<name>]`
-- 第一批受管字段：`model`、`model_provider`
-- 非受管内容允许存在，但不进入通用编辑器范围
+- `providers.json` 是管理态 SSOT
+- `config.toml` 是受管 runtime routing 文件
+- `auth.json` 是受管 auth projection 文件
 
-### `auth.json`
+### 4. 主工作流
 
-`auth.json` 继续是认证态运行时文件：
+#### Direct Provider
 
-- 可以被 `switch`、`rollback`、备份系统纳入事务边界
-- 不是 provider registry 的事实源
-- 不在 `0.0.6` 中扩展为第三方 auth 统一数据库
+正式推荐路径必须清晰稳定：
 
-## 架构目标边界
-
-### 现状问题
-
-当前 `cli / app / domain / infra` 四层结构仍然是可用基线，但 `cli.ts` 已同时承担：
-
-- 命令分发
-- 参数归一化
-- 交互分支判断
-- 渐进式补问
-- 输出路径拼装
-
-这会让后续每增加一个命令或 integration，都继续把复杂度堆回 CLI 入口。
-
-### `0.0.6` 架构调整目标
-
-`0.0.6` 不要求彻底推翻现有分层，但要求把职责边界进一步显式化，至少收敛为下面几类模块能力：
-
-- `Command Surface`
-  - 负责命令定义、help 文案、命令 key、参数规格、子命令分发
-- `Interaction Layer`
-  - 负责 TTY prompt、危险确认、渐进式补问、交互取消语义
-- `Application Use Cases`
-  - 负责单命令业务编排、跨仓储事务边界、结果契约组装
-- `Domain Policies`
-  - 负责 provider/profile/config consistency 规则、错误码、纯规则判断
-- `Storage Repositories`
-  - 负责 `providers.json`、`config.toml`、backups 的文件访问和持久化
-- `Runtime Integrations`
-  - 负责 `codex` CLI 调用，以及未来第三方 auth adapter、本地 proxy runtime、外部 SDK 封装
-
-### 架构约束
-
-`0.0.6` 需要明确以下约束：
-
-- 不把第三方 SDK 调用直接塞进 CLI 入口
-- 不把 prompt 逻辑继续散落到每个命令分支内部
-- 不让 `app` 层直接依赖终端输出细节
-- 不让运行时集成逻辑反向污染领域规则
-- 不因未来接入 Copilot 或其他 provider，就改变本地事务与回滚的安全语义
-
-## `0.0.6` 稳定性要求
-
-### 命令行为一致性
+```bash
+codexs init
+codexs add <provider> --profile <name> --api-key <key>
+codexs switch <provider>
+codexs status
+codexs doctor
+```
 
-现有命令在 `0.0.6` 需要重点收敛：
+#### Copilot Provider
 
-- help 文案与真实命令行为一致
-- 默认文本输出与 `--json` 输出语义一致
-- TTY 与非交互模式下的失败路径可预测
-- 危险命令的确认规则一致
-- 同一类错误优先映射到同一类错误码
+正式推荐路径必须清晰稳定：
 
-### 写命令安全语义
+```bash
+codexs init
+codexs login copilot
+codexs add <provider> --copilot --profile <name>
+codexs switch <provider>
+codexs status
+codexs doctor
+```
 
-所有会修改 `providers.json`、`config.toml`、`auth.json` 的命令继续默认遵守：
+#### `migrate`
 
-- 单次锁
-- 单次备份
-- 单次失败整体回滚
+`migrate` 在 `0.1.0` 可以保留，但必须满足：
 
-不能接受的结果：
+- 产品定位明确为高级 adopt helper
+- 不与 fresh install 主路径混淆
+- 文档不把它写成所有用户都应先执行的默认第一步
 
-- `providers.json` 已更新但 `config.toml` 未同步
-- `config.toml` 已更新但 `providers.json` 未同步
-- `auth.json` 或 active profile 因失败留在半切换状态
+## Release Gate
 
-### 读取稳定性
+只有以下条件全部满足，才允许发布 `0.1.0`：
 
-读取命令在 `0.0.6` 至少需要满足：
+### A. 工作流可信
 
-- 不因历史 workspace 或边缘状态轻易崩溃
-- `status` 与 `doctor` 的诊断信号保持一致语义
-- `config-show` 与 `config-list-profiles` 输出结构稳定
-- 对缺失文件、解析失败和不一致状态给出可预测错误或警告
+- direct provider 主路径可在 fresh tool home 下稳定走通
+- Copilot 主路径可在 fresh tool home 下稳定走通
+- `switch` 成功语义仍然等于 config + auth 投影都正确
+- `rollback` 对受管写操作仍然可信
 
-## Future-Ready Integration 边界
+### B. 输出可信
 
-### 为什么 `0.0.6` 要预留这条线
+- `--json` 读命令输出稳定
+- 非交互模式不会意外 prompt
+- 错误码和 issue code 对常见失败场景足够稳定
+- `status` 与 `doctor` 输出能解释下一步修复动作
 
-未来存在明确扩展需求：
+### C. 文档可信
 
-- 通过第三方 auth 获取认证态
-- 借助本地代理使特定上游可在 Codex 中使用
-- 接入外部 SDK，例如 GitHub Copilot 相关能力
+- README、README.CN、README.AI、CLI usage、product overview、PRD、changelog 与实际行为一致
+- 不再残留旧 `~/.codex/providers.json` / `backups/` 叙述
+- 主路径在所有面向用户的文档中一致
 
-如果继续沿用当前“命令直接长在 `cli.ts` 上”的方式，后续集成会快速把架构拖回高耦合状态。
+### D. 包内容可信
 
-### `0.0.6` 的预留目标
+- `npm pack --dry-run` 结果合理
+- tarball 中包含正确的 README、LICENSE、docs、dist
+- `codexs --help`、`codexs --version`、安装指引与 npm 包元数据一致
 
-本版只要求建立边界，不要求交付真实功能：
+### E. 结构可信
 
-- 允许未来把第三方 auth 封装为独立 integration 模块
-- 允许未来把本地 proxy runtime 封装为独立运行时组件
-- 允许未来把外部依赖探测、可用性检查、错误语义收敛到 runtime integration 层
-- 不在本版锁定具体命令名、交互细节或 SDK 选型细节
+- 不再保留明显误导性的历史目录语义
+- 关键稳定模块有足够 JSDoc 和边界说明
+- 新问题不再需要反复回到超大入口文件做修补
 
-### Copilot 作为代表性场景
+## 明确不要求 `0.1.0` 完成的内容
 
-GitHub Copilot 相关 auth / SDK / 本地代理能力，在 `0.0.6` 里的定位是：
+以下内容不是 `0.1.0` 的发布前置条件：
 
-- 作为未来架构设计的代表性输入
-- 用于验证 `Runtime Integrations` 分层是否足够清晰
-- 不作为 `0.0.6` 必须实现的命令需求
+- 新 upstream
+- GUI / TUI
+- daemon / background supervisor
+- plugin system
+- 多账号平台
+- 自动迁移旧状态
+- `migrate` 的完整非交互产品化
+- 通用 `config.toml` 编辑器
 
-## 对实现的要求
+## 若 Release Gate 未通过
 
-从 `0.0.5` 到 `0.0.6` 的改造，默认遵守：
+如果以下任一问题仍明显存在，则不应强行发布 `0.1.0`：
 
-- 不破坏现有命令名
-- 不破坏统一 JSON envelope
-- 不破坏备份、回滚、锁模型
-- 不引入只能靠交互完成的核心流程
-- 不把未来第三方集成耦合进当前 provider/config 领域规则
-- 允许内部文件和模块重组，但外部 CLI 契约保持稳定
+- 文档和行为仍有明显漂移
+- `migrate` 与主路径仍然混淆
+- Copilot 路径仍需要过多背景知识才能理解
+- 回滚与诊断场景仍存在不稳定或不可解释行为
+- 包内容、安装体验或帮助页仍像开发中工具
 
-## 验收标准
+此时应继续发布：
 
-达到以下条件时，`0.0.6` 可以认为完成：
+- `0.0.13`
+- `0.0.14`
+- 其他后续 beta / rc 版本
 
-- 当前 help 文案与命令行为、参数、危险提示基本一致
-- 现有命令在 TTY / 非交互 / `--json` 模式下行为稳定
-- 读取命令对历史状态和异常状态的处理更稳，不产生明显回归
-- 写命令继续满足锁、备份、失败回滚语义
-- `cli.ts` 不再承担持续膨胀的主调度与交互编排复杂度
-- 应用编排、交互层、运行时集成边界比 `0.0.5` 更清晰
-- 为未来第三方 auth / 本地 proxy / SDK 接入预留了清楚但非侵入式的扩展边界
+而不是为了版本号好看提前进入 `0.1.0`。
 
 ## 结论
 
-`0.0.6` 是一个修复型版本，但它不是“只修 bug 不动结构”的保守补丁版。它的真正目标，是在不破坏当前 CLI 公共契约的前提下，把 `0.0.5` 已经长出来的命令面和事务能力稳住，并把代码结构调整到足以支撑下一阶段 integration-ready 演进的状态。
+`0.1.0` 的意义，不在于“项目终于到 1.0 之前先过一个数字门槛”，而在于 `codex-switch` 首次具备了可以向外明确承诺的稳定产品边界。只有当工作流、输出、恢复、文档和包发布面都同时稳定时，这个版本号才成立。

package/docs/Tests/testing.md

@@ -1,127 +1,62 @@
 # Testing Guide
 
-`codex-switch` currently ships with five active test layers:
+Version under test: `0.0.12`
 
-- `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
+这份文档同时是测试说明和 beta release checklist。
 
-## Commands
+## Active Suites
 
-Build the CLI:
+- `tests/commands.spec.js`: argument parsing, help rendering, and command registry contract
+- `tests/cli-e2e.spec.js`: built CLI help/version plus human-readable and JSON output behavior
+- `tests/interaction.spec.js`: prompt boundaries
+- `tests/runtime.spec.js`: runtime probing behavior
+- `tests/workflows.spec.js`: file-backed mutation and rollback behavior
 
-```bash
-npm run build
-```
-
-Run the full suite:
-
-```bash
-npm test
-```
-
-`npm test` is not compile-only. It runs:
+## Required Commands
 
 ```bash
 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
-
-The repository fixture lives at:
-
-```text
-dev-codex/local-sandbox/
+npm test
+npx tsc --noEmit
+npm pack --dry-run
 ```
 
-It is used in two different ways:
-
-- 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.
-
-## 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.
+## Release Checklist
 
-Covered entrypoint checks:
-
-- `--help`
-- `--version`
-
-Covered read commands against the repository sandbox:
+Read checks:
 
+- built CLI `--help`
+- built CLI `--version`
 - `list --json`
-- `show --json`
-- `current --json`
 - `status --json`
-- `config show --json`
-- `config list-profiles --json`
-- `backups list --json`
 - `doctor --json`
 
-Covered write commands against temporary sandbox copies:
-
-- `init --json`
-- `add --json`
-- `add --create-profile --json`
-- `edit --json`
-- `switch --json`
-- `remove --force --json`
-- `import --json`
-- `export --force --json`
-- `rollback --json`
-- `setup --json`
-
-Covered non-interactive failure contracts:
+Primary workflow checks:
 
-- `add` without an existing profile or `--create-profile`
-- blocking destructive removal of the active provider profile
-- `rollback <missing-id>`
-- `migrate --overwrite --json`
-- `setup --json`
+- fresh tool home direct path
+- fresh tool home Copilot path
+- read commands in `--json`
+- write commands in sandbox
 
-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.
+Specific `0.0.12` checks:
 
-## Workflow Coverage
+- top-level help shows direct primary workflow before `migrate`
+- `migrate` is clearly presented as advanced adopt
+- `setup` remains deprecation-only
+- human-readable `init` output shows tool home, tool config, and providers registry
+- human-readable `status` output shows tool home and target runtime
+- human-readable `doctor` output is repair-oriented
+- `--version` matches `package.json.version`
 
-`tests/workflows.spec.js` keeps the deeper file-backed mutation coverage at the app/dispatch layer.
+## Test Limits
 
-Important workflow scenarios already covered there include:
-
-- 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 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.
+- `login copilot` depends on SDK install, official CLI invocation, and auth recheck. Automation should distinguish mocked coverage from real-environment validation.
+- `migrate` remains intentionally interactive for adopt detail collection. Non-interactive tests should verify the current failure contract rather than force a fake full automation path.
 
 ## Reporting Template
 
-Use this template for release checks:
-
 ```text
-Version under test: 0.0.x
+Version under test: 0.0.12
 Build: PASS/FAIL
 Suite results:
 - commands: PASS/FAIL
@@ -130,22 +65,14 @@ Suite results:
 - runtime: PASS/FAIL
 - workflows: PASS/FAIL
 
-Read command checks:
-- help/version/list/show/current/status/config/backups/doctor
-
-Mutation checks:
-- init/add/edit/switch/remove/import/export/rollback/migrate/setup
+Release checks:
+- help/version: PASS/FAIL
+- direct path: PASS/FAIL
+- copilot path: PASS/FAIL
+- json reads: PASS/FAIL
+- sandbox writes: PASS/FAIL
 
 Open risks:
 - <risk 1>
 - <risk 2>
 ```
-
-## Current Gaps
-
-Known areas that still deserve more coverage:
-
-- 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
-- docs and report snapshots should stay in sync with the current package version