@minniexcode/codex-switch 0.0.10 → 0.0.11

package/README.AI.md

@@ -4,7 +4,7 @@ This file is for AI agents, automation scripts, and contributors who need a comp
 
 ## Repository Purpose
 
-`@minniexcode/codex-switch` is a local-first TypeScript CLI for managing provider/profile state for Codex under `~/.codex/`.
+`@minniexcode/codex-switch` is a local-first TypeScript CLI for managing provider/profile state for Codex while keeping codex-switch tool state separate from the target Codex runtime.
 
 Primary goals:
 
@@ -13,22 +13,29 @@ Primary goals:
 - rollback on failure
 - stable machine-readable CLI output
 - support for both human TTY usage and agent automation
+- explicit onboarding for interactive upstreams such as GitHub Copilot
 
 ## Main Command Surface
 
 ```bash
 codexs init
+codexs login copilot
 codexs migrate
 codexs list
 codexs show <provider>
 codexs current
 codexs status
+codexs config show [profile]
+codexs config list-profiles
 codexs edit <provider>
 codexs switch <provider>
 codexs import <file>
 codexs export <file>
 codexs add <provider>
 codexs remove <provider>
+codexs bridge start [provider]
+codexs bridge status [provider]
+codexs bridge stop [provider]
 codexs backups list
 codexs doctor
 codexs rollback [backup-id]
@@ -41,23 +48,43 @@ Shared flags:
 --codex-dir <path>
 ```
 
-## Important Runtime Files
+Relevant environment variables:
+
+```bash
+CODEXS_HOME
+CODEXS_CODEX_DIR
+```
+
+## Important Files
+
+Tool home:
+
+```text
+~/.config/codex-switch/
+  codex-switch.json
+  providers.json
+  backups/
+  runtime/
+  runtimes/
+```
+
+Target Codex runtime:
 
 ```text
 ~/.codex/
   config.toml
   auth.json
-  providers.json
-  backups/
 ```
 
 Operational model:
 
 - `providers.json` is the management-state source of truth
-- `config.toml` is the managed runtime-routing file
-- `auth.json` is the active auth projection file for direct providers and is also inspected by status/doctor
-- `backups/latest.json` tracks the latest rollback state
-- mutating commands should back up first and run under a lightweight file lock
+- `codex-switch.json` stores tool-level metadata such as `defaultCodexDir`
+- `config.toml` remains the managed runtime-routing file in the target Codex directory
+- `auth.json` remains the active auth projection file
+- `runtime/` stores managed bridge runtime state
+- `runtimes/` stores optional local runtimes such as the Copilot SDK install
+- mutating commands back up first and run under a lightweight file lock in the tool home
 
 ## Project Structure
 
@@ -65,8 +92,11 @@ Operational model:
 src/
   app/
   cli/
+  commands/
   domain/
-  infra/
+  interaction/
+  runtime/
+  storage/
 tests/
 docs/
 dist/
@@ -74,10 +104,13 @@ dist/
 
 Layer intent:
 
-- `cli`: argument parsing, help, TTY flows, output shaping
+- `cli`: output shaping and thin CLI-facing utilities
+- `commands`: argument parsing, help rendering, and command dispatch
 - `app`: command orchestration and use-case logic
 - `domain`: pure domain rules and shared models
-- `infra`: filesystem, lock, backup, config, and Codex integration code
+- `interaction`: TTY-only prompt flows
+- `runtime`: Codex/Copilot runtime probing and local bridge management
+- `storage`: filesystem-backed repositories and path resolution
 
 ## Command Entry Point
 
@@ -87,6 +120,7 @@ Use `codexs` directly for runtime interaction:
 codexs --help
 codexs list --json
 codexs status --json
+codexs config list-profiles --json
 ```
 
 ## Current Version Context
@@ -94,13 +128,14 @@ codexs status --json
 Current package version in this repository:
 
 ```text
