@minniexcode/codex-switch 0.0.1 → 0.0.3

package/README.AI.md

@@ -0,0 +1,105 @@
+# 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 list
+codexs current
+codexs switch <provider>
+codexs status
+codexs import <file>
+codexs export <file>
+codexs add <provider>
+codexs remove <provider>
+codexs doctor
+codexs rollback
+```
+
+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.3
+```
+
+Recent version summary:
+
+- `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

@@ -2,169 +2,160 @@
 
 `@minniexcode/codex-switch` is a local-first CLI for managing and switching Codex provider/profile configuration safely.
 
-Current product direction:
+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/`.
 
-- CLI-first
-- local-first
-- safe by default
-- AI-friendly
+## What This Repository Is For
 
-The intended command name is:
+This repository contains the CLI implementation, package metadata, and product documents for `codex-switch`.
 
-```bash
-codexs
-```
+The project focuses on a simple idea:
 
-## Status
+- keep Codex profile switching local
+- back up config before writes
+- roll back on failure
+- support both humans in a terminal and AI/automation workflows
 
-This scoped package is currently being reserved and scaffolded for the first public release.
+## What It Can Do
 
-The product scope is already defined, but the full CLI feature set is not implemented yet. The first published versions may be bootstrap releases used to reserve the npm package name and establish the command entrypoint.
+Current MVP command set:
 
-If you install the package now, expect a minimal CLI shell rather than the complete switching workflow.
-The project is scaffolded as a TypeScript CLI and publishes compiled output from `dist/`.
+```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
+```
 
-## Why This Exists
+What that means in practice:
 
-Managing multiple Codex providers or profiles locally usually falls into two bad options:
+- 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
 
-- ad hoc scripts that work once but are hard to maintain
-- heavier account or desktop tools that solve a broader problem than local switching
+## Quick Start
 
-`@minniexcode/codex-switch` sits between those extremes. It aims to provide a stable CLI interface for:
+### For Humans
 
-- 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
+```text
+npm install -g @minniexcode/codex-switch
+```
 
-`@minniexcode/codex-switch` is intended to manage files under `~/.codex/`:
+Or run without installing globally:
 
 ```text
-~/.codex/
-  config.toml
-  auth.json
-  providers.json
-  backups/
+npx @minniexcode/codex-switch --help
 ```
 
-Core design principles:
-
-- `config.toml` remains the source of the active top-level `profile`
-- `providers.json` stores provider-to-profile and provider-to-key mappings
-- all writes should be backed up first
-- failures should trigger rollback
-- CLI output should stay stable and machine-readable
+Check the CLI:
 
-## Planned MVP
+```text
+codexs --help
+```
 
-The planned MVP command surface is:
+Typical usage:
 
-```bash
+```text
 codexs list
 codexs current
-codexs switch <provider>
+codexs add my-provider --profile my-provider --api-key sk-xxx
+codexs switch my-provider
 codexs status
-codexs import <file>
-codexs export <file>
-codexs add <provider>
-codexs remove <provider>
-codexs doctor
-codexs rollback
 ```
 
-Planned shared flags:
+### For LLM Agents
 
-```bash
---json
---codex-dir <path>
-```
+Read this first:
 
-## Example Provider Model
-
-Planned `providers.json` shape:
-
-```json
-{
-  "providers": {
-    "packycode": {
-      "profile": "packycode",
-      "apiKey": "sk-xxx",
-      "baseUrl": "https://example.com/v1",
-      "note": "primary free model route",
-      "tags": ["free", "daily"]
-    }
-  }
-}
+```text
+./README.AI.md
 ```
 
-`providers.json` should be treated as a local secret because it may contain API keys.
+Then install and use the project by following the agent-specific instructions in that file.
 
-## Install
+Reference:
 
-Global install:
+- [AI README](./README.AI.md)
 
-```bash
-npm install -g @minniexcode/codex-switch
+Shared flags:
+
+```text
+--json
+--codex-dir <path>
 ```
 
-One-off execution:
+## Interactive Use
 
-```bash
-npx @minniexcode/codex-switch
-```
+The CLI supports both explicit commands and guided terminal flows.
 
-Current bootstrap behavior:
+- `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
 
