@minniexcode/codex-switch 0.0.10 → 0.0.12

package/README.AI.md

@@ -1,115 +1,110 @@
 # AI README
 
-This file is for AI agents, automation scripts, and contributors who need a compact operational summary of the repository.
+This file summarizes the current operational contract for AI agents, automation scripts, and contributors.
 
-## Repository Purpose
+## Package Context
 
-`@minniexcode/codex-switch` is a local-first TypeScript CLI for managing provider/profile state for Codex under `~/.codex/`.
+- Package: `@minniexcode/codex-switch`
+- CLI name: `codexs`
+- Current repository version: `0.0.12`
+- Version status: development-version software, not a stable `0.1.0` release yet
 
-Primary goals:
+## Product Role
 
-- safe local profile switching
-- backup-before-write mutation flows
-- rollback on failure
-- stable machine-readable CLI output
-- support for both human TTY usage and agent automation
+`codex-switch` is a local-first TypeScript CLI that manages provider and profile state for Codex while keeping tool-managed state separate from the target Codex runtime.
 
-## Main Command Surface
+The managed source of truth is the tool home. Runtime files under the target Codex directory are projected outputs, not the main registry.
+
+## Primary Workflows
+
+Direct provider workflow:
 
 ```bash
 codexs init
-codexs migrate
-codexs list
-codexs show <provider>
-codexs current
+codexs add <provider> --profile <name> --api-key <key>
+codexs switch <provider>
 codexs status
-codexs edit <provider>
+codexs doctor
+```
+
+GitHub Copilot workflow:
+
+```bash
+codexs init
+codexs login copilot
+codexs add <provider> --copilot --profile <name>
 codexs switch <provider>
-codexs import <file>
-codexs export <file>
-codexs add <provider>
-codexs remove <provider>
-codexs backups list
+codexs status
 codexs doctor
-codexs rollback [backup-id]
 ```
 
-Shared flags:
+Advanced adopt workflow:
 
 ```bash
---json
---codex-dir <path>
+codexs init
+codexs migrate
 ```
 
-## Important Runtime Files
+`migrate` is not a fresh-install default. It is an advanced adopt helper for existing runtime state.
+
+## Important Paths
+
+Tool home:
 
 ```text
-~/.codex/
-  config.toml
-  auth.json
+~/.config/codex-switch/
+  codex-switch.json
   providers.json
   backups/
+  runtime/
+  runtimes/
 ```
 
-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
-
-## Project Structure
+Target Codex runtime:
 
 ```text
-src/
-  app/
-  cli/
-  domain/
-  infra/
-tests/
-docs/
-dist/
+~/.codex/
+  config.toml
+  auth.json
 ```
 
-Layer intent:
+Operational meaning:
 
-- `cli`: argument parsing, help, TTY flows, output shaping
-- `app`: command orchestration and use-case logic
-- `domain`: pure domain rules and shared models
-- `infra`: filesystem, lock, backup, config, and Codex integration code
+- `providers.json` is the managed provider registry.
+- `codex-switch.json` stores tool-level metadata such as the default target Codex directory.
+- `config.toml` is the active runtime routing file.
+- `auth.json` is the active auth projection file.
 
-## Command Entry Point
+## Command Notes
 
-Use `codexs` directly for runtime interaction:
+Shared flags:
 
 ```bash
-codexs --help
-codexs list --json
-codexs status --json
+--json
+--codex-dir <path>
+--help
+--version
 ```
 
-## Current Version Context
-
-Current package version in this repository:
+Relevant environment variables:
 
-```text
-0.0.10
+```bash
+CODEXS_HOME
+CODEXS_CODEX_DIR
 ```
 
-Recent version summary:
+Important behavioral constraints:
 
-- `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.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
-- `0.0.1`: initial TypeScript CLI and baseline docs
+- Prefer `--json` for programmatic invocation whenever the command supports it.
+- `login copilot` requires a real TTY and does not support `--json`.
+- `login copilot` currently installs the local Copilot SDK when needed, tries the bundled runtime CLI first, falls back to `PATH` when necessary, and rechecks auth readiness before reporting success.
+- `add --copilot` assumes SDK install and upstream Copilot auth are already ready.
+- `migrate` still depends on interactive profile selection and provider-detail collection in this release.
+- `status` is the main dual-path summary command.
+- `doctor` is the deeper repair-oriented diagnostic command.
 
-## Notes For Agents
+## Safety Notes
 
-- 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
-- Use `docs/` for deeper product and architecture context
+- Treat `providers.json` as sensitive because it may contain API keys.
+- Human-readable output may mask secrets, but JSON output can expose full provider payloads.
+- Managed write operations rely on backup and rollback flow; do not describe manual file edits as the primary workflow.

