@minniexcode/codex-switch 0.1.1 → 0.1.2

package/docs/Design/codex-switch-v0.1.2-design.md

@@ -0,0 +1,65 @@
+# codex-switch v0.1.2 Design
+
+## Purpose
+
+`0.1.2` repairs the Copilot runtime integration while keeping direct-provider support unchanged.
+
+## SDK Runtime
+
+- The managed installer installs `@github/copilot-sdk@1.0.2`.
+- `loadCopilotSdk()` resolves `@github/copilot-sdk` from the managed runtime package using `createRequire()`.
+- Copilot-specific paths call a Node gate before mutation or bridge startup. Node.js `<20` fails with `COPILOT_RUNTIME_NODE_UNSUPPORTED`.
+- `probeCopilotSdkRuntime()` classifies missing installs, unsupported versions, and prerelease installs before runtime use.
+- SDK API-shape validation happens later when creating the client or session.
+
+## SDK API Contract
+
+The supported runtime/session shape is:
+
+- `CopilotClient`
+- `CopilotClient.getAuthStatus()`
+- `CopilotClient.createSession()`
+- `CopilotSession.sendAndWait()` when present, otherwise `CopilotSession.send()`
+- `CopilotSession.abort()`
+- `CopilotSession.disconnect()` only as best-effort cleanup
+- SDK `approveAll` or compatible permission handler
+
+Auth readiness uses `getAuthStatus()` and does not create a session just to test login state. `abort()` is a required compatibility surface; `disconnect()` is not a required compatibility gate.
+
+## Bridge Worker
+
+The parent process passes both runtime state and SDK runtime directories into the worker. The worker creates one long-lived `CopilotClient`, starts it once, and serializes incoming requests through a promise queue. Each request gets its own session, uses `abort()` for timeout and cancellation control, and attempts `disconnect()` after completion as best-effort cleanup.
+
+## Request Mapping
+
+The bridge remains a minimal OpenAI-compatible adapter:
+
+- `/v1/chat/completions` maps messages to a text prompt.
+- `/v1/responses` accepts string input, message arrays, or typed top-level content-item arrays and maps those text-oriented shapes to the same prompt path.
+- `model` is passed to `createSession({ model })`.
+- Mixed top-level arrays are rejected as unsupported input.
+- `sendAndWait()` receives `{ prompt }` and the request timeout when available; otherwise the bridge falls back to `send()`.
+
+Non-text Responses content is represented as readable placeholders. Complex tool-call round trips are outside the `0.1.2` guarantee.
+
+## Streaming
+
+Streaming Responses requests emit `response.created`, `response.in_progress`, output item/content part setup events, text deltas, done events, and `response.completed`. The bridge writes initial SSE bytes before the upstream response completes and emits comment heartbeats every 15 seconds while waiting.
+
+## Error Mapping
+
+- Unsupported request shapes return `400`.
+- Auth-required failures return `401`.
+- Upstream timeouts return `504`.
+- Other bridge runtime failures return `500`.
+
+## Config Projection
+
+Copilot provider projection includes:
+
+```toml
+wire_api = "responses"
+stream_idle_timeout_ms = 300000
+```
+
+Direct provider projection does not add `stream_idle_timeout_ms`.

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