-0.0.10
+0.0.11
 ```
 
 Recent version summary:
 
-- `0.0.10`: `init` / `migrate` command split finalized, `setup` deprecated, and the managed provider model reduced to static profile plus `base_url` configuration
-- `0.0.7`: command-surface refactor, env_key/auth-mirror model corrections, and the initial `setup` split toward `init` plus `migrate`
+- `0.0.11`: tool-home split, `login copilot`, managed bridge commands, and config inspection commands
+- `0.0.10`: `init` / `migrate` command split finalized and `setup` deprecated
+- `0.0.7`: command-surface refactor and setup split groundwork
 - `0.0.4`: setup/show/edit/backups list/specific rollback/import merge and clearer CLI semantics
 - `0.0.3`: interactive TTY flows and improved help
 - `0.0.2`: mutation orchestration, backups, rollback, locks, drift detection improvements
@@ -111,5 +146,7 @@ Recent version summary:
 - Prefer `--json` when invoking commands programmatically
 - Treat `providers.json` as sensitive because it may contain API keys
 - Do not assume silent write-back from runtime files into `providers.json`
-- Prefer `init` for repeatable machine setup and `migrate` for human-led adopt flows
+- Prefer `init` for repeatable tool-home setup and `migrate` for human-led adopt flows
+- `login copilot` requires a real TTY and should not be used under `--json`
+- `add --copilot` assumes SDK install and upstream auth readiness are already satisfied
 - Use `docs/` for deeper product and architecture context

package/README.CN.md

@@ -2,55 +2,58 @@
 
 `@minniexcode/codex-switch` 是一个本地优先的 CLI，用来安全地管理和切换 Codex 的 provider/profile 配置。
 
-它主要解决这样一个问题：如果你同时使用多个 Codex provider、API key 或 profile，不想再手动改 `~/.codex/` 里的文件，就可以用这个工具做统一管理和安全切换。
+从 `0.0.11` 开始，它不再把整个管理态都塞进 `~/.codex/`，而是把工具自己的状态拆到独立的 tool home 里，同时继续对目标 Codex runtime 做受控写入。
 
 ## 这个仓库是做什么的
 
 这个仓库包含 `codex-switch` 的 CLI 实现、npm 包配置，以及相关产品和技术文档。
 
-项目目标很明确：
+项目目标：
 
-- 在本地完成 Codex 配置切换
+- 在本地完成 provider/profile 管理与切换
 - 写入前先备份
 - 出错时可回滚
 - 同时兼顾终端用户和 AI/自动化调用
+- 为 GitHub Copilot 这类交互式上游登录提供独立入口
 
 ## 现在可以做什么
 
-当前命令面如下：
+当前公开命令面如下：
 
 ```bash
 codexs init
+codexs login copilot
 codexs migrate
 codexs list
 codexs show <provider>
 codexs current
 codexs status
+codexs config show [profile]
+codexs config list-profiles
 codexs edit <provider>
 codexs switch <provider>
 codexs import <file>
 codexs export <file>
 codexs add <provider>
 codexs remove <provider>
+codexs bridge start [provider]
+codexs bridge status [provider]
+codexs bridge stop [provider]
 codexs backups list
 codexs doctor
-codexs rollback
+codexs rollback [backup-id]
 codexs setup
 ```
 
 对应能力包括：
 
-- 初始化空的受管 `providers.json`
+- 初始化独立的 tool home 与空的受管 `providers.json`
 - 从已有 `config.toml` adopt 可管理的 runtime profile
-- 查看本地已管理的 provider
-- 查看单个 provider 详情
-- 查看当前激活的 profile
-- 查看本地运行态摘要
-- 编辑已有 provider
-- 安全切换 provider
-- 导入和导出 provider 映射
-- 新增和删除 provider
-- 查看备份列表
+- 查看本地已管理 provider
+- 查看结构化 config profile 视图
+- 编辑、切换、导入、导出、删除 provider
+- 为 GitHub Copilot 完成上游 SDK 安装与登录检查
+- 显式启动、查看和停止本地 Copilot bridge
 - 检查配置漂移和常见本地问题
 - 在变更前自动备份，并在失败时回滚
 - 保留 `setup` 作为弃用入口，并引导到 `init` / `migrate`
@@ -81,17 +84,26 @@ codexs --help
 codexs init
 codexs migrate
 codexs list
-codexs current
+codexs config show
 codexs add my-provider --profile my-provider --api-key sk-xxx
 codexs switch my-provider
 codexs status
 ```
 