package/README.CN.md

@@ -1,182 +1,179 @@
 # @minniexcode/codex-switch
 
-`@minniexcode/codex-switch` 是一个本地优先的 CLI，用来安全地管理和切换 Codex 的 provider/profile 配置。
+`@minniexcode/codex-switch` 是一个本地优先的 CLI，用来安全地管理和切换 Codex 的 provider 与 profile 配置。
 
-它主要解决这样一个问题：如果你同时使用多个 Codex provider、API key 或 profile，不想再手动改 `~/.codex/` 里的文件，就可以用这个工具做统一管理和安全切换。
+它把 `codex-switch` 自己的工具状态和目标 Codex runtime 明确分开，让 provider 管理、备份与 runtime 投影有一套受管流程，而不是依赖手工改文件。
 
-## 这个仓库是做什么的
+## 版本定位
 
-这个仓库包含 `codex-switch` 的 CLI 实现、npm 包配置，以及相关产品和技术文档。
+当前包版本：`0.0.12`
 
-项目目标很明确：
+当前仍处于开发版本阶段。这个版本的重点不是继续扩命令面，而是把主工作流、帮助文案和实际行为统一到同一套契约上。
 
-- 在本地完成 Codex 配置切换
-- 写入前先备份
-- 出错时可回滚
-- 同时兼顾终端用户和 AI/自动化调用
-
-## 现在可以做什么
-
-当前命令面如下：
-
-```bash
-codexs init
-codexs migrate
-codexs list
-codexs show <provider>
-codexs current
-codexs status
-codexs edit <provider>
-codexs switch <provider>
-codexs import <file>
-codexs export <file>
-codexs add <provider>
-codexs remove <provider>
-codexs backups list
-codexs doctor
-codexs rollback
-codexs setup
-```
-
-对应能力包括：
-
-- 初始化空的受管 `providers.json`
-- 从已有 `config.toml` adopt 可管理的 runtime profile
-- 查看本地已管理的 provider
-- 查看单个 provider 详情
-- 查看当前激活的 profile
-- 查看本地运行态摘要
-- 编辑已有 provider
-- 安全切换 provider
-- 导入和导出 provider 映射
-- 新增和删除 provider
-- 查看备份列表
-- 检查配置漂移和常见本地问题
-- 在变更前自动备份，并在失败时回滚
-- 保留 `setup` 作为弃用入口，并引导到 `init` / `migrate`
-
-## 简单用法
-
-全局安装：
+## 安装
 
 ```bash
 npm install -g @minniexcode/codex-switch
 ```
 
-或者直接执行：
+不全局安装时也可以直接运行：
 
 ```bash
 npx @minniexcode/codex-switch --help
 ```
 
-检查 CLI 是否可用：
+CLI 命令名：
 
 ```bash
 codexs --help
 ```
 
-典型使用方式：
+## 主工作流
+
+Direct provider 主路径：
 
 ```bash
 codexs init
-codexs migrate
-codexs list
-codexs current
 codexs add my-provider --profile my-provider --api-key sk-xxx
 codexs switch my-provider
 codexs status
+codexs doctor
 ```
 
-给脚本或 AI 使用时建议加上：
+GitHub Copilot 主路径：
 
 ```bash
-codexs list --json
-codexs status --json
+codexs init
+codexs login copilot
+codexs add copilot-main --copilot --profile copilot-main
+codexs switch copilot-main
+codexs status
+codexs doctor
 ```
 
-通用参数：
+说明：
+
+- `init` 负责初始化 `codex-switch` 的 tool home 与受管状态文件。
+- `login copilot` 负责上游 Copilot onboarding 和登录可用性检查。
+- `add --copilot` 不负责替你登录，它假设上游 Copilot 已经 ready。
+- `status` 是切换后的主读取命令。
+- `doctor` 是主诊断命令，用于解释问题和下一步修复动作。
+
+## Advanced Adopt 路径
+
+如果你已经有现成的 Codex runtime 状态，希望把它 adopt 到受管 `providers.json`，再使用：
 
 ```bash
---json
---codex-dir <path>
+codexs init
+codexs migrate
 ```
 
-## 交互式体验
+`migrate` 是高级 adopt helper，不是 fresh install 的默认第一步。
 
-这个 CLI 同时支持显式命令和交互式终端流程。
+## 命令面
 
