@icode-js/icode 3.0.4 → 3.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -7,6 +7,7 @@
 - 更稳定地处理复杂 Git 场景
 - 更好支持 `husky/git hooks` 校验链路
 - 默认识别“继承父级 Git 仓库”的目录结构
+- 提供面向人类和 AI agent 的安全场景入口，而不是复刻 Git 子命令
 - 采用更现代的 Node 20+ ESM 架构（无运行时第三方依赖）
 
 ## 安装
@@ -20,9 +21,32 @@ npm i -g @icode-js/icode
 ```bash
 icode help # 查看命令总览
 icode info
+icode ready
+icode save -m "feat: add login form"
+icode doctor
 icode config ai list
 ```
 
+## Shell Tab 补全
+
+`icode` 现在支持生成 `bash` / `zsh` 的 tab 补全脚本。
+
+临时启用：
+
+```bash
+source <(icode completion bash)
+source <(icode completion zsh)
+```
+
+持久启用可以把对应命令追加到 `~/.bashrc` 或 `~/.zshrc`。
+
+补全范围包括：
+
+- 顶层命令和嵌套子命令
+- 已知参数开关与枚举值
+- 常见 Git 分支 / ref
+- `icode config ai ...` 下已配置的 profile 名称
+
 ## 全局参数
 
 - `-h, --help`：查看帮助（也可 `icode <command> -h` 查看子命令参数）
@@ -30,7 +54,7 @@ icode config ai list
 
 ## AI 能力配置
 
-先配置一个 AI profile（支持 OpenAI/Anthropic/Ollama 四种接口格式）：
+先配置一个 AI profile（支持 OpenAI/Anthropic/Ollama 三种接口格式）：
 
 ```bash
 icode config ai set openai \
@@ -79,8 +103,75 @@ icode config ai options set explain --json '{"profile":"ollama","base":"origin/m
 icode config ai options set push --json '{"aiProfile":"ollama","aiCommitLang":"zh"}'
 ```
 
+## 健康检查
+
+```bash
+icode doctor
+icode doctor --json
+```
+
+`doctor` 会检查 Git 命令、`origin`、hooks、AI profile 与远程合并配置，并给出修复建议。建议新成员初始化环境后先执行一次。
+
+参数说明：
+
+- `--repo-mode auto|strict`：仓库模式（自动继承父仓库/禁止继承）
+- `--json`：输出机器可读 JSON，适合脚本或 CI 读取
+- `-h, --help`：查看帮助
+
 ## 核心命令
 
+### ready
+
+```bash
+icode ready
+icode ready --json
+```
+
+`ready` 是继续开发、保存或推送前的场景化检查入口，不会修改 Git 状态。它会检查：
+
+- 当前是否在明确分支上
+- 是否存在未完成的 `merge/rebase/cherry-pick/revert`
+- 是否存在未提交改动或冲突文件
+- 当前分支与 upstream 的 ahead/behind 关系
+- AI profile 与远程合并配置是否可用
+
+参数说明：
+
+- `--repo-mode auto|strict`：仓库模式（自动继承父仓库/禁止继承）
+- `--json`：输出机器可读 JSON，适合 AI agent 或脚本判断下一步
+- `-h, --help`：查看帮助
+
+### save
+
+```bash
+icode save -m "feat: add login form"
+icode save --ai-commit -y
+icode save -m "fix: adjust copy" --dry-run
+icode save --ai-commit --dry-run --json
+```
+
+`save` 是安全快速提交场景：检查状态 -> 暂存全部改动 -> 创建本地 commit。它不会 push，也不会隐式生成提交信息。
+
+- 无改动会直接失败
+- 存在冲突会直接失败
+- 存在未完成 Git 操作会直接失败
+- `--message` 和 `--ai-commit` 必须二选一
+- `--dry-run` 只检查并展示计划，不执行 `git add` 或 `git commit`
+- `--ai-commit` 必须使用已配置的 AI profile，不做静默降级
+
+参数说明：
+
+- `-m, --message <msg>`：指定提交信息
+- `--ai-commit`：使用 AI 根据全部未提交改动生成提交信息
+- `--profile <name>`：指定 AI profile（仅 `--ai-commit` 使用）
+- `--lang <zh|en>`：AI 提交信息语言，默认 `zh`
+- `--dry-run`：只检查并展示将提交的信息，不执行 add/commit
+- `--json`：输出机器可读 JSON
+- `--repo-mode auto|strict`：仓库模式（自动继承父仓库/禁止继承）
+- `--no-verify`：commit 时跳过 hook/husky 校验
+- `-y, --yes`：自动确认 AI 提交
+- `-h, --help`：查看帮助
+
 ### checkout
 
 ```bash
@@ -90,6 +181,7 @@ icode checkout <branch> [base] [--push-origin] [--pull-main] [--repo-mode auto|s
 - 本地存在分支: 直接切换
 - 远程存在分支: 本地创建 tracking 分支并切换
 - 都不存在: 从 `base` 或默认主分支创建
+- 执行前要求工作区干净，且不存在未完成的 merge/rebase/cherry-pick/revert
 
 参数说明：
 
@@ -105,7 +197,7 @@ icode checkout <branch> [base] [--push-origin] [--pull-main] [--repo-mode auto|s
 ### push
 
 ```bash