+GitHub Copilot 路径：
+
+```bash
+codexs login copilot
+codexs add copilot-main --copilot --profile copilot-main
+codexs bridge start copilot-main
+```
+
 给脚本或 AI 使用时建议加上：
 
 ```bash
 codexs list --json
 codexs status --json
+codexs config list-profiles --json
 ```
 
 通用参数：
@@ -101,6 +113,13 @@ codexs status --json
 --codex-dir <path>
 ```
 
+环境变量：
+
+```bash
+CODEXS_HOME
+CODEXS_CODEX_DIR
+```
+
 ## 交互式体验
 
 这个 CLI 同时支持显式命令和交互式终端流程。
@@ -109,64 +128,77 @@ codexs status --json
 - `codexs switch` 在未传 provider 时可以弹出选择列表
 - `codexs remove` 支持交互式选择和确认删除
 - `import`、`export`、`rollback` 在交互模式下会要求确认
+- `login copilot` 必须在真实 TTY 中执行
+- `migrate` 当前仍保留交互式 adopt 语义
 - `--json` 模式保持非交互，适合自动化
 
 ## 管理哪些文件
 
-`codex-switch` 主要围绕 `~/.codex/` 下的这些文件工作：
+从 `0.0.11` 开始，`codex-switch` 使用双路径模型。
+
+tool home：
+
+```text
+~/.config/codex-switch/
+  codex-switch.json
+  providers.json
+  backups/
+  runtime/
+  runtimes/
+```
+
+目标 Codex runtime：
 
 ```text
 ~/.codex/
   config.toml
   auth.json
-  providers.json
-  backups/
 ```
 
 存储模型：
 
-- `providers.json` 是管理态的单一事实来源
-- `config.toml` 是受管的运行时路由文件
-- `auth.json` 是独立的 Codex 认证状态文件，`status` / `doctor` 只读检查它
+- `providers.json` 是管理态的单一事实来源，位于 tool home
+- `codex-switch.json` 存放工具级配置，例如 `defaultCodexDir`
+- `config.toml` 是目标 Codex runtime 的受管路由文件
+- `auth.json` 是当前认证投影文件
 - `backups/latest.json` 记录最近一次可回滚窗口
+- `runtime/` 保存受管 bridge runtime state
+- `runtimes/` 用于存放可选本地 runtime，例如 Copilot SDK
 
-注意：`providers.json` 可能包含 API key，应视为本地敏感文件。
+注意：`providers.json` 可能包含 API key，本地使用时应视为敏感文件。
 
-## 相关文档
+## 最近版本更新
 
-- [English README](./README.md)
-- [AI README](./README.AI.md)
-- [产品概览](./docs/codex-switch-product-overview.md)
-- [产品调研](./docs/codex-switch-product-research.md)
-- [PRD](./docs/codex-switch-prd.md)
-- [技术架构](./docs/codex-switch-technical-architecture.md)
-- [命令设计](./docs/codex-switch-command-design.md)
+### 0.0.11
 
-## 最近 3 个版本更新
+- 引入独立 tool home，正式把管理态从 `~/.codex` 中拆出
+- 新增 `login copilot`，把 GitHub Copilot 上游登录从 `add --copilot` 中解耦
+- 新增 `bridge start/status/stop` 与 `config show/list-profiles`
+- README、CLI usage 和发布元数据统一按新命令契约更新
 
 ### 0.0.10
 
 - 正式拆分 `setup`：新增 `init` 和 `migrate`，`setup` 变为弃用命令
-- 增加 `show`、`edit`、`backups list` 等对当前命令面的整理
-- 清理 provider/runtime 管理语义，CLI 只负责静态 profile 与 `base_url` 层配置
+- 收紧迁移、诊断、回滚和发布正确性边界
+- 清理 provider/runtime 管理语义，CLI 聚焦静态 profile 与 `base_url` 层配置
 
-### 0.0.3
+### 0.0.7
 
-- 为 `add`、`switch`、`remove`、`import`、`export`、`rollback` 增加了交互式 TTY 流程
-- 改进了帮助信息和命令级使用说明
-- 增强了交互行为和参数处理相关测试覆盖
+- 完成 command-surface 重构
+- 校正 env key / auth mirror 相关模型
+- 推进 `setup` 向 `init` + `migrate` 的拆分
 
-### 0.0.2
-
-- 增加了统一的变更编排能力，包括写前备份、失败回滚和单进程锁
-- 改进了 `status` 和 `doctor`，更清晰地识别运行态漂移
-- 加强了底层仓储层和领域层，使配置写入更安全
-
-### 0.0.1
+## 相关文档
 
-- 发布了第一版 TypeScript CLI 实现
-- 落地了核心 MVP 命令和基于文件的 provider 管理模型
-- 补齐了首批产品、架构和命令设计文档
+- [English README](./README.md)
+- [AI README](./README.AI.md)
+- [详细 CLI 文档](./docs/cli-usage.md)
+- [产品概览](./docs/codex-switch-product-overview.md)
+- [产品调研](./docs/codex-switch-product-research.md)
+- [PRD 0.0.11](./docs/PRD/codex-switch-prd-v0.0.11.md)
+- [技术架构](./docs/codex-switch-technical-architecture.md)
+- [0.0.11 设计文档](./docs/Design/codex-switch-v0.0.11-design.md)
+- [测试说明](./docs/Tests/testing.md)
 
 ## 本地开发
 
@@ -174,6 +206,7 @@ codexs status --json
 npm install
 npm run build
 npm test
+npx tsc --noEmit
 node dist/cli.js --help
 ```
 

