@minniexcode/codex-switch 0.0.8 → 0.0.9

package/dist/runtime/copilot-bridge.js

@@ -37,6 +37,7 @@ exports.setCopilotBridgeSpawnImplementation = setCopilotBridgeSpawnImplementatio
 exports.resetCopilotBridgeSpawnImplementation = resetCopilotBridgeSpawnImplementation;
 exports.probeCopilotBridgeRuntime = probeCopilotBridgeRuntime;
 exports.ensureCopilotBridge = ensureCopilotBridge;
+exports.startOrReuseCopilotBridge = startOrReuseCopilotBridge;
 exports.createCopilotBridgeRequestHandler = createCopilotBridgeRequestHandler;
 exports.startCopilotBridgeServer = startCopilotBridgeServer;
 exports.waitForCopilotBridgeHealth = waitForCopilotBridgeHealth;
@@ -66,6 +67,15 @@ function resetCopilotBridgeSpawnImplementation() {
  */
 async function probeCopilotBridgeRuntime(provider) {
     const state = (0, runtime_state_repo_1.readCopilotBridgeState)();
+    if (state && (!provider || !(0, providers_1.isCopilotBridgeProvider)(provider))) {
+        return {
+            ok: false,
+            runtime: "copilot-bridge",
+            reason: "failed",
+            cause: "Copilot bridge runtime state exists but no active Copilot bridge provider is selected.",
+            details: state,
+        };
+    }
     if (!provider || !(0, providers_1.isCopilotBridgeProvider)(provider)) {
         return {
             ok: false,
@@ -127,6 +137,12 @@ async function probeCopilotBridgeRuntime(provider) {
  * Starts or reuses a Copilot bridge worker, then verifies its health before returning.
  */
 async function ensureCopilotBridge(providerName, provider) {
+    return startOrReuseCopilotBridge(providerName, provider);
+}
+/**
+ * Starts or reuses a Copilot bridge worker and reports the chosen port.
+ */
+async function startOrReuseCopilotBridge(providerName, provider) {
     if (!(0, providers_1.isCopilotBridgeProvider)(provider)) {
         throw (0, errors_1.cliError)("RUNTIME_PROVIDER_INVALID", "Provider is not backed by a Copilot bridge runtime.", {
             provider: providerName,
@@ -140,6 +156,7 @@ async function ensureCopilotBridge(providerName, provider) {
     }
     const expectedBaseUrl = (0, providers_1.buildCopilotBridgeBaseUrl)(runtime);
     const current = (0, runtime_state_repo_1.readCopilotBridgeState)();
+    let replaced = false;
     if (current && current.provider === providerName && current.baseUrl === expectedBaseUrl) {
         const healthy = await healthcheckCopilotBridge(current.host, current.port);
         if (healthy.ok) {
@@ -149,19 +166,20 @@ async function ensureCopilotBridge(providerName, provider) {
             });
             return {
                 baseUrl: expectedBaseUrl,
+                host: current.host,
+                port: current.port,
                 reused: true,
+                portChanged: false,
+                replaced: false,
             };
         }
     }
-    const portCheck = await checkPortAvailability(runtime.bridgeHost, runtime.bridgePort);
-    if (!portCheck.ok) {
-        throw (0, errors_1.cliError)("BRIDGE_PORT_CONFLICT", "Copilot bridge port is already in use.", {
-            provider: providerName,
-            host: runtime.bridgeHost,
-            port: runtime.bridgePort,
-            cause: portCheck.cause,
-        });
+    if (current && current.provider !== providerName) {
+        stopCopilotBridge();
+        replaced = true;
     }
+    const selectedPort = await selectBridgePort(runtime.bridgeHost, runtime.bridgePort);
+    const selectedBaseUrl = `http://${runtime.bridgeHost}:${selectedPort}${runtime.bridgePath}`;
     const workerPath = path.join(__dirname, "copilot-bridge-worker.js");
     let child;
     try {
@@ -172,9 +190,9 @@ async function ensureCopilotBridge(providerName, provider) {
                 ...process.env,
                 CODEX_SWITCH_BRIDGE_PROVIDER: providerName,
                 CODEX_SWITCH_BRIDGE_HOST: runtime.bridgeHost,
-                CODEX_SWITCH_BRIDGE_PORT: String(runtime.bridgePort),
+                CODEX_SWITCH_BRIDGE_PORT: String(selectedPort),
                 CODEX_SWITCH_BRIDGE_API_KEY: provider.apiKey,
-                CODEX_SWITCH_BRIDGE_BASE_URL: expectedBaseUrl,
+                CODEX_SWITCH_BRIDGE_BASE_URL: selectedBaseUrl,
             },
         });
     }
@@ -182,27 +200,27 @@ async function ensureCopilotBridge(providerName, provider) {
         throw (0, errors_1.cliError)("BRIDGE_START_FAILED", "Failed to start the Copilot bridge worker.", {
             provider: providerName,
             host: runtime.bridgeHost,
-            port: runtime.bridgePort,
+            port: selectedPort,
             cause: error instanceof Error ? error.message : String(error),
         });
     }
     child.unref();
     const startedAt = new Date().toISOString();
-    const healthy = await waitForCopilotBridgeStartup(child, runtime.bridgeHost, runtime.bridgePort, 15, 200);
+    const healthy = await waitForCopilotBridgeStartup(child, runtime.bridgeHost, selectedPort, 15, 200);
     if (!healthy.ok) {
         (0, runtime_state_repo_1.clearCopilotBridgeState)();
         if (healthy.reason === "start-failed") {
             throw (0, errors_1.cliError)("BRIDGE_START_FAILED", "Copilot bridge worker exited before becoming healthy.", {
                 provider: providerName,
                 host: runtime.bridgeHost,
-                port: runtime.bridgePort,
+                port: selectedPort,
                 cause: healthy.cause,
             });
         }
         throw (0, errors_1.cliError)("BRIDGE_HEALTHCHECK_FAILED", "Copilot bridge did not become healthy after startup.", {
             provider: providerName,
             host: runtime.bridgeHost,
-            port: runtime.bridgePort,
+            port: selectedPort,
             cause: healthy.cause,
         });
     }
@@ -210,15 +228,19 @@ async function ensureCopilotBridge(providerName, provider) {
         provider: providerName,
         pid: child.pid ?? null,
         host: runtime.bridgeHost,
-        port: runtime.bridgePort,
-        baseUrl: expectedBaseUrl,
+        port: selectedPort,
+        baseUrl: selectedBaseUrl,
         startedAt,
         lastHealthcheckAt: new Date().toISOString(),
     };
     (0, runtime_state_repo_1.writeCopilotBridgeState)(state);
     return {
-        baseUrl: expectedBaseUrl,
+        baseUrl: selectedBaseUrl,
+        host: runtime.bridgeHost,
+        port: selectedPort,
         reused: false,
+        portChanged: selectedPort !== runtime.bridgePort,
+        replaced,
     };
 }
 /**
@@ -342,6 +364,25 @@ async function checkPortAvailability(host, port) {
         });
     });
 }
+async function selectBridgePort(host, preferredPort) {
+    const preferred = await checkPortAvailability(host, preferredPort);
+    if (preferred.ok) {
+        return preferredPort;
+    }
+    for (let port = 10000; port <= 99999; port += 1) {
+        if (port === preferredPort) {
+            continue;
+        }
+        const available = await checkPortAvailability(host, port);
+        if (available.ok) {
+            return port;
+        }
+    }
+    throw (0, errors_1.cliError)("BRIDGE_PORT_CONFLICT", "Unable to find a free 5-digit bridge port.", {
+        host,
+        port: preferredPort,
+    });
+}
 async function waitForCopilotBridgeStartup(child, host, port, attempts, delayMs) {
     let startupFailure = null;
     const onError = (error) => {

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

@@ -0,0 +1,182 @@
+# codex-switch `0.0.9` Design
+
+## 1. Purpose
+
+This design turns the `0.0.9` PRD into an implementable CLI and runtime spec for the local Copilot bridge path.
+
+The release goal is not to introduce a background service product. It is to make the existing local Copilot bridge safe to start, stop, inspect, and reuse from a single-process user-space workflow.
+
+## 2. Scope
+
+### In scope
+
+- `codexs bridge start [provider]`
+- `codexs bridge stop [provider]`
+- `codexs bridge status [provider]`
+- single-instance bridge reuse and replacement
+- detached user-space bridge workers
+- 5-digit default port selection with recovery when the preferred port is occupied
+- runtime state persistence outside the managed backup transaction boundary
+- Copilot-only target selection helpers
+- switch-time bridge reuse through the same lifecycle code path
+
+### Out of scope
+
+- boot autostart
+- login autostart
+- Windows Service support
+- multiple concurrent managed bridge instances
+- non-Copilot runtime families
+- any new auth storage scheme for upstream Copilot login state
+
+## 3. Command Surface
+
+### 3.1 New commands
+
+- `codexs bridge start [provider]`
+- `codexs bridge stop [provider]`
+- `codexs bridge status [provider]`
+
+The command registry must add nested tokens under the public `bridge` namespace, with the longest token sequence winning during argument resolution.
+
+### 3.2 Command semantics
+
+- `start` is a write command
+- `stop` is an operational write/recovery command
+- `status` is a read command
+
+### 3.3 Target resolution
+
+For `bridge start`, provider resolution proceeds in this order:
+
+1. explicit provider argument
+2. current active provider, if it is a Copilot bridge provider
+3. sole configured Copilot bridge provider
+4. interactive Copilot-only provider picker in a TTY
+
+If none of those paths resolves a target, the command fails with a design-level bridge target error.
+
+For `bridge stop` and `bridge status`, resolution prefers the current runtime-state instance when present. An explicit provider argument acts as a guard and must not silently target a different provider instance.
+
+## 4. Runtime Model
+
+### 4.1 Single-instance policy
+
+The bridge runtime is a single detached user-space worker.
+
+- If the bridge is already healthy for the same provider, `start` and `switch` reuse it.
+- If the bridge is healthy for a different provider, the current managed instance is stopped before a new one is started.
+- Runtime state is stored separately from the managed file backup transaction, so the bridge can survive or be inspected outside file rollbacks.
+
+### 4.2 Health checks
+
+Bridge startup must verify the worker by probing the local `/healthz` endpoint before the command reports success.
+
+Bridge status must report:
+
+- the last known runtime state
+- whether the provider binding matches the expected provider
+- whether the live worker is healthy
+- the reason if the state is stale or mismatched
+
+### 4.3 Stop behavior
+
+`bridge stop` is protection-first.
+
+- It stops the managed worker when one exists.
+- It clears the runtime-state manifest.
+- It must not mutate `providers.json`, `config.toml`, or `auth.json`.
+- If the caller supplies a provider that does not match the tracked runtime state, the command fails rather than stopping the wrong instance.
+
+## 5. Port Policy
+
+- The default bridge host is `127.0.0.1`.
+- The default bridge port is fixed at `41415`.
+- The port must always remain in the 5-digit range.
+- If the preferred port is occupied, the runtime must automatically select another free 5-digit port.
+- Any recovered port must be persisted back into the provider record and the corresponding `config.toml` runtime projection before the command reports success.
+- The persisted port must match the live worker port.
+
+The key design constraint is that runtime state and managed config cannot diverge after a successful start.
+
+## 6. Persistence Boundaries
+
+`bridge start` may update:
+
+- `providers.json`
+- the matching `config.toml` bridge projection
+- runtime state manifest
+
+`bridge start` must not rewrite:
+
+- `auth.json`
+- active profile state except when invoked through the shared `switch` flow
+
+`switch` keeps using the same bridge lifecycle path and performs its own auth/config transaction afterward.
+
+Runtime state is explicitly outside backup transactions. If file persistence fails after the worker has started, the implementation must clean up the new worker unless it was reused from a previous healthy instance.
+
+## 7. Error Model
+
+The implementation should reuse existing error families where possible and add bridge-specific errors for unresolved target and provider mismatch cases.
+
+Relevant bridge/runtime errors:
+
+- `BRIDGE_TARGET_UNRESOLVED`
+- `BRIDGE_PROVIDER_MISMATCH`
+- `BRIDGE_PORT_CONFLICT`
+- `BRIDGE_START_FAILED`
+- `BRIDGE_HEALTHCHECK_FAILED`
+- `RUNTIME_PROVIDER_INVALID`
+- `PROVIDER_BASE_URL_MISMATCH`
+
+The design intent is that the bridge commands fail clearly before mutating managed files when the provider cannot be resolved or the provider/runtime binding is inconsistent.
+
+## 8. Implementation Shape
+
+The implementation should be split into three layers:
+
+- command wiring in `src/commands/`
+- app use cases in `src/app/`
+- worker and healthcheck code in `src/runtime/`
+
+The bridge-specific app layer should own:
+
+- target resolution
+- port recovery
+- provider/config projection updates
+- runtime-state cleanup
+
+The runtime layer should own:
+
+- worker spawning
+- healthcheck probing
+- detached-process cleanup
+- runtime-state manifest read/write
+
+## 9. Tests
+
+Minimum coverage for `0.0.9`:
+
+- command parsing and help for `bridge start|stop|status`
+- longest-token resolution for nested commands
+- explicit provider, active-provider, sole-provider, and TTY fallback selection
+- current-runtime-state preference for stop/status
+- mismatch-guard behavior for stop/status
+- single-instance reuse and replacement
+- stale runtime-state cleanup
+- port conflict recovery
+- persisted port updates
+- cleanup when file mutation fails after a successful bridge start
+- direct-provider regressions
+
+## 10. Release Criteria
+
+`0.0.9` is complete when the following are true:
+
+- Copilot bridge can be managed manually with `bridge start|stop|status`
+- `switch` reuses the same lifecycle path
+- the default bridge port is 5 digits and port conflicts recover automatically
+- runtime state is durable enough for status and stop behavior, but remains outside managed backup transactions
+- direct providers keep their existing behavior
+

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

@@ -0,0 +1,166 @@
+# codex-switch `0.0.9` PRD
+
+## 文档信息
+
+- 状态：Active PRD
+- 产品名：`codex-switch`
+- CLI 命令名：`codexs`
+- 当前基线版本：`0.0.8`
+- 目标版本：`0.0.9`
+- 文档定位：定义 `0.0.8 -> 0.0.9` 的直接需求范围
+- 关联设计文档：`../Design/codex-switch-v0.0.9-design.md`（待产出）
+- 关联上一版设计：[`../Design/codex-switch-v0.0.8-design.md`](../Design/codex-switch-v0.0.8-design.md)
+
+## 一句话定义
+
+`0.0.9` 的目标，是把 GitHub Copilot 的本地 bridge 从“切换时临时可用”收敛成“可按需自动拉起、可手动管理、可诊断恢复”的稳定运行态能力。
+
+## In Scope
+
+- 官方 `@github/copilot-sdk`
+- 本地 Node/TypeScript bridge
+- detached 用户态 bridge 守护进程
+- `switch` 的 bridge 自动启动 / 复用
+- `bridge start`
+- `bridge stop`
+- `bridge status`
+- 单实例 bridge 生命周期管理
+- 5 位数 bridge 端口默认策略
+- 端口冲突自动探测与自动换端口
+- runtime state manifest 的持久化与诊断
+- `status` / `doctor` 的 bridge 生命周期诊断
+- direct provider 回归稳定性
+
+## Out of Scope
+
+- 开机自启动
+- 登录自启动
+- Windows Service / 系统服务注册
+- 多实例 bridge 编排
+- 非官方 SDK
+- 独立 GUI / TUI
+- Responses API、Embeddings、图像/音频接口
+- 持久化 GitHub token 到 `providers.json` / `auth.json`
+
+## 运行形态
+
+- bridge 是由 `codex-switch` 启动和管理的本地后台进程
+- bridge 不是系统服务，也不注册开机或登录自动启动项
+- `switch` 到 Copilot provider 时，bridge 应自动启动或复用
+- 用户也可以通过 `bridge` 命令族手动启动、停止和查看状态
+- `0.0.9` 的“守护进程”语义仅指 detached 用户态后台进程，不等同于 OS service
+
+## 命令面
+
+新增命令：
+
+- `codexs bridge start [provider]`
+- `codexs bridge stop [provider]`
+- `codexs bridge status [provider]`
+
+命令规则：
+
+- `bridge` 命令族只服务于 Copilot runtime-backed provider
+- `provider` 可显式传入；未传入时优先使用当前 active provider
+- 如果未传入且当前 active provider 不是 Copilot provider：
+  - TTY 下允许交互选择目标 Copilot provider
+  - 非交互或 `--json` 下必须明确失败
+- `bridge start` 必须先完成：
+  - provider 解析
+  - runtime 配置校验
+  - SDK probe
+  - Copilot auth state 校验
+  - bridge 启动或复用
+  - healthcheck
+- `bridge stop` 只停止当前受管 bridge 进程并清理 runtime state manifest，不修改 provider registry
+- `bridge status` 返回 runtime state、provider 绑定关系、healthcheck 结果与异常原因
+
+## 生命周期规则
+
+- `add --copilot` 只负责创建 provider 和可选安装 SDK，不负责启动 bridge
+- `switch <copilot-provider>` 仍然是最常见的自动启动入口
+- `bridge start` 与 `switch` 共享同一套 bridge 启动与复用逻辑
+- 同一时刻只允许一个 bridge 实例处于受管运行状态
+- 如果 bridge 已为同一 provider 运行且健康，则 `bridge start` 和 `switch` 都直接复用
+- 如果已有 bridge 为另一 Copilot provider 运行：
+  - `bridge start <new-provider>` 先停止旧实例，再启动新实例
+  - `switch <new-provider>` 也遵守同样的单实例替换规则
+- `bridge stop` 应该是幂等的：bridge 已停止时不报致命错误
+
+## 端口策略
+
+- `--bridge-host` 默认 `127.0.0.1`
+- `--bridge-port` 默认值必须是 5 位数端口
+- Copilot provider 的默认端口不再使用 `4141`
+- 如果 provider 指定端口已被占用：
+  - bridge 启动阶段必须自动检测冲突
+  - 自动选择新的可用 5 位数端口
+  - 自动更新 provider 的 runtime 配置和对应 `baseUrl`
+  - 自动保持 `config.toml` runtime projection 与 provider 配置一致
+- 自动换端口后的新端口必须持久化，避免下一次启动再次撞到旧端口
+- 端口自动切换只允许在 Copilot bridge provider 路径发生，不能影响 direct provider
+
+## 依赖策略
+
+- `@github/copilot-sdk` 继续不进入 core CLI 默认依赖
+- 命中 Copilot 路径时才 probe SDK
+- SDK 自动安装仍然只允许发生在 `add --copilot`
+- `bridge start`、`switch`、`status`、`doctor` 都不能隐式安装 SDK
+- `bridge start` 在 SDK 缺失时必须明确失败，并提示回到 `add --copilot --install-copilot-sdk`
+- SDK 运行前提仍然是用户本机已具备可用的 GitHub Copilot CLI / login 状态，`codex-switch` 不托管这部分登录数据
+
+## 数据边界
+
+- `providers.json` 保存 Copilot provider、bridge host/port、`baseUrl` 与 shared secret
+- `config.toml` 保存 Copilot provider 对应的 runtime `base_url` 与 `env_key`
+- `auth.json` 只保存 Codex 到本地 bridge 的 shared secret
+- runtime state manifest 保存当前 bridge 进程状态、provider 绑定、最后健康检查时间
+- runtime state manifest 不进入 managed backup 事务
+- GitHub/Copilot 上游认证状态仍然只由官方 SDK 管理，不进入受管 registry
+
+## 错误语义
+
+`0.0.9` 继续稳定并收敛以下错误码：
+
+- `COPILOT_SDK_MISSING`
+- `COPILOT_SDK_INSTALL_FAILED`
+- `COPILOT_SDK_INSTALL_REQUIRES_TTY`
+- `COPILOT_SDK_UNSUPPORTED`
+- `COPILOT_AUTH_REQUIRED`
+- `COPILOT_PREMIUM_UNAVAILABLE`
+- `BRIDGE_PORT_CONFLICT`
+- `BRIDGE_START_FAILED`
+- `BRIDGE_HEALTHCHECK_FAILED`
+- `RUNTIME_PROVIDER_INVALID`
+- `PROVIDER_BASE_URL_MISMATCH`
+
+新增要求：
+
+- `bridge start`、`switch`、`bridge status` 对同一类 bridge 失败应尽量映射到同一类错误码
+- 端口冲突在自动恢复成功时不应向上冒泡为致命失败
+- 只有在无法找到可用端口或无法持久化新端口时，才允许保留 `BRIDGE_PORT_CONFLICT` 失败
+
+## 验收标准
+
+- `add --copilot` 可以创建 Copilot provider，并写入 5 位数默认端口
+- `switch` 到 Copilot provider 时完成 `probe -> auth check -> start or reuse bridge -> healthcheck -> config/auth write`
+- `codexs bridge start [provider]` 可以手动启动或复用 bridge
+- `codexs bridge stop [provider]` 可以手动停止当前 bridge，并清理 runtime state
+- `codexs bridge status [provider]` 可以给出 bridge 是否运行、绑定哪个 provider、端口是多少、是否健康
+- 当 bridge 目标端口被占用时，系统会自动切换到新的可用 5 位数端口，并持久化该变更
+- direct provider 不经过 Copilot 特有的 runtime gate
+- `status` / `doctor` 能诊断 SDK 缺失、认证缺失、bridge 不健康、stale runtime state、runtime base_url 漂移
+
+## 测试重点
+
+- `bridge start/stop/status` 参数解析与帮助文案
+- 省略 provider 时的 active provider 解析路径
+- TTY 下的 Copilot provider 交互选择路径
+- 非交互下目标 provider 不明确时的失败路径
+- 单实例 bridge 的复用路径
+- 单实例 bridge 的替换路径
+- `switch` 与 `bridge start` 共享生命周期逻辑的回归
+- 端口占用时的自动换端口与持久化
+- stale runtime state 的诊断与清理
+- `bridge stop` 幂等性
+- direct provider 回归