@minniexcode/codex-switch 0.0.7 → 0.0.9

package/dist/storage/runtime-state-repo.js

@@ -0,0 +1,80 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCopilotBridgeStatePath = getCopilotBridgeStatePath;
+exports.readCopilotBridgeState = readCopilotBridgeState;
+exports.writeCopilotBridgeState = writeCopilotBridgeState;
+exports.clearCopilotBridgeState = clearCopilotBridgeState;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const fs_utils_1 = require("./fs-utils");
+/**
+ * Returns the user-level runtime state file used by Copilot bridge helpers.
+ */
+function getCopilotBridgeStatePath() {
+    const override = process.env.CODEX_SWITCH_RUNTIME_STATE_DIR;
+    if (override && override.trim() !== "") {
+        return path.join(path.resolve(override), "copilot-bridge-state.json");
+    }
+    return path.join(os.homedir(), ".codex-switch", "runtime", "copilot-bridge-state.json");
+}
+/**
+ * Reads the Copilot bridge state manifest when present.
+ */
+function readCopilotBridgeState() {
+    const statePath = getCopilotBridgeStatePath();
+    if (!fs.existsSync(statePath)) {
+        return null;
+    }
+    return JSON.parse(fs.readFileSync(statePath, "utf8"));
+}
+/**
+ * Persists the Copilot bridge state manifest.
+ */
+function writeCopilotBridgeState(state) {
+    const statePath = getCopilotBridgeStatePath();
+    (0, fs_utils_1.ensureDir)(path.dirname(statePath));
+    (0, fs_utils_1.writeTextFileAtomic)(statePath, `${JSON.stringify(state, null, 2)}\n`);
+}
+/**
+ * Deletes the Copilot bridge state manifest when present.
+ */
+function clearCopilotBridgeState() {
+    const statePath = getCopilotBridgeStatePath();
+    if (fs.existsSync(statePath)) {
+        fs.rmSync(statePath, { force: true });
+    }
+}

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

@@ -0,0 +1,132 @@
+# codex-switch `0.0.8` 设计文档
+
+## 文档信息
+
+- 文档类型：详细设计文档
+- 适用版本：`0.0.8`
+- 目标范围：`0.0.7 -> 0.0.8`
+- 对应 PRD：[`../PRD/codex-switch-prd-v0.0.8.md`](../PRD/codex-switch-prd-v0.0.8.md)
+
+## 1. 文档目标
+
+本设计把 `0.0.8` 的 Copilot runtime integration 收口到可实现的范围：
+
+- Copilot provider 的 schema 如何表达
+- SDK 的 lazy-load 与自动安装如何落地
+- `add`、`switch`、`status`、`doctor` 分别承担什么职责
+- `providers.json`、`config.toml`、`auth.json` 与 runtime manifest 的边界是什么
+- 代码和测试应该落到哪些模块
+
+## 2. 版本定位
+
+`0.0.8` 是第一个 runtime-backed provider 版本。它不会把 `codex-switch` 扩成通用插件系统，而是先用 GitHub Copilot 把 runtime integration 这条线真正跑通。
+
+## 3. 数据模型
+
+`ProviderRecord` 在 `0.0.8` 中扩展为兼容 direct provider 和 runtime-backed provider：
+
+```ts
+type ProviderRuntime =
+  | {
+      kind: "copilot-sdk-bridge";
+      upstream: "github-copilot";
+      bridgeHost: string;
+      bridgePort: number;
+      bridgePath: "/v1";
+      premiumRequests: true;
+      authSource: "official-sdk";
+      sdkInstallMode: "lazy";
+    };
+```
+
+语义：
+
+- 无 `runtime`：现有 direct provider
+- `runtime.kind = "copilot-sdk-bridge"`：Copilot provider
+- Copilot provider 的 `apiKey` 是本地 bridge 的 shared secret，不是 GitHub token
+- `baseUrl` 必须与 `http://<bridgeHost>:<bridgePort>/v1` 一致
+
+## 4. 命令设计
+
+扩展现有命令面，不新增 `copilot` 或 `proxy` 子命令：
+
+- `codexs add <provider> --copilot --profile <name> [--bridge-host <host>] [--bridge-port <port>] [--bridge-api-key <secret>] [--install-copilot-sdk]`
+- `codexs switch <provider>`
+- `codexs status`
+- `codexs doctor`
+
+规则：
+
+- `--copilot` 与 direct provider 输入模式互斥
+- `--bridge-host` 默认 `127.0.0.1`
+- `--bridge-port` 默认 `4141`
+- `--bridge-api-key` 若缺失则自动生成本地 secret
+- SDK 自动安装只允许发生在 `add --copilot`
+
+## 5. Runtime 模块
+
+新增模块：
+
+- `src/runtime/copilot-sdk-loader.ts`
+- `src/runtime/copilot-installer.ts`
+- `src/runtime/copilot-adapter.ts`
+- `src/runtime/copilot-bridge.ts`
+- `src/storage/runtime-state-repo.ts`
+
+职责：
+
+- loader：按用户级 runtime 目录懒加载 SDK
+- installer：探测与安装 SDK
+- adapter：优先按官方 `CopilotClient -> createSession -> sendAndWait` 形态包装 Copilot SDK 的 probe / auth / request 能力
+- bridge：管理本地 OpenAI 兼容 bridge 的状态
+- runtime state repo：保存 bridge runtime manifest
+
+前置条件：
+
+- 本地官方 SDK 依赖已安装并可加载
+- 用户机器上已有可用的 Copilot CLI / login 状态，`codex-switch` 不接管上游账号登录
+
+## 6. 运行态与文件边界
+
+- `providers.json`：保存 Copilot provider 与 bridge 配置
+- `config.toml`：保存 bridge 的 `base_url` 与 `env_key`
+- `auth.json`：保存 Codex 到 bridge 的 shared secret
+- runtime manifest：保存 bridge 进程状态，不进入 managed backup 事务
+
+## 7. `switch` 时序
+
+1. 读取 provider
+2. 校验 `runtime` 配置
+3. probe SDK
+4. 缺失则直接报错
+5. 检查 Copilot auth state
+6. 启动或复用 bridge
+7. healthcheck 通过
+8. 再进入现有 `config.toml + auth.json` 写入事务
+9. 文件写入失败时回滚，并对本次新启动 bridge 做 best-effort 清理
+
+## 8. 错误语义
+
+新增错误码：
+
+- `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`
+
+## 9. 测试
+
+需要覆盖：
+
+- `add --copilot` 参数与写入
+- 非交互缺失 SDK 的失败路径
+- `--install-copilot-sdk` 的允许安装路径
+- Copilot provider 的 `status` / `doctor`
+- direct provider 回归

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
+