-```bash
-codexs --help
+## Files It Manages
+
+`codex-switch` is designed around files under `~/.codex/`:
+
+```text
+~/.codex/
+  config.toml
+  auth.json
+  providers.json
+  backups/
 ```
 
-## Current Repository Contents
+Storage model:
 
-This repository currently contains the product definition and PRD used to shape the first implementation:
+- `providers.json` is the management source of truth
+- `config.toml` and `auth.json` are runtime state
+- `backups/latest.json` tracks the latest rollback window
 
-- [Product Overview](./docs/codex-switch-product-overview.md)
-- [Product Research](./docs/codex-switch-product-research.md)
-- [PRD](./docs/codex-switch-prd.md)
+`providers.json` may contain API keys, so it should be treated as a local secret.
 
-## Roadmap
+## Documentation
 
-Near-term priorities:
+User-oriented project docs:
 
-- publish the package name and CLI entrypoint
-- implement provider storage and validation
-- implement config backup and rollback
-- implement safe switching flow around `config.toml`
-- support structured `--json` output for automation
-- add cross-platform tests for Windows, macOS, and Linux paths
+- [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)
 
-## Non-Goals for MVP
+## Latest 3 Versions
 
-The first version is not trying to be:
+### 0.0.3
 
-- a GUI or desktop app
-- a background daemon
-- a full account management platform
-- a proxy/router layer
-- a remote sync service
+- 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
 
-## Development
+### 0.0.2
 
-At this stage the package is a bootstrap CLI shell. The implementation will follow the product documents in `docs/`.
+- 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
 
-Local development:
+### 0.0.1
 
-```bash
-npm install
-npm run build
-node dist/cli.js --help
-```
+- 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
 
 ## License
 

package/dist/app/add-provider.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addProvider = addProvider;
+const providers_1 = require("../domain/providers");
+const errors_1 = require("../domain/errors");
+const fs_utils_1 = require("../infra/fs-utils");
+const providers_repo_1 = require("../infra/providers-repo");
+const run_mutation_1 = require("./run-mutation");
+/**
+ * Adds a new provider record to the managed providers registry.
+ */
+function addProvider(args) {
+    (0, fs_utils_1.ensureDir)(args.codexDir);
+    const providers = (0, providers_repo_1.readProvidersFileIfExists)(args.providersPath);
+    if (providers.providers[args.providerName]) {
+        throw (0, errors_1.cliError)("INVALID_IMPORT_FILE", `Provider "${args.providerName}" already exists.`);
+    }
+    const next = {
+        providers: {
+            ...providers.providers,
+            [args.providerName]: (0, providers_1.cleanProviderRecord)({
+                profile: args.profile,
+                apiKey: args.apiKey,
+                baseUrl: args.baseUrl ?? undefined,
+                note: args.note ?? undefined,
+                tags: args.tags,
+            }),
+        },
+    };
+    return (0, run_mutation_1.runMutation)({
+        codexDir: args.codexDir,
+        backupsDir: args.backupsDir,
+        latestBackupPath: args.latestBackupPath,
+        operation: "add",
+        files: [{ absolutePath: args.providersPath, relativePath: "providers.json" }],
+        mutate: () => {
+            // Persist only the normalized provider payload so later reads are deterministic.
+            (0, providers_repo_1.writeProvidersFile)(args.providersPath, next);
+            return {
+                provider: args.providerName,
+                profile: args.profile,
+            };
+        },
+    });
+}

package/dist/app/export-providers.js

@@ -0,0 +1,62 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exportProviders = exportProviders;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const errors_1 = require("../domain/errors");
+const fs_utils_1 = require("../infra/fs-utils");
+const providers_repo_1 = require("../infra/providers-repo");
+/**
+ * Exports the current providers registry to a user-specified file.
+ */
+function exportProviders(args) {
+    const absoluteTarget = path.resolve(args.targetFile);
+    if (fs.existsSync(absoluteTarget) && !args.force) {
+        throw (0, errors_1.cliError)("INVALID_IMPORT_FILE", "Export target already exists. Re-run with --force to overwrite.", {
+            file: absoluteTarget,
+        });
+    }
+    const providers = (0, providers_repo_1.readProvidersFile)(args.providersPath);
+    // Create the target directory first so exports work for nested paths.
+    (0, fs_utils_1.ensureDir)(path.dirname(absoluteTarget));
+    (0, providers_repo_1.writeProvidersFile)(absoluteTarget, providers);
+    return {
+        data: {
+            exportedTo: absoluteTarget,
+            count: Object.keys(providers.providers).length,
+        },
+    };
+}

package/dist/app/get-current-profile.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCurrentProfile = getCurrentProfile;
+const config_repo_1 = require("../infra/config-repo");
+/**
+ * Returns the currently active top-level Codex profile.
+ */
+function getCurrentProfile(configPath) {
+    return {
+        data: {
+            profile: (0, config_repo_1.readCurrentProfile)(configPath),
+        },
+    };
+}