@minniexcode/codex-switch 0.0.3 → 0.0.5

package/README.AI.md

@@ -17,16 +17,20 @@ Primary goals:
 ## Main Command Surface
 
 ```bash
+codexs setup
 codexs list
+codexs show <provider>
 codexs current
-codexs switch <provider>
 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 rollback [backup-id]
 ```
 
 Shared flags:
@@ -88,11 +92,12 @@ codexs status --json
 Current package version in this repository:
 
 ```text
-0.0.3
+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

package/README.md

@@ -1,113 +1,173 @@
 # @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.
 
-It is built for people who use multiple Codex providers, API keys, or profiles and want a repeatable way to switch between them without manually editing files under `~/.codex/`.
+`codex-switch` 是一个本地优先的 CLI，用来安全地管理和切换 Codex 的 provider/profile 配置。
 
-## What This Repository Is For
+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/`.
 
-This repository contains the CLI implementation, package metadata, and product documents for `codex-switch`.
+它面向同时维护多个 Codex provider、API key 或 profile 的用户，目标是用可重复、先备份再写入的方式替代手动修改 `~/.codex/` 下的文件。
 
-The project focuses on a simple idea:
+## Overview | 简介
 
-- keep Codex profile switching local
-- back up config before writes
-- roll back on failure
-- support both humans in a terminal and AI/automation workflows
+What it does:
 
-## What It Can Do
+- 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
 
-Current MVP command set:
+它可以完成的事情：
 
-```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
-```
+- 从现有 Codex 目录初始化 `providers.json`
+- 查看、新增、编辑、删除 provider 记录
+- 安全切换当前激活的 provider/profile
+- 导入和导出 provider 配置
+- 运行诊断并识别本地配置漂移
+- 查看备份并回滚到之前的受管状态
 
-What that means in practice:
+Current version: `0.0.4`
 
-- list locally managed providers
-- show the current active profile
-- switch to another provider safely
-- import and export provider mappings
-- add or remove provider records
-- detect config drift and common local issues
-- back up managed files before mutation and roll back when needed
+当前版本：`0.0.4`
 
-## Quick Start
-
-### For Humans
+## Install | 安装
 
 Install globally:
 
-```text
+```bash
 npm install -g @minniexcode/codex-switch
 ```
 
-Or run without installing globally:
+Or run directly:
 
-```text
+```bash
 npx @minniexcode/codex-switch --help
 ```
 
-Check the CLI:
+全局安装：
 
-```text
+```bash
+npm install -g @minniexcode/codex-switch
+```
+
+或者直接运行：
+
+```bash
+npx @minniexcode/codex-switch --help
+```
+
+CLI entry:
+
+```bash
 codexs --help
 ```
 
-Typical usage:
+命令入口：
 
-```text
+```bash
+codexs --help
+```
+
+## Quick Start | 快速开始
+
+Take over an existing Codex directory:
+
+```bash
+codexs setup
+```
+
+接管当前已有的 Codex 目录：
+
+```bash
+codexs setup
+```
+
+Inspect managed providers:
+
+```bash
 codexs list
-codexs current
+codexs show my-provider
+```
+
+查看已管理的 provider：
+
+```bash
+codexs list
+codexs show my-provider
+```
+
+Add and switch:
+
+```bash
 codexs add my-provider --profile my-provider --api-key sk-xxx
 codexs switch my-provider
-codexs status
 ```
 
-### For LLM Agents
+新增并切换：
+
+```bash
+codexs add my-provider --profile my-provider --api-key sk-xxx
+codexs switch my-provider
+```
 
-Read this first:
+Check runtime state:
 
-```text
-./README.AI.md
+```bash
+codexs current
+codexs status
+codexs doctor
 ```
 
-Then install and use the project by following the agent-specific instructions in that file.
+检查当前运行状态：
+
+```bash
+codexs current
+codexs status
+codexs doctor
+```
 
-Reference:
+## Common Commands | 常用命令
 
-- [AI README](./README.AI.md)
+```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
+```
 
-Shared flags:
+Command help:
 
-```text
---json
---codex-dir <path>
+```bash
+codexs help switch
+codexs help setup
 ```
 