package/README.md

@@ -8,17 +8,20 @@ It is designed for users who work with multiple Codex providers, API keys, or pr
 
 ## Overview
 
-What it does:
+What it does in `0.0.11`:
 
-- Initialize an empty managed `providers.json`
-- Migrate unmanaged runtime profiles from an existing Codex directory
-- List, show, add, edit, and remove provider records
-- Switch the active provider/profile safely
-- Import and export provider definitions
-- Run diagnostics and detect local drift
-- List backups and roll back to a previous managed state
+- Initializes a dedicated `codex-switch` tool home
+- Adopts unmanaged runtime profiles from an existing Codex directory
+- Lists, shows, adds, edits, and removes provider records
+- Switches the active provider/profile safely
+- Supports explicit GitHub Copilot upstream onboarding
+- Manages the local Copilot bridge runtime explicitly
+- Imports and exports provider definitions
+- Runs diagnostics and detects local drift
+- Lists backups and rolls back to a previous managed state
+- Inspects `config.toml` profiles through structured read commands
 
-Current version: `0.0.10`
+Current version: `0.0.11`
 
 ## Install
 
@@ -42,27 +45,36 @@ codexs --help
 
 ## Quick Start
 
-Take over an existing Codex directory:
+Initialize tool state and adopt an existing Codex runtime:
 
 ```bash
 codexs init
 codexs migrate
 ```
 
-Inspect managed providers:
+Inspect managed providers and config:
 
 ```bash
 codexs list
 codexs show my-provider
+codexs config show
 ```
 
-Add and switch:
+Add and switch a direct provider:
 
 ```bash
 codexs add my-provider --profile my-provider --api-key sk-xxx
 codexs switch my-provider
 ```
 
+Prepare GitHub Copilot and manage its bridge:
+
+```bash
+codexs login copilot
+codexs add copilot-main --copilot --profile copilot-main
+codexs bridge start copilot-main
+```
+
 Check runtime state:
 
 ```bash
@@ -75,17 +87,24 @@ codexs doctor
 
 ```bash
 codexs init
+codexs login copilot
 codexs migrate
 codexs list
 codexs show <provider>
 codexs current
 codexs status
+codexs config show [profile]
+codexs config list-profiles
 codexs add <provider> --profile <name> --api-key <key>
-codexs edit <provider> [--profile <name>] [--api-key <key>]
+codexs add <provider> --copilot --profile <name>
+codexs edit <provider>
 codexs switch <provider>
-codexs remove <provider>
+codexs bridge start [provider]
+codexs bridge status [provider]
+codexs bridge stop [provider]
+codexs remove <provider> [--force] [--switch-to <profile>]
 codexs import <file> [--merge]
-codexs export <file>
+codexs export <file> [--force]
 codexs backups list
 codexs rollback [backup-id]
 codexs doctor