@@ -1,217 +1,65 @@
-# codex-switch `0.1.0` Release Gate PRD
-
-## 文档信息
-
-- 状态：Release Gate
-- 产品名：`codex-switch`
-- CLI 命令名：`codexs`
-- 当前稳定基线：`0.0.12`
-- 目标版本：`0.1.0`
-- 文档定位：定义 `codex-switch` 第一次稳定发布前必须满足的门槛
-- 关联 beta PRD：[`./codex-switch-prd-v0.0.12.md`](./codex-switch-prd-v0.0.12.md)
-- 关联实现约束设计：[`../Design/codex-switch-v0.1.0-design.md`](../Design/codex-switch-v0.1.0-design.md)
-- 关联长期演进稿：[`./codex-switch-prd-v0.0.5-to-v0.1.0.md`](./codex-switch-prd-v0.0.5-to-v0.1.0.md)
-
-## 1. 定位
-
-`0.1.0` 是 `codex-switch` 的第一条稳定发布线，不是继续扩 feature surface 的版本，也不是把 `0.0.12` 再包装一次。
-
-这个版本的判断标准只有一个：当前仓库已经足够稳定，能把命令面、输出契约、主工作流、诊断语义和文档事实对外固定下来，并且不需要再依赖开发期解释来“补全理解”。
-
-## 2. 当前阻塞项
-
-以下问题仍然阻止 `0.1.0` 成为真正可发布的稳定版本：
-
-1. `tests/` 被忽略，导致测试无法被版本化和审阅。
-2. README 里仍有失效的 `docs/Tests/testing.md` 链接，用户会直接遇到死链。
-3. 版本叙事仍停留在 `0.0.12`，对外材料没有把 `0.1.0` 讲成稳定发布线。
-4. 发布故事和实现状态还没有完全对齐，尤其是主工作流、`migrate` 定位和 `setup` 定位。
-
-这些阻塞项必须先被收口，`0.1.0` 才能成立。
-
-## 3. `0.1.0` 的稳定合同
-
-`0.1.0` 必须把以下内容视为稳定合同，不再当作可随意重写的草案。
-
-### 3.1 命令面
-
-稳定命令面包括：
-
-- `init`
-- `login`
-- `list`
-- `show`
-- `current`
-- `status`
-- `doctor`
-- `config show`
-- `config list-profiles`
-- `add`
-- `edit`
-- `switch`
-- `remove`
-- `import`
-- `export`
-- `bridge start`
-- `bridge status`
-- `bridge stop`
-- `backups list`
-- `rollback`
-
-其中：
-
-- `migrate` 只能是高级 adopt helper。
-- `setup` 只能是 deprecated entry。
-
-### 3.2 `--json` envelope
-
-`--json` 的顶层 envelope 必须保持不变：
-
-```json
-{
-  "ok": true,
-  "command": "list",
-  "data": {},
-  "warnings": [],
-  "error": null
-}
-```
-
-约束如下：
-
-- 顶层字段名不变。
-- 顶层字段顺序和 shape 不变。
-- 新信息只能继续追加到 `data`、`warnings` 或 `error.details`。
-
-### 3.3 dual-path model
-
-`0.1.0` 必须把以下分层固定为正式合同：
-
-- tool home：
-  - `codex-switch.json`
-  - `providers.json`
-  - `backups/`
-  - `runtime/`
-  - `runtimes/`
-- target Codex runtime：
-  - `config.toml`
-  - `auth.json`
-
-含义必须稳定：
-
-- `providers.json` 是管理态 SSOT。
-- `config.toml` 是受管 runtime routing 文件。
-- `auth.json` 是受管 auth projection 文件。
-
-### 3.4 主工作流
-
-Direct provider 主路径：
-
-```bash
-codexs init
-codexs add <provider> --profile <name> --api-key <key>
-codexs switch <provider>
-codexs status
-codexs doctor
-```
-
-Copilot provider 主路径：
-
-```bash
-codexs init
-codexs login copilot
-codexs add <provider> --copilot --profile <name>
-codexs switch <provider>
-codexs status
-codexs doctor
-```
-
-`migrate` 的定位必须明确为：
-
-- 面向已有 runtime state 的高级 adopt helper。
-- 不应与 fresh install 主路径混淆。
-- 不应被写成所有新用户都应先执行的默认步骤。
-
-## 4. Release Gate
-
-只有以下条件全部满足，才允许发布 `0.1.0`。
-
-### 4.1 工作流
-
-- fresh tool home 下 direct provider 主路径可稳定走通。
-- fresh tool home 下 Copilot 主路径可稳定走通。
-- `switch` 的成功语义仍然等于 config 和 auth projection 都正确。
-- `rollback` 对受管写操作仍然可信。
-
-### 4.2 输出与语义
-
-- `--json` 读命令输出稳定。
-- 非交互模式不会意外触发 prompt。
-- 错误码和 issue code 对常见失败场景足够稳定。
-- `status` 与 `doctor` 能清楚说明下一步修复动作。
-- `list`、`status`、`doctor` 的人类可读输出和交互提示一致。
-
-### 4.3 文档
-
-- README、README.CN、README.AI、CLI usage、product overview、PRD、design 和 changelog 与实际行为一致。
-- `docs/Tests/testing.md` 不能继续停留在忽略状态，测试回归必须落仓库并可版本化。
-- 主路径在所有面向用户的文档中必须一致。
-- `0.1.0` 的定位必须压过旧的 `0.0.12` 叙事。
-
-### 4.4 包内容
-
-- `npm pack --dry-run` 结果合理。
-- tarball 中包含正确的 README、LICENSE、docs、dist。
-- `codexs --help`、`codexs --version`、安装指引与 npm 包元数据一致。
-
-### 4.5 结构
-
-- 不再保留明显误导性的历史目录语义。
-- 稳定模块的边界说明足够清楚。
-- 新问题不再需要反复回到超大入口文件修补。
-
-## 5. 可执行验证清单
-
-`0.1.0` 的发布前验证必须至少覆盖以下项目：
-
-```bash
-npm run build
-npm test
-npx tsc --noEmit
-npm pack --dry-run
-node dist/cli.js --help
-node dist/cli.js --version
-```
-
-同时必须做以下行为验证：
-
-- fresh direct provider flow。
-- fresh Copilot provider flow。
-- `list/status/doctor` 语义检查。
-- `--json` 输出检查。
-- `migrate` 作为高级 adopt helper 的检查。
-- `setup` 作为 deprecated entry 的检查。
-
-## 6. 明确不在范围内
-
-`0.1.0` 不要求完成以下内容：
-
-- 新 upstream。
-- GUI / TUI。
-- daemon。
-- plugin system。
-- auto migration。
-- 兼容层。
-- dual-read / dual-write。
-- `migrate` 的完整非交互产品化。
-- 旧状态的自动升级保留逻辑。
-
-## 7. 若 Gate 未通过
-
-如果任何阻塞项仍然存在，就不要强行发布 `0.1.0`。
-
-此时应继续发布 beta 或 rc 版本，而不是为了版本号好看提前进入稳定线。
-
-## 8. 结论
-
-`0.1.0` 的本质不是“功能更多”，而是“承诺更稳”。当命令面、输出契约、主工作流、诊断语义、包内容和文档事实完全一致时，这个版本号才成立。
+# codex-switch v0.1.0 PRD
+
+## Status
+
+- Version line: `0.1.0`
+- Role: first stable documentation baseline
+- Scope: summarize the stable public contract already reached by the CLI
+
+## Product Contract
+
+`codex-switch` is a local-first CLI named `codexs` for managing Codex model-provider routes. It keeps tool-owned provider state separate from the target Codex runtime while projecting the selected provider into Codex-compatible `config.toml` and `auth.json` files.
+
+Stable user workflows:
+
+```bash
+codexs init
+codexs add <provider> --profile <model-provider-id> --api-key <key> --base-url <url> --model <model>
+codexs switch <provider>
+codexs status
+codexs doctor
+```
+
+```bash
+codexs init
+codexs login copilot
+codexs add <provider> --copilot --profile <model-provider-id> --model <model>
+codexs switch <provider>
+codexs status
+codexs doctor
+```
+
+## Stable Boundaries
+
+- Tool home owns `codex-switch.json`, `providers.json`, `backups/`, `runtime/`, and `runtimes/`.
+- Target Codex home owns the active `config.toml` and `auth.json` projection.
+- `providers.json` is the provider registry source of truth.
+- `config.toml` uses top-level `model` / `model_provider` plus `[model_providers.*]` sections.
+- `auth.json` receives the active Codex-facing bearer value as `OPENAI_API_KEY`.
+- Copilot upstream GitHub credentials are not stored in `providers.json` or target `auth.json`.
+
+## Stable Commands
+
+Stable command families include `init`, `login copilot`, `add`, `edit`, `switch`, `remove`, `list`, `show`, `current`, `status`, `doctor`, `config show`, `config list-profiles`, `import`, `export`, `bridge start`, `bridge status`, `bridge stop`, `backups list`, and `rollback`.
+
+`migrate` remains an advanced adopt helper for existing Codex state. `setup` is a deprecated compatibility entry that points users to `init` and `migrate`.
+
+## Output Contract
+
+JSON output keeps the top-level envelope:
+
+```json
+{
+  "ok": true,
+  "command": "status",
+  "data": {},
+  "warnings": [],
+  "error": null
+}
+```
+
+New information should be added under `data`, `warnings`, or `error.details` without changing the envelope.
+
+## Non-Goals
+
+`0.1.0` does not introduce automatic migration shims, a daemon, GUI/TUI, plugin system, new upstream families, or backward-compatibility dual-read paths for old development state.

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

