@minniexcode/codex-switch 0.0.2 → 0.0.3

package/dist/cli.js

@@ -15,37 +15,20 @@ const rollback_latest_1 = require("./app/rollback-latest");
 const run_doctor_1 = require("./app/run-doctor");
 const switch_provider_1 = require("./app/switch-provider");
 const errors_1 = require("./domain/errors");
+const providers_repo_1 = require("./infra/providers-repo");
 const codex_paths_1 = require("./infra/codex-paths");
 const args_1 = require("./cli/args");
+const add_interactive_1 = require("./cli/add-interactive");
+const help_1 = require("./cli/help");
+const interactive_1 = require("./cli/interactive");
 const output_1 = require("./cli/output");
-const VERSION = "0.0.2";
-const HELP_TEXT = `codex-switch
-
-Usage:
-  codexs <command> [options]
-
-Commands:
-  codexs list
-  codexs current
-  codexs switch <provider> [--no-login]
-  codexs status
-  codexs import <file>
-  codexs export <file> [--force]
-  codexs add <provider> --profile <name> --api-key <key> [--base-url <url>] [--note <text>] [--tag <tag> ...]
-  codexs remove <provider> --force
-  codexs doctor
-  codexs rollback
-
-Global options:
-  --json
-  --codex-dir <path>
-  --help
-  --version`;
+const prompt_1 = require("./cli/prompt");
+const VERSION = "0.0.3";
 /**
  * Prints the command help text to stdout.
  */
