@minniexcode/codex-switch 0.0.2 → 0.0.4

package/README.AI.md

@@ -0,0 +1,110 @@
+# AI README
+
+This file is for AI agents, automation scripts, and contributors who need a compact operational summary of the repository.
+
+## Repository Purpose
+
+`@minniexcode/codex-switch` is a local-first TypeScript CLI for managing provider/profile state for Codex under `~/.codex/`.
+
+Primary goals:
+
+- 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
+
+## Main Command Surface
+
+```bash
+codexs setup
+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 [backup-id]
+```
+
+Shared flags:
+
+```bash
+--json
+--codex-dir <path>
+```
+
+## Important Runtime Files
+
+```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
+
+## Project Structure
+
+```text
+src/
+  app/
+  cli/
+  domain/
+  infra/
+tests/
+docs/
+dist/
+```
+
+Layer intent:
+
+- `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
+
+## Command Entry Point
+
+Use `codexs` directly for runtime interaction:
+
+```bash
+codexs --help
+codexs list --json
+codexs status --json
+```
+
+## Current Version Context
+
+Current package version in this repository:
+
+```text
+0.0.4
+```
+
+Recent version summary:
+
+- `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
+
+## Notes For Agents
+
+- 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`
+- Use `docs/` for deeper product and architecture context

package/README.CN.md