@@ -0,0 +1,26 @@
+# codex-switch v0.1.1 PRD
+
+## Status
+
+- Version line: `0.1.1`
+- Role: documentation and fact-source completion release
+- Current package version: `0.1.1`
+
+## Goal
+
+`0.1.1` closes documentation gaps after the first stable line. It does not change the primary command surface. Its purpose is to make README, CLI usage, product overview, technical architecture, PRD, design, and changelog agree on the same current facts.
+
+## Requirements
+
+- Keep `0.1.0` as the stable product contract summary.
+- Add explicit `0.1.1` PRD and design fact sources so links from overview and architecture resolve.
+- Remove obsolete `0.0.x` transition docs from the active docs tree.
+- Keep Copilot described as a managed local bridge backed by the official GitHub Copilot runtime.
+- Clarify that direct providers remain the stable, generic path and that Copilot has additional runtime prerequisites.
+- Keep the development-version policy: no automatic migration or backward-compatibility shims unless a later task explicitly asks for them.
+
+## Acceptance
+
+- Public docs link only to current `0.1.0`, `0.1.1`, or planned `0.1.2` fact sources.
+- No public page points to removed `0.0.x` transition documents.
+- `npm test` and `npx tsc --noEmit` continue to pass.

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

@@ -0,0 +1,41 @@
+# codex-switch v0.1.2 PRD
+
+## Status
+
+- Version line: `0.1.2`
+- Status: release candidate
+- Current repository package version: `0.1.2`
+- Role: next Copilot runtime repair line
+- Scope: make the experimental Copilot bridge diagnosable and usable for simple text-oriented turns against the currently verified Codex runtime boundary, with `0.140.x` treated as a planning and verification target rather than a blanket compatibility guarantee
+
+## Problem
+
+The existing Copilot path treated `@github/copilot-sdk` as a simple chat/session SDK. The package is an official JSON-RPC control surface for GitHub Copilot CLI and has a stricter runtime contract than the previous integration assumed. It also requires Node.js `>=20`, while direct providers should continue to support Node.js `>=18`.
+
+## Requirements
+
+- Default the managed installer to `@github/copilot-sdk@1.0.2` instead of `latest`.
+- Keep package-level `engines.node >=18`, but fail Copilot-only paths early under Node.js `<20` with `COPILOT_RUNTIME_NODE_UNSUPPORTED`.
+- Load the SDK from the managed runtime install directory using `createRequire()`.
+- Probe auth through `CopilotClient.getAuthStatus()` rather than by creating a session.
+- Treat unsupported SDK versions and prerelease installs as explicit runtime failures before bridge use, with API-shape validation reported separately as `COPILOT_SDK_API_UNSUPPORTED` when the client or session is actually used.
+- Start the bridge worker with the same `runtimesDir` that passed parent readiness checks.
+- Keep one long-lived `CopilotClient` in the worker, create one session per request, require `abort()`, and attempt `disconnect()` as best-effort cleanup after the request.
+- Serialize bridge requests to avoid session event interleaving.
+- Normalize `/v1/chat/completions` and `/v1/responses` text-oriented turns to SDK `prompt` messages and pass the model through `createSession({ model })`.
+- Stream Responses API events before upstream completion and emit heartbeat comments while waiting.
+- Return explicit bridge errors for unsupported requests, auth-required failures, SDK/runtime failures, and upstream timeouts.
+- Project Copilot model providers with `wire_api = "responses"` and `stream_idle_timeout_ms = 300000`.
+
+## Non-Goals
+
+`0.1.2` does not claim the Copilot bridge is a complete OpenAI Responses API backend. Complex tool-call round trips remain experimental unless verified separately.
+
+## Acceptance
+
+- `/v1/responses` request normalization accepts string input, message arrays, or typed top-level content-item arrays; mixed arrays are rejected; non-text items become readable placeholders.
+- Unsupported requests map to `400`, auth-required failures map to `401`, upstream timeouts map to `504`, and other bridge runtime failures map to `500`.
+- Streaming Responses requests emit the expected event shape, including initial lifecycle events before upstream completion, text deltas, and final completion events.
+- Copilot config projection writes `wire_api = "responses"` and `stream_idle_timeout_ms = 300000`.
+- Simple non-stream and stream bridge requests work against the fake SDK contract.
+- Node `<20` Copilot commands fail before mutating provider or Codex state.