@@ -94,41 +113,61 @@ codexs doctor
 Command help:
 
 ```bash
-codexs help switch
 codexs help init
+codexs help login
+codexs help add
+codexs help bridge
+codexs help config
 codexs help migrate
-codexs help setup
 ```
 
 ## How It Works
 
-By default, `codex-switch` operates on `~/.codex/`, and you can override the target with `--codex-dir`.
+Starting in `0.0.11`, `codex-switch` uses a dual-path model.
 
-Managed files:
+Tool home:
+
+```text
+~/.config/codex-switch/
+  codex-switch.json
+  providers.json
+  backups/
+  runtime/
+  runtimes/
+```
+
+Target Codex runtime:
 
 ```text
 ~/.codex/
   config.toml
   auth.json
-  providers.json
-  backups/
 ```
 
 Notes:
 
-- `providers.json` is the managed provider registry
-- `config.toml` is the managed runtime-routing file
-- `auth.json` is the active auth projection file; direct-provider switches rewrite `OPENAI_API_KEY`, while `status` and `doctor` inspect its state
-- mutating commands back up before writing
-- rollback is available after failed or undesired changes
+- `providers.json` is the managed provider registry and now lives under the tool home
+- `codex-switch.json` stores tool-level metadata such as `defaultCodexDir`
+- `config.toml` is still the active runtime-routing file in the target Codex directory
+- `auth.json` is the active auth projection file
+- direct-provider switches rewrite `OPENAI_API_KEY`
+- Copilot bridge providers keep upstream login in the official Copilot runtime while `codex-switch` manages the local bridge secret, bridge state, and routing
+- mutating commands back up before writing and rollback stays available after failed or undesired changes
+
+Path overrides and resolution:
+
+- `--codex-dir <path>` explicitly targets a Codex runtime directory
+- `CODEXS_CODEX_DIR` sets the default target when `--codex-dir` is not passed
+- `CODEXS_HOME` overrides the tool home location
 
 ## Automation
 
 This CLI supports both human TTY use and non-interactive automation.
 
 Current exceptions:
-- `init` is automation-friendly and idempotent, but still returns a structured error in non-interactive or `--json` mode when the resolved target directory does not exist.
-- `migrate` remains intentionally TTY-only for adopt initialization. It requires interactive profile selection and provider detail collection, and non-interactive/`--json` runs fail fast with a structured error.
+
+- `login copilot` requires a real TTY and does not support `--json`
+- `migrate` remains intentionally interactive for adopt profile selection and provider detail collection
 
 Recommended global flags:
 
@@ -144,6 +183,7 @@ Recommendations:
 - use `--json` for stable machine-readable output
 - pass all required arguments explicitly in scripts or CI
 - use `--codex-dir <path>` for sandbox or test environments
+- use `CODEXS_HOME` when you want tool state isolated from your default workstation setup
 
 ## Testing
 
@@ -152,24 +192,25 @@ Build and test locally:
 ```bash
 npm run build
 npm test
+npx tsc --noEmit
 ```
 
 The repository includes a development fixture under `dev-codex/local-sandbox` plus dedicated test docs:
 
-- [Testing Guide](./docs/testing.md)
-- [Test Report for 0.0.5](./docs/test-report-0.0.5.md)
+- [Testing Guide](./docs/Tests/testing.md)
+- [Bridge Testing Notes](./docs/Tests/testing-bridge-v0.0.9.md)
+- [Test Report for 0.0.7](./docs/Tests/test-report-0.0.7.md)
 
 ## Documentation
 
 - [Chinese README](./README.CN.md)
 - [AI README](./README.AI.md)
 - [Detailed CLI Usage](./docs/cli-usage.md)
-- [Testing Guide](./docs/testing.md)
-- [Test Report for 0.0.5](./docs/test-report-0.0.5.md)
+- [Testing Guide](./docs/Tests/testing.md)
 - [Product Overview](./docs/codex-switch-product-overview.md)
 - [Technical Architecture](./docs/codex-switch-technical-architecture.md)
-- [Design Doc 0.0.5](./docs/Design/codex-switch-v0.0.5-design.md)
-- [Design Doc 0.0.4](./docs/Design/codex-switch-v0.0.4-design.md)
+- [PRD 0.0.11](./docs/PRD/codex-switch-prd-v0.0.11.md)
+- [Design Doc 0.0.11](./docs/Design/codex-switch-v0.0.11-design.md)
 
 ## License
 