@@ -0,0 +1,160 @@
+# @minniexcode/codex-switch
+
+`@minniexcode/codex-switch` 是一个本地优先的 CLI，用来安全地管理和切换 Codex 的 provider/profile 配置。
+
+它主要解决这样一个问题：如果你同时使用多个 Codex provider、API key 或 profile，不想再手动改 `~/.codex/` 里的文件，就可以用这个工具做统一管理和安全切换。
+
+## 这个仓库是做什么的
+
+这个仓库包含 `codex-switch` 的 CLI 实现、npm 包配置，以及相关产品和技术文档。
+
+项目目标很明确：
+
+- 在本地完成 Codex 配置切换
+- 写入前先备份
+- 出错时可回滚
+- 同时兼顾终端用户和 AI/自动化调用
+
+## 现在可以做什么
+
+当前 MVP 命令如下：
+
+```bash
+codexs list
+codexs current
+codexs switch <provider>
+codexs status
+codexs import <file>
+codexs export <file>
+codexs add <provider>
+codexs remove <provider>
+codexs doctor
+codexs rollback
+```
+
+对应能力包括：
+
+- 查看本地已管理的 provider
+- 查看当前激活的 profile
+- 安全切换 provider
+- 导入和导出 provider 映射
+- 新增和删除 provider
+- 检查配置漂移和常见本地问题
+- 在变更前自动备份，并在失败时回滚
+
+## 简单用法
+
+全局安装：
+
+```bash
+npm install -g @minniexcode/codex-switch
+```
+
+或者直接执行：
+
+```bash
+npx @minniexcode/codex-switch --help
+```
+
+检查 CLI 是否可用：
+
+```bash
+codexs --help
+```
+
+典型使用方式：
+
+```bash
+codexs list
+codexs current
+codexs add my-provider --profile my-provider --api-key sk-xxx
+codexs switch my-provider
+codexs status
+```
+
+给脚本或 AI 使用时建议加上：
+
+```bash
+codexs list --json
+codexs status --json
+```
+
+通用参数：
+
+```bash
+--json
+--codex-dir <path>
+```
+
+## 交互式体验
+
+这个 CLI 同时支持显式命令和交互式终端流程。
+
+- `codexs add` 在 TTY 里会补问缺失的必填项
+- `codexs switch` 在未传 provider 时可以弹出选择列表
+- `codexs remove` 支持交互式选择和确认删除
+- `import`、`export`、`rollback` 在交互模式下会要求确认
+- `--json` 模式保持非交互，适合自动化
+
+## 管理哪些文件
+
+`codex-switch` 主要围绕 `~/.codex/` 下的这些文件工作：
+
+```text
+~/.codex/
+  config.toml
+  auth.json
+  providers.json
+  backups/
+```
+
+存储模型：
+
+- `providers.json` 是管理态的单一事实来源
+- `config.toml` 和 `auth.json` 是运行态文件
+- `backups/latest.json` 记录最近一次可回滚窗口
+
+注意：`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)
+
+## 最近 3 个版本更新
+
+### 0.0.3
+
+- 为 `add`、`switch`、`remove`、`import`、`export`、`rollback` 增加了交互式 TTY 流程
+- 改进了帮助信息和命令级使用说明
+- 增强了交互行为和参数处理相关测试覆盖
+
+### 0.0.2
+
+- 增加了统一的变更编排能力，包括写前备份、失败回滚和单进程锁
+- 改进了 `status` 和 `doctor`，更清晰地识别运行态漂移
+- 加强了底层仓储层和领域层，使配置写入更安全
+
+### 0.0.1
+
+- 发布了第一版 TypeScript CLI 实现
+- 落地了核心 MVP 命令和基于文件的 provider 管理模型
+- 补齐了首批产品、架构和命令设计文档
+
+## 本地开发
+
+```bash
+npm install
+npm run build
+npm test
+node dist/cli.js --help
+```
+
+## License
+
+MIT

package/README.md

@@ -1,193 +1,231 @@
 # @minniexcode/codex-switch
 
-`@minniexcode/codex-switch` is a local-first CLI for managing and switching Codex provider/profile configuration safely.
+`codex-switch` is a local-first CLI for managing and switching Codex provider/profile configuration safely.
 
-Current product direction:
+`codex-switch` 是一个本地优先的 CLI，用来安全地管理和切换 Codex 的 provider/profile 配置。
 
-- CLI-first
-- local-first
-- safe by default
-- AI-friendly
+It is designed for users who work with multiple Codex providers, API keys, or profiles and want a repeatable, backup-first workflow instead of manually editing files under `~/.codex/`.
 
-The intended command name is:
+它面向同时维护多个 Codex provider、API key 或 profile 的用户，目标是用可重复、先备份再写入的方式替代手动修改 `~/.codex/` 下的文件。
 
-```bash
-codexs
-```
+## Overview | 简介
 
-## Status
+What it does:
 
-The repository now contains the first end-to-end modular CLI implementation for the MVP command set defined in `docs/`.
+- Initialize `providers.json` 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 rollback to a previous managed state
 
-The project is implemented as a TypeScript CLI, builds into `dist/`, and is organized into `cli`, `app`, `domain`, and `infra` layers for maintainability.
+它可以完成的事情：
 
-## Why This Exists
+- 从现有 Codex 目录初始化 `providers.json`
+- 查看、新增、编辑、删除 provider 记录
+- 安全切换当前激活的 provider/profile
+- 导入和导出 provider 配置
+- 运行诊断并识别本地配置漂移
+- 查看备份并回滚到之前的受管状态
 
-Managing multiple Codex providers or profiles locally usually falls into two bad options:
+Current version: `0.0.4`
 
-- ad hoc scripts that work once but are hard to maintain
-- heavier account or desktop tools that solve a broader problem than local switching
+当前版本：`0.0.4`
 
-`@minniexcode/codex-switch` sits between those extremes. It aims to provide a stable CLI interface for:
+## Install | 安装
 
-- viewing the current Codex profile
-- listing locally configured providers
-- switching providers safely
-- backing up config before mutation
-- rolling back on failure
-- importing and exporting provider mappings
-- returning structured output for automation and AI agents
+Install globally:
 
-## Product Definition
+```bash
+npm install -g @minniexcode/codex-switch
+```
 
-`@minniexcode/codex-switch` is intended to manage files under `~/.codex/`:
+Or run directly:
 
-```text
-~/.codex/
-  config.toml
-  auth.json
-  providers.json
-  backups/
+```bash
+npx @minniexcode/codex-switch --help
 ```
 
-Core design principles:
+全局安装：
+
+```bash
+npm install -g @minniexcode/codex-switch
+```
 
-- `providers.json` is the management-state single source of truth for provider metadata and mappings
-- `config.toml` and `auth.json` are runtime mirrors that codex-switch synchronizes safely
-- `backups/latest.json` tracks rollback state for the latest managed mutation window
-- all writes should be backed up first
-- failures should trigger rollback
-- write operations should execute under a lightweight single-process file lock
-- CLI output should stay stable and machine-readable
+或者直接运行：
 
-## MVP Commands
+```bash
+npx @minniexcode/codex-switch --help
+```
 
-The current MVP command surface is:
+CLI entry:
 
 ```bash
-codexs list
-codexs current
-codexs switch <provider>
-codexs status
-codexs import <file>
-codexs export <file>
-codexs add <provider>
-codexs remove <provider>
-codexs doctor
-codexs rollback
+codexs --help
 ```
 
