@minniexcode/codex-switch 0.0.2 → 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,67 +2,22 @@
 
 `@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
-```
-
-## Status
-
-The repository now contains the first end-to-end modular CLI implementation for the MVP command set defined in `docs/`.
-
-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
-
-Managing multiple Codex providers or profiles locally usually falls into two bad options:
-
-- ad hoc scripts that work once but are hard to maintain
-- heavier account or desktop tools that solve a broader problem than local switching
-
-`@minniexcode/codex-switch` sits between those extremes. It aims to provide a stable CLI interface for:
-
-- 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
+The project focuses on a simple idea:
 
-## Product Definition
-
-`@minniexcode/codex-switch` is intended to manage files under `~/.codex/`:
-
-```text
-~/.codex/
-  config.toml
-  auth.json
-  providers.json
-  backups/
-```
+- keep Codex profile switching local
+- back up config before writes
+- roll back on failure
+- support both humans in a terminal and AI/automation workflows
 
-Core design principles:
+## What It Can Do
 
-- `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
-
-The current MVP command surface is:
+Current MVP command set:
 
 ```bash
 codexs list
@@ -77,116 +32,130 @@ codexs doctor
 codexs rollback
 ```
 
-Shared flags:
+What that means in practice:
 
-```bash
---json
---codex-dir <path>
-```
-
-## 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"]
-    }
-  }
-}
-```
+- 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
 
-`providers.json` should be treated as a local secret because it may contain API keys.
+## Quick Start
 
-## Install
+### For Humans
 
-Global install:
+Install globally:
 
-```bash
+```text
 npm install -g @minniexcode/codex-switch
 ```
 
-One-off execution:
+Or run without installing globally:
 
-```bash
-npx @minniexcode/codex-switch
+```text
+npx @minniexcode/codex-switch --help
 ```
 
-Current CLI entry check:
+Check the CLI:
 
-```bash
+```text
 codexs --help
 ```
 
-## Current Repository Contents
+Typical usage:
+
+```text
+codexs list
+codexs current
+codexs add my-provider --profile my-provider --api-key sk-xxx
+codexs switch my-provider
+codexs status
+```
+
+### For LLM Agents
 
-This repository contains both the product documents and the CLI implementation:
+Read this first:
 
-- [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)
+```text
+./README.AI.md
+```
 
-## Implementation Notes
+Then install and use the project by following the agent-specific instructions in that file.
 
-Current implementation characteristics:
+Reference:
 
-- 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
+- [AI README](./README.AI.md)
 
-## Storage Model
+Shared flags:
 
-The current storage model is intentionally split:
+```text
+--json
+--codex-dir <path>
+```
 
-- management state: `providers.json`
-- runtime state: `config.toml` and `auth.json`
-- rollback state: `backups/latest.json` and timestamped backup manifests
+## Interactive Use
 
-That keeps the MVP file-based while preserving the same boundary a future database-backed registry would use.
+The CLI supports both explicit commands and guided terminal flows.
 
-## Concurrency And Drift
+- `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
 
-Current write semantics are intentionally lightweight:
+## Files It Manages
 