-function printHelp() {
-    process.stdout.write(`${HELP_TEXT}\n`);
+function printHelp(commandName) {
+    process.stdout.write(`${(0, help_1.buildHelpText)(commandName)}\n`);
 }
 /**
  * Prints the current CLI version to stdout.
@@ -58,16 +41,22 @@ function printVersion() {
  */
 function main() {
     const parsed = (0, args_1.parseArgs)(process.argv.slice(2));
-    if (!parsed.command) {
-        printHelp();
+    if (parsed.versionRequested) {
+        printVersion();
         process.exit(0);
     }
-    if (parsed.command === "help") {
-        printHelp();
+    if (parsed.helpRequested) {
+        if (parsed.helpTarget && !(0, help_1.isKnownCommandName)(parsed.helpTarget)) {
+            (0, output_1.outputFailure)({ command: "help", options: parsed.globalOptions }, (0, errors_1.cliError)("INVALID_IMPORT_FILE", `Unknown help topic: ${parsed.helpTarget}`, {
+                availableCommands: (0, help_1.buildHelpText)(parsed.helpTarget).split("\n").slice(2),
+            }));
+            return;
+        }
+        printHelp(parsed.helpTarget);
         process.exit(0);
     }
-    if (parsed.command === "version") {
-        printVersion();
+    if (!parsed.command) {
+        printHelp();
         process.exit(0);
     }
     const ctx = {
@@ -85,7 +74,7 @@ function main() {
 /**
  * Dispatches a parsed CLI command into the application layer.
  */
-async function executeCommand(ctx, parsed) {
+async function executeCommand(ctx, parsed, runtime = (0, prompt_1.createPromptRuntime)()) {
     const paths = (0, codex_paths_1.createCodexPaths)(ctx.options.codexDir);
     switch (ctx.command) {
         case "list":
@@ -95,7 +84,10 @@ async function executeCommand(ctx, parsed) {
         case "status":
             return (0, get_status_1.getStatus)(paths.codexDir, paths.configPath, paths.providersPath);
         case "switch": {
-            const providerName = parsed.positionals[0];
+            let providerName = parsed.positionals[0] ?? null;
+            if (!providerName && (0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                providerName = await (0, interactive_1.promptForProviderSelection)(runtime, paths.providersPath, "Choose a provider to switch to");
+            }
             if (!providerName) {
                 throw (0, errors_1.cliError)("PROVIDER_NOT_FOUND", "Missing provider name for switch command.");
             }
@@ -115,6 +107,9 @@ async function executeCommand(ctx, parsed) {
             if (!sourceFile) {
                 throw (0, errors_1.cliError)("INVALID_IMPORT_FILE", "Missing import file path.");
             }
+            if ((0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                await (0, interactive_1.confirmImport)(runtime, sourceFile);
+            }
             return (0, import_providers_1.importProviders)({
                 codexDir: paths.codexDir,
                 backupsDir: paths.backupsDir,
@@ -128,21 +123,45 @@ async function executeCommand(ctx, parsed) {
             if (!targetFile) {
                 throw (0, errors_1.cliError)("INVALID_IMPORT_FILE", "Missing export file path.");
             }
+            let force = (0, args_1.hasFlag)(parsed.commandOptions, "--force");
+            if (!force && (0, interactive_1.canPrompt)(runtime, ctx.options.json) && (0, interactive_1.exportTargetExists)(targetFile)) {
+                const confirmed = await (0, interactive_1.confirmExportOverwrite)(runtime, targetFile);
+                if (!confirmed) {
+                    throw (0, errors_1.cliError)("INVALID_IMPORT_FILE", "Export cancelled.");
+                }
+                force = true;
+            }
             return (0, export_providers_1.exportProviders)({
                 providersPath: paths.providersPath,
                 targetFile,
-                force: (0, args_1.hasFlag)(parsed.commandOptions, "--force"),
+                force,
             });
         }
         case "add": {
-            const providerName = parsed.positionals[0];
-            if (!providerName) {
-                throw (0, errors_1.cliError)("INVALID_IMPORT_FILE", "Missing provider name for add command.");
-            }
-            const profile = (0, args_1.getSingleOption)(parsed.commandOptions, "--profile");
-            const apiKey = (0, args_1.getSingleOption)(parsed.commandOptions, "--api-key");
-            if (!profile || !apiKey) {
-                throw (0, errors_1.cliError)("INVALID_IMPORT_FILE", "add requires --profile and --api-key.");
+            let providerName = parsed.positionals[0] ?? null;
+            let profile = (0, args_1.getSingleOption)(parsed.commandOptions, "--profile");
+            let apiKey = (0, args_1.getSingleOption)(parsed.commandOptions, "--api-key");
+            let baseUrl = (0, args_1.getSingleOption)(parsed.commandOptions, "--base-url", false);
+            let note = (0, args_1.getSingleOption)(parsed.commandOptions, "--note", false);
+            let tags = parsed.commandOptions.get("--tag") ?? [];
+            if (!providerName || !profile || !apiKey) {
+                if (ctx.options.json || !runtime.isInteractive()) {
+                    throw (0, add_interactive_1.createNonInteractiveAddError)();
+                }
+                const prompted = await (0, add_interactive_1.collectAddInput)(runtime, {
+                    providerName,
+                    profile,
+                    apiKey,
+                    baseUrl,
+                    note,
+                    tags,
+                }, (candidate) => Boolean((0, providers_repo_1.readProvidersFileIfExists)(paths.providersPath).providers[candidate]), paths.configPath);
+                providerName = prompted.providerName;
+                profile = prompted.profile;
+                apiKey = prompted.apiKey;
+                baseUrl = prompted.baseUrl ?? null;
+                note = prompted.note ?? null;
+                tags = prompted.tags;
             }
             return (0, add_provider_1.addProvider)({
                 codexDir: paths.codexDir,
@@ -152,19 +171,26 @@ async function executeCommand(ctx, parsed) {
                 providerName,
                 profile,
                 apiKey,
-                baseUrl: (0, args_1.getSingleOption)(parsed.commandOptions, "--base-url", false),
-                note: (0, args_1.getSingleOption)(parsed.commandOptions, "--note", false),
-                tags: parsed.commandOptions.get("--tag") ?? [],
+                baseUrl,
+                note,
+                tags,
             });
         }
         case "remove": {
-            const providerName = parsed.positionals[0];
+            let providerName = parsed.positionals[0] ?? null;
+            const force = (0, args_1.hasFlag)(parsed.commandOptions, "--force");
+            if (!providerName && (0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                providerName = await (0, interactive_1.promptForProviderSelection)(runtime, paths.providersPath, "Choose a provider to remove");
+            }
             if (!providerName) {
                 throw (0, errors_1.cliError)("PROVIDER_NOT_FOUND", "Missing provider name for remove command.");
             }
-            if (!(0, args_1.hasFlag)(parsed.commandOptions, "--force")) {
+            if (!force && !(0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
                 throw (0, errors_1.cliError)("INVALID_IMPORT_FILE", "remove requires --force.");
             }
+            if ((0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                await (0, interactive_1.confirmProviderRemoval)(runtime, providerName);
+            }
             return (0, remove_provider_1.removeProvider)({
                 codexDir: paths.codexDir,
                 backupsDir: paths.backupsDir,
@@ -180,6 +206,9 @@ async function executeCommand(ctx, parsed) {
                 providersPath: paths.providersPath,
             });
         case "rollback":
+            if ((0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                await (0, interactive_1.confirmRollback)(runtime, paths.latestBackupPath);
+            }
             return (0, rollback_latest_1.rollbackLatest)(paths.latestBackupPath);
         default:
             throw (0, errors_1.cliError)("INVALID_IMPORT_FILE", `Unknown command: ${ctx.command}`);

package/docs/codex-switch-command-design.md

@@ -40,7 +40,7 @@
 - 参数显式
 - 输出稳定
 - 能被 AI 和脚本直接消费
-- 不把 GUI 交互假装成 CLI 接口
+- 交互只作为 TTY 中的人类增强层，而不是自动化契约
 
 ## 2. 公共命令约定
 
@@ -107,6 +107,13 @@ codexs
 - `ROLLBACK_FAILED`
 - `INVALID_IMPORT_FILE`
 
+### 2.5 渐进式交互约定
+
+- `--json` 一律禁用交互
+- 非 TTY 一律不进入交互
+- 交互主要服务于人类高频写命令，不改变自动化显式参数契约
+- 用户取消 prompt、`Ctrl+C`、或确认选择否时，不应产生任何文件写入
+
 ## 3. 命令清单概览
 
 ```bash
@@ -275,6 +282,12 @@ JSON 示例：
 codexs switch <provider> [--no-login] [--json] [--codex-dir <path>]
 ```
 
+#### 交互行为
+
+- 当 `<provider>` 缺失且当前是 TTY 时，先从 `providers.json` 读取 provider 列表，再用选择器选择 provider
+- 当 `<provider>` 已显式传入时，不额外确认
+- `--no-login` 仍保持显式 flag，不进入提问
+
 #### 前置校验
 
 - `providers.json` 必须存在
@@ -341,6 +354,8 @@ codexs import <file> [--json] [--codex-dir <path>]
 - 只支持整体替换
 - 不支持 merge
 - 写入前备份当前 `providers.json`
+- 路径参数必须显式传入
+- TTY 中实际替换前增加一次确认
 
 #### 成功输出
 
@@ -379,6 +394,8 @@ codexs export <file> [--force] [--json] [--codex-dir <path>]
 
 - 默认不覆盖已有文件
 - 传 `--force` 后允许覆盖
+- 路径参数必须显式传入
+- 当目标文件已存在、当前是 TTY 且未传 `--force` 时，可通过确认后继续覆盖
 
 #### 成功输出
 
@@ -424,7 +441,11 @@ codexs add <provider> \
 
 - provider 名必须唯一
 - 写入前备份旧 `providers.json`
-- 当前不支持交互式模式
+- 显式参数模式保持可用
+- 当缺少必填字段且 stdin/stdout 都是 TTY 时，允许渐进式提问
+- `--json` 或非 TTY 场景下仍要求显式传入必填参数
+- `profile` 优先从 `config.toml` 已有 profile 列表里选择，获取失败时退回文本输入
+- `apiKey` 使用隐藏输入并要求二次确认
 
 #### 成功输出
 
@@ -457,12 +478,15 @@ codexs add <provider> \
 #### 输入
 
 ```bash
-codexs remove <provider> --force [--json] [--codex-dir <path>]
+codexs remove <provider> [--force] [--json] [--codex-dir <path>]
 ```
 
 #### 行为语义
 
-- 必须显式传入 `--force`
+- TTY 中若缺少 `<provider>`，允许先选择 provider
+- TTY 中始终需要确认，确认文案必须带 provider 名
+- TTY 中即使未传 `--force`，也可通过确认完成删除
+- 非 TTY 或 `--json` 场景下仍要求显式 `<provider> --force`
 - 先备份再删除
 
 #### 失败错误码
@@ -536,6 +560,7 @@ codexs rollback [--json] [--codex-dir <path>]
 - 读取 `backups/latest.json`
 - 恢复 manifest 中记录的文件
 - 如果最近一次备份包含 `auth.json`，一并恢复
+- TTY 中执行前会展示备份目录和受影响文件摘要，并请求确认
 
 #### 成功输出
 

package/docs/codex-switch-prd.md

@@ -99,6 +99,10 @@ AI 需要通过 `status` 或 `doctor --json` 判断本地配置是否完整、
 
 关键命令必须提供稳定、可解析的 `--json` 输出。
 
+### Progressive For Humans
+
+高频人类写命令可以在 TTY 中提供渐进式交互，但这层体验不能改变自动化的显式参数契约。
+
 ### Local First
 
 MVP 的核心对象是本地文件与本机配置，不依赖云端控制面。
@@ -278,6 +282,12 @@ MVP 固定包含以下命令：
 - 位置参数：`<provider>`
 - 可选参数：`--no-login`
 
+交互边界：
+
+- 当 `<provider>` 缺失且运行在 TTY 中时，允许用户从 provider 列表中选择
+- `--json` 或非 TTY 场景下仍要求显式 provider
+- 当 provider 已显式传入时，不做额外确认
+
 前置校验：
 
 - `providers.json` 存在且可解析
@@ -346,6 +356,8 @@ MVP 固定包含以下命令：
 说明：
 
 - MVP 不做 merge 导入，固定为整体替换
+- 路径参数保持显式，不做路径向导
+- TTY 中在真正覆盖前增加确认
 
 ### `codexs export <file>`
 
@@ -361,6 +373,8 @@ MVP 固定包含以下命令：
 
 - 默认不覆盖已有文件
 - 只有传入 `--force` 时才允许覆盖
+- TTY 中若目标已存在且未传 `--force`，允许通过确认覆盖
+- 非 TTY 与 `--json` 保持显式 `--force` 契约
 
 ### `codexs add <provider>`
 
@@ -383,8 +397,11 @@ MVP 固定包含以下命令：
 
 范围限制：
 
-- MVP 只支持显式参数模式
-- 不提供交互式 wizard
+- 显式参数模式仍是自动化主路径
+- 当 `add` 缺少必填参数且运行在 TTY 中时，允许进入渐进式交互录入
+- `--json` 或非 TTY 场景下仍要求显式传参
+- `profile` 优先展示 `config.toml` 中现有 profile 供选择
+- `apiKey` 以隐藏输入采集并要求二次确认
 
 ### `codexs remove <provider>`
 
@@ -406,7 +423,8 @@ MVP 固定包含以下命令：
 
 范围限制：
 
-- 自动化调用场景下，要求显式传 `--force`
+- TTY 中可选择 provider，并通过确认代替 `--force`
+- 自动化调用场景下，仍要求显式传 `--force`
 
 ### `codexs doctor`
 
@@ -442,6 +460,7 @@ MVP 固定包含以下命令：
 说明：
 
 - `rollback` 进入 MVP，因为它直接支撑“默认安全”的产品承诺
+- TTY 中在恢复前展示将被恢复的文件摘要，并请求确认
 
 ## 输出契约
 

package/docs/codex-switch-technical-architecture.md

@@ -236,6 +236,27 @@ scripts/
 - 文件访问
 - 输出格式化
 
+#### `src/cli/prompt.ts`
+
+负责：
+
+- 对 `inquirer` 做轻量封装
+- 提供 `input` / `password` / `select` / `confirm` 四类 typed 交互能力
+- 把 prompt 取消统一转换成稳定 CLI 错误
+
+不负责：
+
+- 业务判断某个命令是否应该进入交互
+- 直接读写 provider/config 文件
+
+#### `src/cli/interactive.ts`
+
+负责：
+
+- 统一判定何时允许交互
+- 组合 provider 选择、危险确认、rollback 摘要展示等 CLI 级辅助逻辑
+- 保持命令分支对交互的接入方式一致
+
 #### `src/cli/output.ts`
 
 负责：
@@ -524,19 +545,20 @@ scripts/
 
 流程如下：
 
-1. 获取单操作写锁
-2. 读取并解析 `providers.json`
-3. 校验目标 provider 是否存在
-4. 读取 `config.toml`
-5. 校验 provider 对应的 `profile` 在配置中存在
-6. 创建备份：
+1. CLI 层在 TTY 且 `<provider>` 缺失时，先用 selector 选 provider
+2. 获取单操作写锁
+3. 读取并解析 `providers.json`
+4. 校验目标 provider 是否存在
+5. 读取 `config.toml`
+6. 校验 provider 对应的 `profile` 在配置中存在
+7. 创建备份：
    - `config.toml`
    - `auth.json`（如果存在）
-7. 更新顶层 `profile`
-8. 如果未传 `--no-login`，执行 `codex login --with-api-key`
-9. 成功后把这次备份记录为 `latest.json`
-10. 若任何步骤失败，按 manifest 回滚
-11. 释放写锁
+8. 更新顶层 `profile`
+9. 如果未传 `--no-login`，执行 `codex login --with-api-key`
+10. 成功后把这次备份记录为 `latest.json`
+11. 若任何步骤失败，按 manifest 回滚
+12. 释放写锁
 
 #### 为什么 `switch` 必须由应用层编排
 
@@ -625,11 +647,13 @@ failure path:
 
 流程：
 
-1. 读取外部文件
-2. 校验 JSON 和 schema
-3. 备份当前 `providers.json`
-4. 整体替换写入
-5. 写失败则恢复旧文件
+1. CLI 层保留显式路径参数
+2. TTY 中写入前先确认
+3. 读取外部文件
+4. 校验 JSON 和 schema
+5. 备份当前 `providers.json`
+6. 整体替换写入
+7. 写失败则恢复旧文件
 
 当前明确不支持 merge import。
 
@@ -639,37 +663,46 @@ failure path:
 
 1. 读取当前 `providers.json`
 2. 检查目标文件是否存在
-3. 默认拒绝覆盖
-4. 传入 `--force` 时允许覆盖
+3. TTY 中若文件已存在且未传 `--force`，先确认是否覆盖
+4. 默认拒绝覆盖
+5. 传入 `--force` 或确认覆盖时允许写入
 
 ### 6.8 `add`
 
 流程：
 
-1. 读取现有 provider 集合
-2. 校验重名
-3. 备份旧文件
-4. 追加一条 provider 记录
-5. 写回 `providers.json`
+1. CLI 层仅在缺失必填字段且当前是 TTY 时进入交互
+2. provider 名在 prompt 阶段尽早做重名检查
+3. profile 优先从 `config.toml` 里解析出的现有 profile 列表选择
+4. apiKey 通过隐藏输入采集并二次确认
+5. 读取现有 provider 集合
+6. 校验重名
+7. 备份旧文件
+8. 追加一条 provider 记录
+9. 写回 `providers.json`
 
 ### 6.9 `remove`
 
 流程：
 
-1. 校验 provider 存在
-2. 要求显式 `--force`
-3. 备份 `providers.json`
-4. 删除目标 provider
-5. 写回
+1. CLI 层在 TTY 且缺少 provider 时可先选择 provider
+2. CLI 层在 TTY 中始终做删除确认
+3. 非 TTY 或 `--json` 场景继续要求显式 `--force`
+4. 校验 provider 存在
+5. 备份 `providers.json`
+6. 删除目标 provider
+7. 写回
 
 ### 6.10 `rollback`
 
 流程：
 
-1. 读取 `backups/latest.json`
-2. 加载最近一次 manifest
-3. 按 manifest 恢复文件
-4. 返回恢复文件列表和备份目录
+1. TTY 中先读取 `backups/latest.json`
+2. 展示备份目录和待恢复文件摘要
+3. 请求确认
+4. 加载最近一次 manifest
+5. 按 manifest 恢复文件
+6. 返回恢复文件列表和备份目录
 
 #### `rollback` 时序图
 
@@ -934,15 +967,23 @@ tests/
 
 从 MVP 可用性上没问题，但长期更推荐拆成专门的 CLI availability 错误。
 
-### 13.3 当前没有真正的交互式命令层
+### 13.3 当前交互式命令层范围仍然受控
+
+当前 CLI 仍以显式参数模式为主，但已经把 `inquirer` 交互扩展到了高频写命令：
+
+- `add` 缺失必填字段时的渐进式提问
+- `switch` 的 provider 选择
+- `remove` 的 provider 选择与确认
+- `import` / `export` 的危险确认
+- `rollback` 的恢复确认
 
-现在所有命令都是显式参数模式，没有：
+当前仍然没有：
 
-- 交互式 provider 选择
-- 向导式 add/import
+- 路径向导式 import/export
 - TUI 状态面板
+- 脱离显式参数契约的自动化交互
 
-这符合 PRD 的 MVP 边界。
+这继续保持了 CLI-first 和自动化优先的主体边界。
 
 ### 13.4 尚未引入持久化审计日志
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minniexcode/codex-switch",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Local-first CLI for managing and switching Codex provider/profile configuration.",
   "license": "MIT",
   "type": "commonjs",
@@ -44,5 +44,8 @@
   "devDependencies": {
     "@types/node": "^24.12.3",
     "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "inquirer": "^13.4.3"
   }
 }