package/dist/app/add-provider.js

@@ -41,12 +41,13 @@ const errors_1 = require("../domain/errors");
 const config_repo_1 = require("../storage/config-repo");
 const fs_utils_1 = require("../storage/fs-utils");
 const providers_repo_1 = require("../storage/providers-repo");
+const copilot_adapter_1 = require("../runtime/copilot-adapter");
 const copilot_installer_1 = require("../runtime/copilot-installer");
 const run_mutation_1 = require("./run-mutation");
 /**
  * Adds a new provider record to the managed providers registry.
  */
-function addProvider(args) {
+async function addProvider(args) {
     (0, fs_utils_1.ensureDir)(args.codexDir);
     const providers = (0, providers_repo_1.readProvidersFileIfExists)(args.providersPath);
     if (providers.providers[args.providerName]) {
@@ -67,17 +68,26 @@ function addProvider(args) {
         }
         : undefined;
     if (args.copilot) {
-        const installStatus = (0, copilot_installer_1.probeCopilotSdkInstall)();
+        const installStatus = (0, copilot_installer_1.probeCopilotSdkInstall)(args.runtimesDir);
         if (!installStatus.installed) {
-            if (!args.installCopilotSdk) {
-                throw (0, errors_1.cliError)(args.interactive ? "COPILOT_SDK_MISSING" : "COPILOT_SDK_INSTALL_REQUIRES_TTY", args.interactive
-                    ? "The optional Copilot SDK runtime is not installed. Re-run with --install-copilot-sdk or confirm installation interactively."
-                    : "The optional Copilot SDK runtime is not installed. Pass --install-copilot-sdk when running non-interactively.", {
-                    installDir: installStatus.installDir,
-                    packageName: installStatus.packageName,
+            throw (0, errors_1.cliError)("COPILOT_SDK_MISSING", "The optional Copilot SDK runtime is not installed. Run `codexs login copilot` first.", {
+                installDir: installStatus.installDir,
+                packageName: installStatus.packageName,
+                suggestion: "Run `codexs login copilot` to install the Copilot SDK and complete login.",
+            });
+        }
+        try {
+            await (0, copilot_adapter_1.readCopilotAuthState)(args.runtimesDir);
+        }
+        catch (error) {
+            const normalized = (0, errors_1.normalizeError)(error);
+            if (normalized.code === "COPILOT_AUTH_REQUIRED") {
+                throw (0, errors_1.cliError)("COPILOT_AUTH_REQUIRED", "Copilot authentication is required before a Copilot provider can be added.", {
+                    ...(normalized.details ?? {}),
+                    suggestion: "Run `codexs login copilot` to complete GitHub Copilot login.",
                 });
             }
-            (0, copilot_installer_1.installCopilotSdk)();
+            throw error;
         }
     }
     const document = (0, config_repo_1.readStructuredConfig)(args.configPath);
@@ -97,13 +107,17 @@ function addProvider(args) {
             }),
         }
         : undefined;
-    const upsertModelProviders = !existingModelProvider && args.createProfile
+    const upsertModelProviders = args.copilot
         ? {
-            [args.profile]: {
-                baseUrl: args.copilot ? (0, providers_1.buildCopilotBridgeBaseUrl)(runtime) : args.baseUrl ?? undefined,
-            },
+            [args.profile]: (0, providers_1.buildCopilotModelProviderProjection)(runtime),
         }
-        : undefined;
+        : !existingModelProvider && args.createProfile
+            ? {
+                [args.profile]: {
+                    baseUrl: args.baseUrl ?? undefined,
+                },
+            }
+            : undefined;
     if (existingProfile) {
         (0, config_repo_1.requireManagedProfileRuntime)(document, providers, args.profile);
     }
@@ -123,7 +137,7 @@ function addProvider(args) {
         },
     };
     return (0, run_mutation_1.runMutation)({
-        codexDir: args.codexDir,
+        lockPath: args.lockPath,
         backupsDir: args.backupsDir,
         latestBackupPath: args.latestBackupPath,
         operation: "add",