-- 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`
+`codex-switch` is designed around files under `~/.codex/`:
 
-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.
+```text
+~/.codex/
+  config.toml
+  auth.json
+  providers.json
+  backups/
+```
 
-## Non-Goals for MVP
+Storage model:
 
-The first version is not trying to be:
+- `providers.json` is the management source of truth
+- `config.toml` and `auth.json` are runtime state
+- `backups/latest.json` tracks the latest rollback window
 
-- a GUI or desktop app
-- a background daemon
-- a full account management platform
-- a proxy/router layer
-- a remote sync service
+`providers.json` may contain API keys, so it should be treated as a local secret.
 
-## Development
+## Documentation
 
-Local development:
+User-oriented project docs:
 
-```bash
-npm install
-npm run build
-npm test
-node dist/cli.js --help
-```
+- [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)
+
+## Latest 3 Versions
+
+### 0.0.3
+
+- 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
+
+- 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
+
+### 0.0.1
+
+- 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/cli/add-interactive.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectAddInput = collectAddInput;
+exports.createNonInteractiveAddError = createNonInteractiveAddError;
+const config_repo_1 = require("../infra/config-repo");
+const errors_1 = require("../domain/errors");
+/**
+ * Collects add command inputs interactively when required values are missing.
+ */
+async function collectAddInput(runtime, defaults, providerExists, configPath) {
+    runtime.writeLine("Interactive add mode");
+    runtime.writeLine("Provide the missing required fields. Press Enter to skip optional fields.");
+    const providerName = defaults.providerName
+        ? normalizeRequiredValue(defaults.providerName)
+        : await promptProviderName(runtime, providerExists);
+    const profile = defaults.profile
+        ? normalizeRequiredValue(defaults.profile)
+        : await promptProfile(runtime, configPath);
+    const apiKey = defaults.apiKey
+        ? normalizeRequiredValue(defaults.apiKey)
+        : await promptConfirmedSecret(runtime, "API key", "Confirm API key");
+    const baseUrl = defaults.baseUrl ?? normalizeOptionalValue(await runtime.inputText("Base URL (optional)"));
+    const note = defaults.note ?? normalizeOptionalValue(await runtime.inputText("Note (optional)"));
+    const tags = defaults.tags.length > 0
+        ? defaults.tags
+        : parseTags(await runtime.inputText("Tags (optional, comma-separated)"));
+    return {
+        providerName,
+        profile,
+        apiKey,
+        baseUrl,
+        note,
+        tags,
+    };
+}
+/**
+ * Throws a consistent error when interactive add is unavailable.
+ */
+function createNonInteractiveAddError() {
+    return (0, errors_1.cliError)("INVALID_IMPORT_FILE", "add requires <provider>, --profile, and --api-key when running without an interactive TTY.", {
+        suggestion: "Run in a terminal TTY or pass all required values explicitly.",
+    });
+}
+async function promptProviderName(runtime, providerExists) {
+    while (true) {
+        const providerName = await promptRequiredValue(runtime, "Provider name");
+        if (providerExists(providerName)) {
+            runtime.writeLine(`Provider "${providerName}" already exists. Choose a different name.`);
+            continue;
+        }
+        return providerName;
+    }
+}
+async function promptProfile(runtime, configPath) {
+    const profileChoices = loadProfileChoices(configPath);
+    if (profileChoices.length > 0) {
+        return runtime.selectOne("Profile", profileChoices);
+    }
+    return promptRequiredValue(runtime, "Profile");
+}
+function loadProfileChoices(configPath) {
+    try {
+        return Array.from((0, config_repo_1.listConfigProfiles)(configPath))
+            .sort()
+            .map((profileName) => ({
+            value: profileName,
+            label: profileName,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+async function promptRequiredValue(runtime, label) {
+    while (true) {
+        const value = normalizeRequiredValue(await runtime.inputText(label));
+        if (value.length > 0) {
+            return value;
+        }
+        runtime.writeLine(`${label} is required.`);
+    }
+}
+async function promptConfirmedSecret(runtime, label, confirmationLabel) {
+    while (true) {
+        const first = normalizeRequiredValue(await runtime.inputSecret(label));
+        if (first.length === 0) {
+            runtime.writeLine(`${label} is required.`);
+            continue;
+        }
+        const second = normalizeRequiredValue(await runtime.inputSecret(confirmationLabel));
+        if (second.length === 0) {
+            runtime.writeLine(`${confirmationLabel} is required.`);
+            continue;
+        }
+        if (first !== second) {
+            runtime.writeLine("API key entries did not match. Try again.");
+            continue;
+        }
+        return first;
+    }
+}
+function normalizeRequiredValue(value) {
+    return value.trim();
+}
+function normalizeOptionalValue(value) {
+    const normalized = value.trim();
+    return normalized === "" ? null : normalized;
+}
+function parseTags(value) {
+    return value
+        .split(",")
+        .map((tag) => tag.trim())
+        .filter((tag) => tag.length > 0);
+}