package/docs/Tests/testing.md

@@ -1,6 +1,6 @@
 # codex-switch Testing Guide
 
-This guide records the release gate for `0.1.0`.
+This guide records the current `0.1.x` verification contract for release and review work.
 
 ## Required checks
 

package/docs/cli-usage.md

@@ -1,6 +1,6 @@
 # codex-switch CLI Usage
 
-This document describes the current CLI contract for `@minniexcode/codex-switch` at version `0.1.1`.
+This document describes the current `0.1.2` CLI contract for `@minniexcode/codex-switch`, including the Copilot runtime repair boundary.
 
 Executable command name:
 
@@ -10,7 +10,7 @@ codexs
 
 ## 1. Version Context
 
-The current package version in this repository is `0.1.1`.
+The current package version in this repository is `0.1.2`.
 
 This release line targets Codex `0.134.0+`. The public contract assumes runtime routing is selected by top-level `model` plus `model_provider`, while legacy `profile` and `[profiles.*]` remain inspect-and-adopt inputs instead of the recommended runtime path.
 
@@ -51,6 +51,8 @@ Important notes:
 - The current implementation prefers the bundled Copilot CLI from the managed runtime and falls back to `PATH` when needed.
 - `login copilot` succeeds only after auth readiness is rechecked.
 - `add --copilot` does not install or log in to Copilot for you.