-Shared flags:
+命令入口：
 
 ```bash
---json
---codex-dir <path>
+codexs --help
 ```
 
-## Example Provider Model
+## Quick Start | 快速开始
 
-Planned `providers.json` shape:
+Take over an existing Codex directory:
 
-```json
-{
-  "providers": {
-    "packycode": {
-      "profile": "packycode",
-      "apiKey": "sk-xxx",
-      "baseUrl": "https://example.com/v1",
-      "note": "primary free model route",
-      "tags": ["free", "daily"]
-    }
-  }
-}
+```bash
+codexs setup
 ```
 
-`providers.json` should be treated as a local secret because it may contain API keys.
+接管当前已有的 Codex 目录：
 
-## Install
+```bash
+codexs setup
+```
 
-Global install:
+Inspect managed providers:
 
 ```bash
-npm install -g @minniexcode/codex-switch
+codexs list
+codexs show my-provider
 ```
 
-One-off execution:
+查看已管理的 provider：
 
 ```bash
-npx @minniexcode/codex-switch
+codexs list
+codexs show my-provider
 ```
 
-Current CLI entry check:
+Add and switch:
 
 ```bash
-codexs --help
+codexs add my-provider --profile my-provider --api-key sk-xxx
+codexs switch my-provider
 ```
 
-## Current Repository Contents
+新增并切换：
+
+```bash
+codexs add my-provider --profile my-provider --api-key sk-xxx
+codexs switch my-provider
+```
 
-This repository contains both the product documents and the CLI implementation:
+Check runtime state:
 
-- [Product Overview](./docs/codex-switch-product-overview.md)
-- [Product Research](./docs/codex-switch-product-research.md)
-- [PRD](./docs/codex-switch-prd.md)
-- [Technical Architecture](./docs/codex-switch-technical-architecture.md)
-- [Command Design](./docs/codex-switch-command-design.md)
+```bash
+codexs current
+codexs status
+codexs doctor
+```
+
+检查当前运行状态：
+
+```bash
+codexs current
+codexs status
+codexs doctor
+```
+
+## Common Commands | 常用命令
+
+```bash
+codexs setup
+codexs list
+codexs show <provider>
+codexs current
+codexs status
+codexs add <provider> --profile <name> --api-key <key>
+codexs edit <provider> [--profile <name>] [--api-key <key>]
+codexs switch <provider>
+codexs remove <provider>
+codexs import <file> [--merge]
+codexs export <file>
+codexs backups list
+codexs rollback [backup-id]
+codexs doctor
+```
 
-## Implementation Notes
+Command help:
 
-Current implementation characteristics:
+```bash
+codexs help switch
+codexs help setup
+```
 
-- modular TypeScript architecture split into `app`, `domain`, `infra`, and `cli`
-- repository-style infra modules for providers, config, backups, and write locks
-- a shared mutation orchestration contract that wraps backup, rollback, and lock handling
-- safe write flows with backup manifests under `backups/`
-- rollback support for `config.toml` and optional `auth.json`
-- `status` and `doctor` expose live-state drift so future backfill/edit/sync flows can reuse the same core model
-- stable `--json` envelopes for automation
-- test coverage in `tests/` using a custom serial runner (`tests/run-tests.js`) because the current environment hits `node --test` worker/spawn restrictions
+命令帮助：
 
-## Storage Model
+```bash
+codexs help switch
+codexs help setup
+```
 
-The current storage model is intentionally split:
+## How It Works | 工作方式
 
-- management state: `providers.json`
-- runtime state: `config.toml` and `auth.json`
-- rollback state: `backups/latest.json` and timestamped backup manifests
+By default, `codex-switch` operates on `~/.codex/`, and you can override the target with `--codex-dir`.
 
-That keeps the MVP file-based while preserving the same boundary a future database-backed registry would use.
+`codex-switch` 默认围绕 `~/.codex/` 工作，也可以通过 `--codex-dir` 指向其他目录。
 
-## Concurrency And Drift
+Managed files:
 
-Current write semantics are intentionally lightweight:
+```text
+~/.codex/
+  config.toml
+  auth.json
+  providers.json
+  backups/
+```
 
-- every mutating command runs inside `~/.codex/.codex-switch.lock`
-- each mutation creates a backup first and rolls back on failure
-- `status` and `doctor` detect when the active runtime profile in `config.toml` is no longer mapped in `providers.json`
+说明：
 
-That drift signal is the contract for future `edit`, `sync`, and explicit backfill flows. The current version detects and reports drift, but does not silently write live runtime changes back into the management registry.
+- `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
 