-## Interactive Use
+命令帮助：
+
+```bash
+codexs help switch
+codexs help setup
+```
 
-The CLI supports both explicit commands and guided terminal flows.
+## How It Works | 工作方式
 
-- `codexs add` prompts for missing required values in a real TTY
-- `codexs switch` can show a provider selector when no provider is passed
-- `codexs remove` supports interactive selection and confirmation
-- `import`, `export`, and `rollback` ask for confirmation in interactive mode
-- `--json` remains non-interactive for scripts and agents
+By default, `codex-switch` operates on `~/.codex/`, and you can override the target with `--codex-dir`.
 
-## Files It Manages
+`codex-switch` 默认围绕 `~/.codex/` 工作，也可以通过 `--codex-dir` 指向其他目录。
 
-`codex-switch` is designed around files under `~/.codex/`:
+Managed files:
 
 ```text
 ~/.codex/
@@ -117,46 +177,55 @@ The CLI supports both explicit commands and guided terminal flows.
   backups/
 ```
 
-Storage model:
+说明：
 
-- `providers.json` is the management source of truth
-- `config.toml` and `auth.json` are runtime state
-- `backups/latest.json` tracks the latest rollback window
+- `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` may contain API keys, so it should be treated as a local secret.
+- `providers.json` 是受管理的 provider 注册表
+- `config.toml` 和 `auth.json` 代表当前运行态
+- 所有写操作都会先备份再写入
+- 变更失败或结果不符合预期时可以回滚
 
-## Documentation
+## Automation | 自动化
 
-User-oriented project docs:
+This CLI supports both human TTY use and non-interactive automation.
 
-- [Chinese README](./README.CN.md)
-- [AI README](./README.AI.md)
-- [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)
+这个 CLI 同时支持人工交互和非交互自动化。
 
-## Latest 3 Versions
+Recommended global flags:
 
-### 0.0.3
+```bash
+--json
+--codex-dir <path>
+--help
+--version
+```
 
-- Added interactive TTY flows for high-frequency commands such as `add`, `switch`, `remove`, `import`, `export`, and `rollback`
-- Improved help output and command-specific guidance
-- Expanded CLI test coverage for interactive and argument handling behavior
+建议：
 
-### 0.0.2
+- 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
 
-- Added mutation orchestration with backup-first writes, rollback handling, and single-process locking
-- Improved `status` and `doctor` so they can detect runtime drift more clearly
-- Strengthened repository and domain layers for safer config operations
+- 在脚本或 CI 中使用 `--json` 获取稳定输出
+- 在非交互环境中显式传入所有必需参数
+- 在测试环境中优先配合 `--codex-dir <path>` 使用
 
-### 0.0.1
+## Documentation | 文档
 
