@minniexcode/codex-switch 0.0.9 → 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,22 +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` and `auth.json` are runtime mirrors
-- `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
 
@@ -64,8 +92,11 @@ Operational model:
 src/
   app/
   cli/
+  commands/
   domain/
-  infra/
+  interaction/
+  runtime/
+  storage/
 tests/
 docs/
 dist/
@@ -73,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
 
@@ -86,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
@@ -93,12 +128,14 @@ codexs status --json
 Current package version in this repository:
 
 ```text
-0.0.7
+0.0.11
 ```
 
 Recent version summary:
 
-- `0.0.7`: command-surface refactor, env_key/auth-mirror model corrections, and the `setup` split into `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
@@ -109,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,45 +2,61 @@
 
 `@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 这类交互式上游登录提供独立入口
 
 ## 现在可以做什么
 
-当前 MVP 命令如下：
+当前公开命令面如下：
 
 ```bash
+codexs init
+codexs login copilot
+codexs migrate
 codexs list
+codexs show <provider>
 codexs current
-codexs switch <provider>
 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
 ```
 
 对应能力包括：
 
-- 查看本地已管理的 provider
-- 查看当前激活的 profile
-- 安全切换 provider
-- 导入和导出 provider 映射
-- 新增和删除 provider
+- 初始化独立的 tool home 与空的受管 `providers.json`
+- 从已有 `config.toml` adopt 可管理的 runtime profile
+- 查看本地已管理 provider
+- 查看结构化 config profile 视图
+- 编辑、切换、导入、导出、删除 provider
+- 为 GitHub Copilot 完成上游 SDK 安装与登录检查
+- 显式启动、查看和停止本地 Copilot bridge
 - 检查配置漂移和常见本地问题
 - 在变更前自动备份，并在失败时回滚
+- 保留 `setup` 作为弃用入口，并引导到 `init` / `migrate`
 
 ## 简单用法
 
@@ -65,18 +81,29 @@ codexs --help
 典型使用方式：
 
 ```bash
+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
 ```
 
 通用参数：
@@ -86,6 +113,13 @@ codexs status --json
 --codex-dir <path>
 ```
 
+环境变量：
+
+```bash
+CODEXS_HOME
+CODEXS_CODEX_DIR
+```
+
 ## 交互式体验
 
 这个 CLI 同时支持显式命令和交互式终端流程。
@@ -94,57 +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` 是运行态文件
+- `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.3
+### 0.0.10
 
-- 为 `add`、`switch`、`remove`、`import`、`export`、`rollback` 增加了交互式 TTY 流程
-- 改进了帮助信息和命令级使用说明
-- 增强了交互行为和参数处理相关测试覆盖
+- 正式拆分 `setup`：新增 `init` 和 `migrate`，`setup` 变为弃用命令
+- 收紧迁移、诊断、回滚和发布正确性边界
+- 清理 provider/runtime 管理语义，CLI 聚焦静态 profile 与 `base_url` 层配置
 
-### 0.0.2
+### 0.0.7
 
-- 增加了统一的变更编排能力，包括写前备份、失败回滚和单进程锁
-- 改进了 `status` 和 `doctor`，更清晰地识别运行态漂移
-- 加强了底层仓储层和领域层，使配置写入更安全
+- 完成 command-surface 重构
+- 校正 env key / auth mirror 相关模型
+- 推进 `setup` 向 `init` + `migrate` 的拆分
 
-### 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)
 
 ## 本地开发
 
@@ -152,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.8`
+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,40 +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` and `auth.json` represent runtime 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:
 
@@ -143,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
 
@@ -151,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