-- `codexs add` 在 TTY 里会补问缺失的必填项
-- `codexs switch` 在未传 provider 时可以弹出选择列表
-- `codexs remove` 支持交互式选择和确认删除
-- `import`、`export`、`rollback` 在交互模式下会要求确认
-- `--json` 模式保持非交互，适合自动化
+```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 add <provider> --copilot --profile <name>
+codexs edit <provider>
+codexs switch <provider>
+codexs remove <provider> [--force] [--switch-to <profile>]
+codexs import <file>
+codexs export <file> [--force]
+codexs bridge start [provider]
+codexs bridge status [provider]
+codexs bridge stop [provider]
+codexs backups list
+codexs rollback [backup-id]
+codexs doctor
+```
+
+`setup` 仍然存在，但只作为已弃用兼容入口，用来提示调用方改用 `init` 或 `migrate`。
 
-## 管理哪些文件
+## 双路径模型
 
-`codex-switch` 主要围绕 `~/.codex/` 下的这些文件工作：
+tool home：
 
 ```text
-~/.codex/
-  config.toml
-  auth.json
+~/.config/codex-switch/
+  codex-switch.json
   providers.json
   backups/
+  runtime/
+  runtimes/
 ```
 
-存储模型：
-
-- `providers.json` 是管理态的单一事实来源
-- `config.toml` 是受管的运行时路由文件
-- `auth.json` 是独立的 Codex 认证状态文件，`status` / `doctor` 只读检查它
-- `backups/latest.json` 记录最近一次可回滚窗口
+目标 Codex runtime：
 
-注意：`providers.json` 可能包含 API key，应视为本地敏感文件。
-
-## 相关文档
+```text
+~/.codex/
+  config.toml
+  auth.json
+```
 
-- [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)
+关键边界：
 
-## 最近 3 个版本更新
+- `providers.json` 是受管 provider 注册表，位于 tool home。
+- `codex-switch.json` 保存工具级元数据，例如 `defaultCodexDir`。
+- `config.toml` 仍然是目标 runtime 里的活动路由文件。
+- `auth.json` 仍然是目标 runtime 里的活动认证投影文件。
+- Direct provider 切换会改写活动 runtime 中的 `OPENAI_API_KEY`。
+- Copilot provider 保持上游 GitHub 登录留在官方 Copilot runtime 中，`codex-switch` 只管理本地 bridge 状态与路由。
 
-### 0.0.10
+路径控制：
 
-- 正式拆分 `setup`：新增 `init` 和 `migrate`，`setup` 变为弃用命令
-- 增加 `show`、`edit`、`backups list` 等对当前命令面的整理
-- 清理 provider/runtime 管理语义，CLI 只负责静态 profile 与 `base_url` 层配置
+- `--codex-dir <path>` 显式指定目标 Codex runtime 目录。
+- `CODEXS_CODEX_DIR` 在未传 `--codex-dir` 时提供默认目标目录。
+- `CODEXS_HOME` 用于覆盖 tool home 位置。
 
-### 0.0.3
+## 自动化说明
 
-- 为 `add`、`switch`、`remove`、`import`、`export`、`rollback` 增加了交互式 TTY 流程
-- 改进了帮助信息和命令级使用说明
-- 增强了交互行为和参数处理相关测试覆盖
+这个 CLI 同时支持人类终端使用和非交互自动化。
 
-### 0.0.2
+全局参数：
 
-- 增加了统一的变更编排能力，包括写前备份、失败回滚和单进程锁
-- 改进了 `status` 和 `doctor`，更清晰地识别运行态漂移
-- 加强了底层仓储层和领域层，使配置写入更安全
+```bash
+--json
+--codex-dir <path>
+--help
+--version
+```
 
-### 0.0.1
+当前实现边界：
 
-- 发布了第一版 TypeScript CLI 实现
-- 落地了核心 MVP 命令和基于文件的 provider 管理模型
-- 补齐了首批产品、架构和命令设计文档
+- `login copilot` 必须运行在真实 TTY 下，不支持 `--json`。
+- `migrate` 在当前版本仍然依赖交互式 profile 选择和 provider 细节补全。
+- 自动化调用应尽量显式传参，并优先使用 `--json`。
 
 ## 本地开发
 
 ```bash
-npm install
 npm run build
 npm test
+npx tsc --noEmit
 node dist/cli.js --help
+npm pack --dry-run
 ```
 
+## 相关文档
+
+- [English README](./README.md)
+- [AI README](./README.AI.md)
+- [详细 CLI 文档](./docs/cli-usage.md)
+- [产品概览](./docs/codex-switch-product-overview.md)
+- [测试说明](./docs/Tests/testing.md)
+- [PRD 0.0.12](./docs/PRD/codex-switch-prd-v0.0.12.md)
+- [Release Gate PRD 0.1.0](./docs/PRD/codex-switch-prd-v0.1.0.md)
+
 ## License
 
 MIT