-icode push [targetBranch...] [-m "commit message"] [--ai-commit] [--pull-main] [--not-push-current]
+icode push [targetBranch...] [-m "commit message"] [--ai-commit] [--pull-main] [--not-push-current] [-r|--remote-merge] [--dry-run]
 ```
 
 示例：
@@ -113,13 +205,18 @@ icode push [targetBranch...] [-m "commit message"] [--ai-commit] [--pull-main] [
 ```bash
 icode push -m "feat: release" # 提交并推送当前分支
 icode push release test -m "feat: batch publish" -y # 默认本地 merge 推送到多个分支
+icode push release test --dry-run # 只查看计划，不执行任何 Git/远程合并副作用
+icode push release test -r -y # 使用远程 MR 模式合并到多个目标分支
 ```
 
 - 自动 `add + commit + push`
+- 存在冲突或未完成 Git 操作时会直接停止
+- 本地 merge 冲突会暂停在目标分支现场；解决后执行 `icode undo --recover continue`，或执行 `icode undo --recover abort` 中止
 - 支持 `--ai-commit` 在 push 前自动生成并应用 AI 提交信息
 - 若仓库存在 husky/hooks/commitlint 规则，AI commit 会先扫描本地规范再生成提交信息
 - 支持把当前分支合并到多个目标分支
 - 默认使用本地 merge 模式（会生成 merge commit）
+- 支持远程 PR/MR API 模式（需配置平台密钥）
 - 支持受保护分支策略（通过 `icode config protect ...` 管理）
 
 参数说明：
@@ -128,6 +225,8 @@ icode push release test -m "feat: batch publish" -y # 默认本地 merge 推送
 - `-m, --message <msg>`：提交信息（未填会提示输入）
 - `-y, --yes`：自动确认（跳过确认提示）
 - `--local-merge`：显式声明使用本地 merge 模式（当前为默认行为，会切换分支并生成 merge commit）
+- `-r, --remote-merge`：改为远程 PR/MR 模式；会先推送源分支，再通过 API 创建合并请求；若发生冲突会暂停，并输出明确失败原因
+- `--dry-run`：只展示计划，不执行 commit/fetch/pull/push/merge/MR
 - `--ai-commit`：push 前自动执行 AI commit
 - `--ai-profile <name>`：指定 AI profile（用于 `--ai-commit`）
 - `--pull-main`：提交前同步主分支到当前分支
@@ -138,8 +237,25 @@ icode push release test -m "feat: batch publish" -y # 默认本地 merge 推送
 - `-h, --help`：查看帮助
 
 说明：
+
 - `push` 的布尔开关（如 `--ai-commit`、`--pull-main`、`--no-verify`、`-y`）仅在命令行显式传入时生效。
 
+远程合并配置示例：
+
+```bash
+icode config platform remote-merge set --provider gitlab --api-key rm_xxx
+```
+
+建议：
+
+- 密钥按平台维度管理，例如 GitLab / GitHub / 自建平台。
+- GitLab API 地址固定为仓库 `origin` 对应站点的 `/api/v4`，无需再单独配置服务地址。
+- 项目/仓库默认启用远程合并；如个别仓库不希望启用，可显式设置 `repositories.<repo>.remoteMerge.enabled=false`。
+- 远程合并始终根据 `origin` 自动提取 GitLab 项目地址；若无法识别，会提示你修正仓库 remote 配置。
+- GitLab 审批规则由 merge API 统一判断；若审批不足，会在 merge 阶段输出明确失败原因。
+- GitLab 合并检查会展示等待进度，并在长时间 pending 后超时退出，避免命令无限卡住。
+- 这样更符合密钥复用与安全边界，避免多个仓库重复维护同一平台 API 地址。
+
 ### ai
 
 ```bash