+- Copilot runtime paths require Node.js `>=20`; direct providers remain supported on Node.js `>=18`.
+- The Copilot bridge is experimental and targets simple text-oriented turns through the local OpenAI-compatible bridge.
 
 ## 3. Runtime Route Contract
 
@@ -73,6 +75,10 @@ Managed provider projection fixes these fields for OpenAI-compatible direct rout
 - `wire_api = "responses"`
 - `requires_openai_auth = true`
 
+Copilot bridge projection also writes:
+
+- `stream_idle_timeout_ms = 300000`
+
 Compatibility notes:
 
 - `--profile` is accepted as an alias for the managed `model_provider` id.
@@ -278,5 +284,7 @@ codexs rollback [backup-id]
 - [Chinese README](../README.CN.md)
 - [AI README](../README.AI.md)
 - [Product Overview](./codex-switch-product-overview.md)
-- [Release PRD 0.1.1](./PRD/codex-switch-prd-v0.1.1.md)
-- [Release Design 0.1.1](./Design/codex-switch-v0.1.1-design.md)
+- [PRD 0.1.0](./PRD/codex-switch-prd-v0.1.0.md)
+- [PRD 0.1.1](./PRD/codex-switch-prd-v0.1.1.md)
+- [PRD 0.1.2](./PRD/codex-switch-prd-v0.1.2.md)
+- [Design 0.1.2](./Design/codex-switch-v0.1.2-design.md)