-## Non-Goals for MVP
+- `providers.json` 是受管理的 provider 注册表
+- `config.toml` 和 `auth.json` 代表当前运行态
+- 所有写操作都会先备份再写入
+- 变更失败或结果不符合预期时可以回滚
 
-The first version is not trying to be:
+## Automation | 自动化
 
-- a GUI or desktop app
-- a background daemon
-- a full account management platform
-- a proxy/router layer
-- a remote sync service
+This CLI supports both human TTY use and non-interactive automation.
 
-## Development
+这个 CLI 同时支持人工交互和非交互自动化。
 
-Local development:
+Recommended global flags:
 
 ```bash
-npm install
-npm run build
-npm test
-node dist/cli.js --help
+--json
+--codex-dir <path>
+--help
+--version
 ```
 
-## License
+建议：
+
+- 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
+
+- 在脚本或 CI 中使用 `--json` 获取稳定输出
+- 在非交互环境中显式传入所有必需参数
+- 在测试环境中优先配合 `--codex-dir <path>` 使用
+
+## Documentation | 文档
+
+- [Detailed CLI Usage](./docs/cli-usage.md)
+- [详细 CLI 使用文档](./docs/cli-usage.md)
+- [Changelog](./CHANGELOG.md)
+- [更新日志](./CHANGELOG.md)
+- [AI README](./README.AI.md)
+- [中文 README（历史版）](./README.CN.md)
+- [Product Overview](./docs/codex-switch-product-overview.md)
+- [Technical Architecture](./docs/codex-switch-technical-architecture.md)
+- [0.0.4 Design Doc](./docs/codex-switch-v0.0.4-design.md)
+
+## License | 许可证
 
 MIT

package/dist/app/edit-provider.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.editProvider = editProvider;
+const errors_1 = require("../domain/errors");
+const providers_1 = require("../domain/providers");
+const fs_utils_1 = require("../infra/fs-utils");
+const providers_repo_1 = require("../infra/providers-repo");
+const run_mutation_1 = require("./run-mutation");
+/**
+ * Updates selected fields on a single managed provider.
+ */
+function editProvider(args) {
+    (0, fs_utils_1.ensureDir)(args.codexDir);
+    const providers = (0, providers_repo_1.readProvidersFile)(args.providersPath);
+    const current = providers.providers[args.providerName];
+    if (!current) {
+        throw (0, errors_1.cliError)("PROVIDER_NOT_FOUND", `Provider "${args.providerName}" was not found.`, {
+            provider: args.providerName,
+            file: args.providersPath,
+        });
+    }
+    const updatedFields = [];
+    const nextRecord = (0, providers_1.cleanProviderRecord)({
+        profile: args.profile ?? current.profile,
+        apiKey: args.apiKey ?? current.apiKey,
+        baseUrl: args.baseUrl === null ? undefined : args.baseUrl ?? current.baseUrl,
+        note: args.note === null ? undefined : args.note ?? current.note,
+        tags: args.tags ?? current.tags,
+    });
+    if (args.profile !== undefined && args.profile !== current.profile) {
+        updatedFields.push("profile");
+    }
+    if (args.apiKey !== undefined && args.apiKey !== current.apiKey) {
+        updatedFields.push("apiKey");
+    }
+    if (args.baseUrl !== undefined && (args.baseUrl ?? undefined) !== current.baseUrl) {
+        updatedFields.push("baseUrl");
+    }
+    if (args.note !== undefined && (args.note ?? undefined) !== current.note) {
+        updatedFields.push("note");
+    }
+    if (args.tags !== undefined) {
+        updatedFields.push("tags");
+    }
+    return (0, run_mutation_1.runMutation)({
+        codexDir: args.codexDir,
+        backupsDir: args.backupsDir,
+        latestBackupPath: args.latestBackupPath,
+        operation: "edit",
+        files: [{ absolutePath: args.providersPath, relativePath: "providers.json" }],
+        mutate: () => {
+            (0, providers_repo_1.writeProvidersFile)(args.providersPath, {
+                providers: {
+                    ...providers.providers,
+                    [args.providerName]: nextRecord,
+                },
+            });
+            return {
+                provider: args.providerName,
+                updatedFields,
+            };
+        },
+    });
+}