@@ -183,6 +299,7 @@ icode sync [branch...] [--all-local] [--merge-main] [--push]
 ```
 
 - 批量同步多个分支（fetch + pull）
+- 执行前要求当前处于普通分支、工作区干净，且不存在未完成 Git 操作
 - 可选自动同步全部本地分支（`--all-local`）
 - 可选把主分支自动 merge 到目标分支（`--merge-main`）
 - 可选同步后自动推送（`--push`）
@@ -206,6 +323,7 @@ icode clean [--merged-target <branch>] [--remote] [--force]
 ```
 
 - 安全清理“已合并”本地分支
+- 执行前要求当前处于普通分支、工作区干净，且不存在未完成 Git 操作
 - 默认保护当前分支/主分支/配置中的受保护分支
 - 可选同步删除远程分支（`--remote`）
 
@@ -239,19 +357,24 @@ icode tag [--name <tag>] [--message <msg>] [--from <ref>]
 ### undo
 
 ```bash
-icode undo [--mode revert|soft|mixed|hard] [--ref <ref>] [--recover continue|abort|keep]
+icode undo [ref] [--mode revert|soft|mixed|hard] [--ref <ref>] [--hash <hash>] [--recover continue|abort|keep]
+icode undo --mode revert --ref HEAD --json
 ```
 
 - 向导式撤销命令（交互选择回滚策略）
 - 适合新人或低频 Git 操作场景
-- 也支持非交互参数：`--mode` + `--ref`
-- 检测到 revert/cherry-pick 冲突时，会提示继续或中止
+- 也支持非交互参数：`--mode` + `--ref` / `--hash`
+- 支持用位置参数指定 commit hash，例如：`icode undo a1b2c3d --mode revert -y`
+- 检测到 merge/revert/cherry-pick 冲突时，会提示继续或中止
+- 支持 `--json` 输出结构化结果；适合 AI agent 判断是否已恢复现场
 
 参数说明：
 
 - `--mode <mode>`：回滚模式（`revert|soft|mixed|hard`）
 - `--ref <ref>`：回滚目标，默认按 mode 自动给出
+- `--hash <hash>`：按 commit hash 指定回滚目标（等同 `--ref`）
 - `--recover <action>`：冲突恢复策略（`continue|abort|keep`）
+- `--json`：输出机器可读 JSON
 - `-y, --yes`：自动确认（跳过确认提示）
 - `--repo-mode auto|strict`：仓库模式（自动继承父仓库/禁止继承）
 - `-h, --help`：查看帮助