package/docs/codex-switch-command-design.md

@@ -8,7 +8,7 @@
 - 文档类型：命令设计文档
 - 适用范围：`codex-switch` MVP
 - 关联文档：
-  - [`PRD/codex-switch-prd.md`](./PRD/codex-switch-prd.md)
+  - [`PRD/codex-switch-prd-v0.1.0.md`](./PRD/codex-switch-prd-v0.1.0.md)
   - [`codex-switch-technical-architecture.md`](./codex-switch-technical-architecture.md)
 
 ## 1. 文档目标

package/docs/codex-switch-product-overview.md

@@ -4,11 +4,13 @@
 
 这份文档介绍当前活跃产品事实源下的 `codex-switch` 产品定位。
 
-当前 release contract 以这些文档为准：
+当前稳定 release contract 以这些文档为准：
 
-- [`cli-usage.md`](./cli-usage.md)
+- [`cli-usage.md`](./cli-usage.md)
+- [`PRD/codex-switch-prd-v0.1.0.md`](./PRD/codex-switch-prd-v0.1.0.md)
 - [`PRD/codex-switch-prd-v0.1.1.md`](./PRD/codex-switch-prd-v0.1.1.md)
-- [`Design/codex-switch-v0.1.1-design.md`](./Design/codex-switch-v0.1.1-design.md)
+- [`PRD/codex-switch-prd-v0.1.2.md`](./PRD/codex-switch-prd-v0.1.2.md)（规划中）
+- [`Design/codex-switch-v0.1.2-design.md`](./Design/codex-switch-v0.1.2-design.md)（规划中）
 
 ## 产品概述
 
@@ -85,3 +87,5 @@ codexs migrate
 - `migrate` 何时才该使用
 - `status` / `doctor` 如何帮助定位下一步
 - 当前运行态是用顶层 `model` 与 `model_provider` 选择活动路由
+
+`0.1.2` 是规划中的 Copilot runtime 修复线，不是当前已发布包版本。当前实现边界是：Copilot 路径要求 Node.js `>=20`，受管安装默认固定到 `@github/copilot-sdk@1.0.2`，运行时会额外拒绝过旧版本和 prerelease 版本，并在真正创建 client 或 session 时验证 SDK API shape；本地 bridge 仍然只是面向 simple text-oriented turns 的 experimental bridge。Direct provider 路径继续支持 Node.js `>=18`。

package/docs/codex-switch-product-research.md

@@ -2,7 +2,7 @@
 
 ## 背景与当前结论
 
-这份文档的定位不是正式 PRD，而是 `codex-switch` 的前置分析稿。它用于整合当前对参考项目、产品边界和技术方向的判断，并为后续单独编写 `PRD/codex-switch-prd.md` 提供输入。
+这份文档的定位不是正式 PRD，而是 `codex-switch` 的前置分析稿。它用于整合当前对参考项目、产品边界和技术方向的判断，并为后续单独编写 `PRD/codex-switch-prd-v0.1.0.md` 提供输入。
 
 当前已经相对明确、可以先锁定的基础结论如下：
 
@@ -317,7 +317,7 @@ Rust / Zig 不是不能做，而是当前收益不足。只有在下面这些诉
 
 ## 后续 PRD 输入项
 
-以下内容应留给后续单独的 `PRD/codex-switch-prd.md` 详细展开，这次只列为输入清单，不在本稿中定死：
+以下内容应留给后续单独的 `PRD/codex-switch-prd-v0.1.0.md` 详细展开，这次只列为输入清单，不在本稿中定死：
 
 - 目标用户和典型场景
   - 例如个人多 provider 用户、需要让 AI 执行切换命令的开发者、需要本地安全回滚的用户