-- Shipped the initial TypeScript CLI implementation
-- Added the core MVP commands and file-based provider management model
-- Added the first full set of product, architecture, and command design docs
+- [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
+## License | 许可证
 
 MIT

package/dist/app/add-provider.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.addProvider = addProvider;
+const config_1 = require("../domain/config");
 const providers_1 = require("../domain/providers");
 const errors_1 = require("../domain/errors");
+const config_repo_1 = require("../infra/config-repo");
 const fs_utils_1 = require("../infra/fs-utils");
 const providers_repo_1 = require("../infra/providers-repo");
 const run_mutation_1 = require("./run-mutation");
@@ -15,6 +17,22 @@ function addProvider(args) {
     if (providers.providers[args.providerName]) {
         throw (0, errors_1.cliError)("INVALID_IMPORT_FILE", `Provider "${args.providerName}" already exists.`);
     }
+    const document = (0, config_repo_1.readStructuredConfig)(args.configPath);
+    const existingProfile = document.profiles.find((profile) => profile.name === args.profile);
+    if (!existingProfile && !args.createProfile) {
+        throw (0, errors_1.cliError)("PROFILE_NOT_FOUND", `Profile "${args.profile}" does not exist in config.toml.`, {
+            profile: args.profile,
+            provider: args.providerName,
+        });
+    }
+    const upsertProfiles = !existingProfile && args.createProfile
+        ? {
+            [args.profile]: (0, config_1.validateManagedProfileCreation)(args.profile, {
+                model: args.model ?? undefined,
+                baseUrl: args.baseUrl ?? undefined,
+            }),
+        }
+        : undefined;
     const next = {
         providers: {
             ...providers.providers,
@@ -32,13 +50,26 @@ function addProvider(args) {
         backupsDir: args.backupsDir,
         latestBackupPath: args.latestBackupPath,
         operation: "add",
-        files: [{ absolutePath: args.providersPath, relativePath: "providers.json" }],
+        files: [
+            { absolutePath: args.providersPath, relativePath: "providers.json" },
+            { absolutePath: args.configPath, relativePath: "config.toml" },
+        ],
         mutate: () => {
+            const configPlan = (0, config_repo_1.createConfigMutationPlan)(document, {
+                upsertProfiles,
+            });
             // Persist only the normalized provider payload so later reads are deterministic.
             (0, providers_repo_1.writeProvidersFile)(args.providersPath, next);
+            (0, config_repo_1.applyConfigMutation)(args.configPath, document, configPlan);
             return {
                 provider: args.providerName,
                 profile: args.profile,
+                createdProfileSections: configPlan.createdProfileSections,
+                deletedProfileSections: configPlan.deletedProfileSections,
+                keptSharedProfiles: [],
+                switchedActiveProfile: configPlan.switchedActiveProfile,
+                adoptedProfiles: [],
+                repairedProfiles: [],
             };
         },
     });

package/dist/app/edit-provider.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.editProvider = editProvider;
+const errors_1 = require("../domain/errors");
+const config_1 = require("../domain/config");
+const providers_1 = require("../domain/providers");
+const config_repo_1 = require("../infra/config-repo");
+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 document = (0, config_repo_1.readStructuredConfig)(args.configPath);
+    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");
+    }
+    const oldProfile = current.profile;
+    const newProfile = nextRecord.profile;
+    const targetSection = document.profiles.find((profile) => profile.name === newProfile) ?? null;
+    const targetProfileExists = Boolean(targetSection);
+    let upsertProfiles;
+    if (!targetProfileExists) {
+        if (!args.createProfile) {
+            throw (0, errors_1.cliError)("PROFILE_NOT_FOUND", `Profile "${newProfile}" does not exist in config.toml.`, {
+                profile: newProfile,
+                provider: args.providerName,
+            });
+        }
+        upsertProfiles = {
+            [newProfile]: (0, config_1.validateManagedProfileCreation)(newProfile, {
+                model: args.model ?? undefined,
+                baseUrl: args.baseUrl ?? undefined,
+            }),
+        };
+    }
+    else if (args.model !== undefined || args.baseUrl !== undefined) {
+        upsertProfiles = {
+            [newProfile]: {
+                ...(args.model !== undefined && args.model !== null ? { model: args.model } : {}),
+                ...(args.baseUrl !== undefined && args.baseUrl !== null ? { baseUrl: args.baseUrl } : {}),
+            },
+        };
+        if (args.model !== undefined && (targetSection?.model !== args.model) && !updatedFields.includes("model")) {
+            updatedFields.push("model");
+        }
+        if (args.baseUrl !== undefined && targetSection?.baseUrl !== args.baseUrl && !updatedFields.includes("baseUrl")) {
+            updatedFields.push("baseUrl");
+        }
+    }
+    const remainingLinksByProfile = new Map();
+    for (const [name, provider] of Object.entries(providers.providers)) {
+        if (name === args.providerName) {
+            continue;
+        }
+        const list = remainingLinksByProfile.get(provider.profile) ?? [];
+        list.push(name);
+        remainingLinksByProfile.set(provider.profile, list);
+    }
+    if (newProfile !== oldProfile) {
+        const list = remainingLinksByProfile.get(newProfile) ?? [];
+        list.push(args.providerName);
+        remainingLinksByProfile.set(newProfile, list);
+    }
+    const lifecycle = (0, config_1.planProfileLifecycleOutcome)({
+        providerName: args.providerName,
+        oldProfile,
+        newProfile,
+        activeProfile: document.activeProfile,
+        remainingLinksByProfile,
+        switchToProfile: args.switchToProfile ?? null,
+    });
+    return (0, run_mutation_1.runMutation)({
+        codexDir: args.codexDir,
+        backupsDir: args.backupsDir,
+        latestBackupPath: args.latestBackupPath,
+        operation: "edit",
+        files: [
+            { absolutePath: args.providersPath, relativePath: "providers.json" },
+            { absolutePath: args.configPath, relativePath: "config.toml" },
+        ],
+        mutate: () => {
+            const configPlan = (0, config_repo_1.createConfigMutationPlan)(document, {
+                upsertProfiles,
+                deleteProfiles: lifecycle.deletedProfileSections,
+                setActiveProfile: lifecycle.nextActiveProfile,
+            });
+            (0, providers_repo_1.writeProvidersFile)(args.providersPath, {
+                providers: {
+                    ...providers.providers,
+                    [args.providerName]: nextRecord,
+                },
+            });
+            (0, config_repo_1.applyConfigMutation)(args.configPath, document, configPlan);
+            return {
+                provider: args.providerName,
+                updatedFields,
+                createdProfileSections: configPlan.createdProfileSections,
+                deletedProfileSections: configPlan.deletedProfileSections,
+                keptSharedProfiles: lifecycle.keptSharedProfiles,
+                switchedActiveProfile: lifecycle.switchedActiveProfile,
+                adoptedProfiles: [],
+                repairedProfiles: [],
+            };
+        },
+    });
+}

package/dist/app/get-status.js

@@ -37,6 +37,7 @@ exports.getStatus = getStatus;
 const fs = __importStar(require("node:fs"));
 const config_1 = require("../domain/config");
 const runtime_state_1 = require("../domain/runtime-state");
+const config_repo_1 = require("../infra/config-repo");
 const providers_repo_1 = require("../infra/providers-repo");
 /**
  * Reports the current on-disk runtime state and how it maps back to managed providers.
@@ -47,9 +48,13 @@ function getStatus(codexDir, configPath, providersPath) {
     let currentProfile = null;
     const warnings = [];
     const providers = providersExists ? (0, providers_repo_1.readProvidersFile)(providersPath) : null;
+    let configViews = [];
+    let consistencyIssues = [];
     if (configExists) {
-        const configContent = fs.readFileSync(configPath, "utf8");
-        currentProfile = (0, config_1.parseTopLevelProfile)(configContent);
+        const document = (0, config_repo_1.readStructuredConfig)(configPath);
+        currentProfile = document.activeProfile;
+        configViews = (0, config_1.buildManagedProfileViews)(document, providers);
+        consistencyIssues = (0, config_1.collectConfigConsistencyIssues)(document, providers);
         if (!currentProfile) {
             warnings.push("config.toml exists but has no top-level profile.");
         }
@@ -70,6 +75,8 @@ function getStatus(codexDir, configPath, providersPath) {
             currentProfileMapped: liveState.profileMapped,
             provider: liveState.mappedProvider,
             liveState,
+            configProfiles: configViews,
+            issues: consistencyIssues,
         },
     };
 }

package/dist/app/import-providers.js

@@ -36,8 +36,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.importProviders = importProviders;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const config_1 = require("../domain/config");
 const providers_1 = require("../domain/providers");
 const errors_1 = require("../domain/errors");
+const config_repo_1 = require("../infra/config-repo");
 const fs_utils_1 = require("../infra/fs-utils");
 const providers_repo_1 = require("../infra/providers-repo");
 const run_mutation_1 = require("./run-mutation");
@@ -58,16 +60,59 @@ function importProviders(args) {
         });
     }
     (0, fs_utils_1.ensureDir)(args.codexDir);
+    const document = (0, config_repo_1.readStructuredConfig)(args.configPath);
     return (0, run_mutation_1.runMutation)({
         codexDir: args.codexDir,
         backupsDir: args.backupsDir,
         latestBackupPath: args.latestBackupPath,
         operation: "import",
-        files: [{ absolutePath: args.providersPath, relativePath: "providers.json" }],
+        files: [
+            { absolutePath: args.providersPath, relativePath: "providers.json" },
+            { absolutePath: args.configPath, relativePath: "config.toml" },
+        ],
         mutate: () => {
-            (0, providers_repo_1.writeProvidersFile)(args.providersPath, imported);
+            const current = (0, providers_repo_1.readProvidersFileIfExists)(args.providersPath);
+            const next = args.merge ? (0, providers_repo_1.mergeProviders)(current, imported) : imported;
+            const currentViews = (0, config_1.buildManagedProfileViews)(document, current);
+            const nextViews = (0, config_1.buildManagedProfileViews)(document, next);
+            const adoptedProfiles = currentViews
+                .filter((view) => view.source === "unmanaged" && view.linkedProviders.length === 0)
+                .filter((view) => nextViews.some((nextView) => nextView.name === view.name && nextView.managed))
+                .map((view) => view.name)
+                .sort();
+            const missingViews = nextViews.filter((view) => view.source === "orphaned-reference");
+            const repairedProfiles = [];
+            const upsertProfiles = missingViews.reduce((accumulator, view) => {
+                const repair = args.repairProfiles?.[view.name];
+                if (!repair) {
+                    throw (0, errors_1.cliError)("MANAGED_PROFILE_FIELDS_MISSING", "Import would create provider references to missing config profiles that need model and base_url.", {
+                        profilesNeedingRepair: missingViews.map((entry) => entry.name).sort(),
+                    });
+                }
+                accumulator[view.name] = (0, config_1.validateManagedProfileCreation)(view.name, repair);
+                repairedProfiles.push(view.name);
+                return accumulator;
+            }, {});
+            const configPlan = (0, config_repo_1.createConfigMutationPlan)(document, {
+                upsertProfiles,
+            });
+            (0, providers_repo_1.writeProvidersFile)(args.providersPath, next);
+            (0, config_repo_1.applyConfigMutation)(args.configPath, document, configPlan);
+            const replacedProviders = args.merge
+                ? Object.keys(imported.providers).filter((name) => current.providers[name]).sort()
+                : [];
             return {
+                mode: args.merge ? "merge" : "replace",
                 importedProviders: Object.keys(imported.providers).sort(),
+                importedCount: Object.keys(imported.providers).length,
+                mergedCount: Object.keys(next.providers).length,
+                replacedProviders,
+                createdProfileSections: configPlan.createdProfileSections,
+                deletedProfileSections: [],
+                keptSharedProfiles: nextViews.filter((view) => view.linkedProviders.length > 1).map((view) => view.name),
+                switchedActiveProfile: false,
+                adoptedProfiles,
+                repairedProfiles: repairedProfiles.sort(),
             };
         },
     });

package/dist/app/list-backups.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listBackupEntries = listBackupEntries;
+const backup_repo_1 = require("../infra/backup-repo");
+/**
+ * Lists backup manifests available under the managed Codex backups directory.
+ */
+function listBackupEntries(backupsDir) {
+    const result = (0, backup_repo_1.listBackups)(backupsDir);
+    return {
+        data: {
+            backups: result.backups,
+            count: result.backups.length,
+        },
+        warnings: result.warnings,
+    };
+}