@@ -260,11 +383,16 @@ icode undo [--mode revert|soft|mixed|hard] [--ref <ref>] [--recover continue|abo
 
 ```bash
 icode migrate <sourceBranch> <targetBranch> [--range <from..to>] [--push]
+icode migrate <sourceBranch> <targetBranch> --dry-run --json
 ```
 
 - 将 source 分支的提交迁移到 target（底层是 `cherry-pick`）
 - 默认迁移 `target..source` 的增量提交
 - 可通过 `--range` 精确指定迁移范围
+- 执行前要求工作区干净，且不能存在未完成的 merge/rebase/cherry-pick/revert
+- 支持 `--dry-run` 输出 checkout/pull/cherry-pick/push 计划，不产生 Git 副作用
+- 支持 `--json` 输出结构化计划或执行结果，适合 AI agent 消费
+- 如果迁移冲突，可使用 `icode undo --recover continue|abort|keep` 处理现场
 
 参数说明：
 
@@ -272,6 +400,8 @@ icode migrate <sourceBranch> <targetBranch> [--range <from..to>] [--push]
 - `<targetBranch>`：迁移目标分支
 - `-i, --interactive`：交互模式（单选/多选 source/target 与迁移范围）
 - `--range <from..to>`：指定提交范围，例如 `main..feature-x`
+- `--dry-run`：只展示迁移计划，不 checkout/pull/cherry-pick/push
+- `--json`：输出机器可读 JSON
 - `--push`：迁移后自动推送 target 分支
 - `-y, --yes`：自动确认（跳过确认提示）
 - `--repo-mode auto|strict`：仓库模式（自动继承父仓库/禁止继承）
@@ -286,6 +416,7 @@ icode config get defaults.repoMode
 icode config set defaults.repoMode strict
 icode config protect add main release
 icode config protect list
+icode config platform remote-merge set --provider gitlab --api-key rm_xxx
 ```
 
 参数说明：
@@ -298,6 +429,8 @@ icode config protect list
 - `protect add <branch...>`：添加受保护分支
 - `protect remove <branch...>`：移除受保护分支
 - `ai <subcommand>`：AI profile 管理（见上文“AI 能力配置”）
+- `platform remote-merge show`：查看远程合并平台配置（密钥脱敏）
+- `platform remote-merge set --provider gitlab --api-key <key>`：写入 GitLab 远程合并密钥
 - `--repo-mode auto|strict`：仓库模式（仅影响 protect）
 - `-h, --help`：查看帮助
 
@@ -331,6 +464,10 @@ icode push -m "chore: hotfix" --no-verify
 - 默认 `--repo-mode auto`：自动定位到父仓库根目录执行
 - `--repo-mode strict`：检测到继承时直接阻断，避免误操作
 
+### 3) 非 Git 目录
+
+`icode` 不会在非 Git 目录中隐式执行 `git init`。如果需要初始化仓库，请先手动执行 `git init`，再运行 `icode` 命令。
+
 ## 开发
 
 ```bash

package/bin/icode.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import('../src/cli.js').catch((error) => {
-  const message = error?.message || String(error)
-  console.error(`\x1b[31m[icode] ${message}\x1b[0m`)
-  process.exit(error?.exitCode || 1)
+import { handleCliError, main } from '../src/cli.js'
+
+main().catch((error) => {
+  handleCliError(error)
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@icode-js/icode",
-  "version": "3.0.4",
+  "version": "3.2.0",
   "description": "Modern git workflow CLI with robust parent-repo and hook handling",
   "type": "module",
   "author": "C",

package/src/cli.js

@@ -1,19 +1,24 @@
 import { runAiCommand } from './commands/ai.js'
 import { runCleanCommand } from './commands/clean.js'
 import { runCodeReviewCommand } from './commands/codereview.js'
+import { runCompletionCommand, runHiddenCompletionCommand } from './commands/completion.js'
 import { runCheckoutCommand } from './commands/checkout.js'
 import { runConfigCommand } from './commands/config.js'
+import { runDoctorCommand } from './commands/doctor.js'
 import { runExplainCommand } from './commands/explain.js'
 import { printMainHelp } from './commands/help.js'
 import { runInfoCommand } from './commands/info.js'
 import { runMigrateCommand } from './commands/migrate.js'
 import { runPushCommand } from './commands/push.js'
+import { runReadyCommand } from './commands/ready.js'
+import { runSaveCommand } from './commands/save.js'
 import { runSyncCommand } from './commands/sync.js'
 import { runTagCommand } from './commands/tag.js'
 import { runUndoCommand } from './commands/undo.js'
 import { asIcodeError } from './core/errors.js'
-import { logger } from './core/logger.js'
-import { normalizeLegacyArgs } from './core/args.js'
+import { normalizeLegacyArgs } from './core/cli/args.js'
+import { notifyIfCliUpdateAvailable } from './core/cli/update-notifier.js'
+import { logger } from './core/tools/logger.js'
 
 function isTruthy(value) {
   const normalized = String(value || '').trim().toLowerCase()
@@ -31,7 +36,10 @@ function serializeErrorMeta(meta) {
 const COMMANDS = {
   ai: runAiCommand,
   codereview: runCodeReviewCommand,
+  completion: runCompletionCommand,
   checkout: runCheckoutCommand,
+  ready: runReadyCommand,
+  save: runSaveCommand,
   push: runPushCommand,
   sync: runSyncCommand,
   clean: runCleanCommand,
@@ -39,11 +47,49 @@ const COMMANDS = {
   migrate: runMigrateCommand,
   tag: runTagCommand,
   config: runConfigCommand,
+  doctor: runDoctorCommand,
   explain: runExplainCommand,
   info: runInfoCommand,
   help: async () => {
     printMainHelp()
+  },
+  __complete: runHiddenCompletionCommand
+}
+
+const NO_UPDATE_NOTIFICATION_COMMANDS = new Set(['help', 'completion', '__complete'])
+
+/**
+ * 执行 CLI 主流程并在命令成功后触发升级提示检查。
+ * 输入为命令行参数与可注入依赖，输出为建议的退出码。
+ */
+export async function runCli(argv = process.argv.slice(2), dependencies = {}) {
+  const commands = dependencies.commands || COMMANDS
+  const printHelp = dependencies.printMainHelp || printMainHelp
+  const notifyUpdate = dependencies.notifyIfCliUpdateAvailable || notifyIfCliUpdateAvailable
+  const { globalArgs, commandName, commandArgs } = parseEntryArgs(argv)
+  const globalResult = applyGlobalFlags(globalArgs)
+
+  if (globalResult.shouldExit) {
+    return globalResult.exitCode
+  }
+
+  if (!commandName) {
+    printHelp()
+    return 0
+  }
+
+  const command = commands[commandName]
+  if (!command) {
+    throw new Error(`未知命令: ${commandName}`)
+  }
+
+  await command(commandArgs)
+
+  if (!NO_UPDATE_NOTIFICATION_COMMANDS.has(commandName)) {
+    await notifyUpdate()
   }
+
+  return 0
 }
 
 function parseEntryArgs(argv) {
@@ -86,28 +132,19 @@ function applyGlobalFlags(globalArgs) {
   }
 }
 
-async function main() {
-  const { globalArgs, commandName, commandArgs } = parseEntryArgs(process.argv.slice(2))
-  const globalResult = applyGlobalFlags(globalArgs)
-
-  if (globalResult.shouldExit) {
-    process.exit(globalResult.exitCode)
-  }
-
-  if (!commandName) {
-    printMainHelp()
-    process.exit(0)
-  }
-
-  const command = COMMANDS[commandName]
-  if (!command) {
-    throw new Error(`未知命令: ${commandName}`)
-  }
-
-  await command(commandArgs)
+/**
+ * 启动 CLI 入口，复用 runCli 处理参数与命令调度。
+ * 输入为可选 argv 与依赖注入，输出为退出码。
+ */
+export async function main(argv = process.argv.slice(2), dependencies = {}) {
+  return runCli(argv, dependencies)
 }
 
-main().catch((error) => {
+/**
+ * 统一处理 CLI 异常并输出对用户可读的错误信息。
+ * 输入为任意异常对象，输出为进程退出。
+ */
+export function handleCliError(error) {
   const normalized = asIcodeError(error)
   logger.error(normalized.message)
 
@@ -128,4 +165,4 @@ main().catch((error) => {
   }
 
   process.exit(normalized.exitCode || 1)
-})
+}

package/src/commands/ai.js

@@ -1,9 +1,9 @@
 import { parseArgs } from 'node:util'
-import { normalizeLegacyArgs } from '../core/args.js'
-import { getAiCommandOptions } from '../core/ai-config.js'
-import { formatAiCommitSummary } from '../core/ai-commit-summary.js'
+import { formatAiCommitSummary } from '../core/ai/commit-summary.js'
+import { getAiCommandOptions } from '../core/ai/config.js'
+import { normalizeLegacyArgs } from '../core/cli/args.js'
 import { IcodeError } from '../core/errors.js'
-import { logger } from '../core/logger.js'
+import { logger } from '../core/tools/logger.js'
 import { runAiCodeReviewWorkflow } from '../workflows/ai-codereview-workflow.js'
 import { runAiCommitWorkflow } from '../workflows/ai-commit-workflow.js'
 import { runAiConflictWorkflow } from '../workflows/ai-conflict-workflow.js'

package/src/commands/checkout.js

@@ -1,6 +1,6 @@
 import { parseArgs } from 'node:util'
-import { normalizeLegacyArgs } from '../core/args.js'
-import { logger } from '../core/logger.js'
+import { normalizeLegacyArgs } from '../core/cli/args.js'
+import { logger } from '../core/tools/logger.js'
 import { runCheckoutWorkflow } from '../workflows/checkout-workflow.js'
 
 function printHelp() {

package/src/commands/clean.js

@@ -1,5 +1,6 @@
 import { parseArgs } from 'node:util'
-import { logger } from '../core/logger.js'
+import { normalizeLegacyArgs } from '../core/cli/args.js'
+import { logger } from '../core/tools/logger.js'
 import { runCleanWorkflow } from '../workflows/clean-workflow.js'
 
 function printHelp() {
@@ -26,9 +27,11 @@ Examples:
 `)
 }
 
+// 执行 clean 子命令，输入原始参数，输出清理结果；参数会先做历史别名归一化。
 export async function runCleanCommand(rawArgs) {
+  const args = normalizeLegacyArgs(rawArgs)
   const parsed = parseArgs({
-    args: rawArgs,
+    args,
     allowPositionals: true,
     options: {
       'merged-target': { type: 'string' },

package/src/commands/codereview.js

@@ -1,5 +1,6 @@
 import { parseArgs } from 'node:util'
-import { logger } from '../core/logger.js'
+import { normalizeLegacyArgs } from '../core/cli/args.js'
+import { logger } from '../core/tools/logger.js'
 import { runAiCodeReviewWorkflow } from '../workflows/ai-codereview-workflow.js'
 
 function printHelp() {
@@ -18,9 +19,11 @@ Options:
 `)
 }
 
+// 执行 codereview 子命令，输入原始参数，输出 AI 代码评审结果；参数会先归一化。
 export async function runCodeReviewCommand(rawArgs) {
+  const args = normalizeLegacyArgs(rawArgs)
   const parsed = parseArgs({
-    args: rawArgs,
+    args,
     allowPositionals: true,
     options: {
       base: { type: 'string' },

package/src/commands/completion.js

@@ -0,0 +1,93 @@
+import { parseArgs } from 'node:util'
+import { normalizeLegacyArgs } from '../core/cli/args.js'
+import { IcodeError } from '../core/errors.js'
+import { getCompletionCandidates, renderCompletionScript } from '../core/cli/completion.js'
+
+/**
+ * 输出 completion 命令帮助，说明支持的 shell 与安装方式。
+ * 输入为空，输出为标准输出文本。
+ */
+function printHelp() {
+  process.stdout.write(`
+Usage:
+  icode completion <bash|zsh>
+
+Options:
+  -h, --help             查看帮助
+
+Examples:
+  source <(icode completion bash)
+  source <(icode completion zsh)
+`)
+}
+
+/**
+ * 解析隐藏补全命令参数，提取当前词与已确认参数列表。
+ * 输入为隐藏命令的原始参数数组，输出为 current 和 previousWords。
+ */
+function parseHiddenCompletionArgs(rawArgs) {
+  const args = normalizeLegacyArgs(rawArgs)
+  let current = ''
+  let separatorIndex = args.indexOf('--')
+
+  if (separatorIndex === -1) {
+    separatorIndex = args.length
+  }
+
+  for (let index = 0; index < separatorIndex; index += 1) {
+    const token = args[index]
+    if (token === '--current') {
+      current = args[index + 1] || ''
+      index += 1
+    }
+  }
+
+  return {
+    current,
+    previousWords: args.slice(separatorIndex + 1)
+  }
+}
+
+/**
+ * 执行公开的 completion 命令，输出对应 shell 的补全脚本。
+ * 输入为命令行参数数组，输出为脚本文本到标准输出。
+ */
+export async function runCompletionCommand(rawArgs) {
+  const args = normalizeLegacyArgs(rawArgs)
+  const parsed = parseArgs({
+    args,
+    allowPositionals: true,
+    options: {
+      help: { type: 'boolean', short: 'h', default: false }
+    }
+  })
+
+  if (parsed.values.help || parsed.positionals.length === 0) {
+    printHelp()
+    return
+  }
+
+  const [shellName] = parsed.positionals
+  const normalizedShell = shellName.trim().toLowerCase()
+  if (!['bash', 'zsh'].includes(normalizedShell)) {
+    throw new IcodeError(`completion 仅支持 bash|zsh，当前输入: ${shellName}`, {
+      code: 'COMPLETION_SHELL_INVALID',
+      exitCode: 2
+    })
+  }
+
+  process.stdout.write(renderCompletionScript(normalizedShell))
+}
+
+/**
+ * 执行隐藏补全命令，只输出候选项，避免污染 shell 的补全结果。
+ * 输入为隐藏命令参数数组，输出为逐行候选项到标准输出。
+ */
+export async function runHiddenCompletionCommand(rawArgs) {
+  const { current, previousWords } = parseHiddenCompletionArgs(rawArgs)
+  const candidates = getCompletionCandidates(previousWords, current)
+
+  if (candidates.length > 0) {
+    process.stdout.write(`${candidates.join('\n')}\n`)
+  }
+}