@icode-js/icode 3.0.3 → 3.1.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

@@ -23,6 +23,26 @@ icode info
 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` 查看子命令参数）
@@ -105,7 +125,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] [--remote-merge]
 ```
 
 示例：
@@ -120,6 +140,7 @@ icode push release test -m "feat: batch publish" -y # 默认本地 merge 推送
 - 若仓库存在 husky/hooks/commitlint 规则，AI commit 会先扫描本地规范再生成提交信息
 - 支持把当前分支合并到多个目标分支
 - 默认使用本地 merge 模式（会生成 merge commit）
+- 支持远程 PR/MR API 模式（需配置平台密钥）
 - 支持受保护分支策略（通过 `icode config protect ...` 管理）
 
 参数说明：
@@ -128,6 +149,7 @@ icode push release test -m "feat: batch publish" -y # 默认本地 merge 推送
 - `-m, --message <msg>`：提交信息（未填会提示输入）
 - `-y, --yes`：自动确认（跳过确认提示）
 - `--local-merge`：显式声明使用本地 merge 模式（当前为默认行为，会切换分支并生成 merge commit）
+- `--remote-merge`：改为远程 PR/MR 模式；会先推送源分支，再通过 API 创建合并请求；若发生冲突会暂停，并输出明确失败原因
 - `--ai-commit`：push 前自动执行 AI commit
 - `--ai-profile <name>`：指定 AI profile（用于 `--ai-commit`）
 - `--pull-main`：提交前同步主分支到当前分支
@@ -140,6 +162,19 @@ icode push release test -m "feat: batch publish" -y # 默认本地 merge 推送
 说明：
 - `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 配置。
+- 这样更符合密钥复用与安全边界，避免多个仓库重复维护同一平台 API 地址。
+
 ### ai
 
 ```bash
@@ -239,18 +274,20 @@ 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]
 ```
 
 - 向导式撤销命令（交互选择回滚策略）
 - 适合新人或低频 Git 操作场景
-- 也支持非交互参数：`--mode` + `--ref`
+- 也支持非交互参数：`--mode` + `--ref` / `--hash`
+- 支持用位置参数指定 commit hash，例如：`icode undo a1b2c3d --mode revert -y`
 - 检测到 revert/cherry-pick 冲突时，会提示继续或中止
 
 参数说明：
 
 - `--mode <mode>`：回滚模式（`revert|soft|mixed|hard`）
 - `--ref <ref>`：回滚目标，默认按 mode 自动给出
+- `--hash <hash>`：按 commit hash 指定回滚目标（等同 `--ref`）
 - `--recover <action>`：冲突恢复策略（`continue|abort|keep`）
 - `-y, --yes`：自动确认（跳过确认提示）
 - `--repo-mode auto|strict`：仓库模式（自动继承父仓库/禁止继承）

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.3",
+  "version": "3.1.0",
   "description": "Modern git workflow CLI with robust parent-repo and hook handling",
   "type": "module",
   "author": "C",

package/src/cli.js

@@ -1,6 +1,7 @@
 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 { runExplainCommand } from './commands/explain.js'
@@ -12,8 +13,9 @@ 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,6 +33,7 @@ function serializeErrorMeta(meta) {
 const COMMANDS = {
   ai: runAiCommand,
   codereview: runCodeReviewCommand,
+  completion: runCompletionCommand,
   checkout: runCheckoutCommand,
   push: runPushCommand,
   sync: runSyncCommand,
@@ -43,7 +46,44 @@ const COMMANDS = {
   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 +126,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 +159,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,5 @@
 import { parseArgs } from 'node:util'
-import { logger } from '../core/logger.js'
+import { logger } from '../core/tools/logger.js'
 import { runCleanWorkflow } from '../workflows/clean-workflow.js'
 
 function printHelp() {

package/src/commands/codereview.js

@@ -1,5 +1,5 @@
 import { parseArgs } from 'node:util'
-import { logger } from '../core/logger.js'
+import { logger } from '../core/tools/logger.js'
 import { runAiCodeReviewWorkflow } from '../workflows/ai-codereview-workflow.js'
 
 function printHelp() {

package/src/commands/completion.js

@@ -0,0 +1,90 @@
+import { parseArgs } from 'node:util'
+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) {
+  let current = ''
+  let separatorIndex = rawArgs.indexOf('--')
+
+  if (separatorIndex === -1) {
+    separatorIndex = rawArgs.length
+  }
+
+  for (let index = 0; index < separatorIndex; index += 1) {
+    const token = rawArgs[index]
+    if (token === '--current') {
+      current = rawArgs[index + 1] || ''
+      index += 1
+    }
+  }
+
+  return {
+    current,
+    previousWords: rawArgs.slice(separatorIndex + 1)
+  }
+}
+
+/**
+ * 执行公开的 completion 命令，输出对应 shell 的补全脚本。
+ * 输入为命令行参数数组，输出为脚本文本到标准输出。
+ */
+export async function runCompletionCommand(rawArgs) {
+  const parsed = parseArgs({
+    args: rawArgs,
+    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`)
+  }
+}

package/src/commands/config.js

@@ -1,6 +1,6 @@
 import path from 'node:path'
 import { parseArgs } from 'node:util'
-import { askAi } from '../core/ai-client.js'
+import { askAi } from '../core/ai/client.js'
 import {
   getAiCommandOptions,
   getAiProfileForDisplay,
@@ -11,28 +11,31 @@ import {
   upsertAiCommandOptions,
   upsertAiProfile,
   useAiProfile
-} from '../core/ai-config.js'
+} from '../core/ai/config.js'
 import {
   deleteValue,
   getConfigFilePath,
+  getPlatformConfig,
   getRepoPolicy,
   getValue,
   readConfig,
+  setPlatformConfig,
   setRepoPolicy,
   setValue
-} from '../core/config-store.js'
-import { parseConfigValue } from '../core/args.js'
+} from '../core/config/store.js'
+import { parseConfigValue } from '../core/cli/args.js'
 import { IcodeError } from '../core/errors.js'
-import { resolveGitContext } from '../core/git-context.js'
-import { logger } from '../core/logger.js'
+import { resolveGitContext } from '../core/git/context.js'
+import { logger } from '../core/tools/logger.js'
 
+// 输出 config 命令帮助，并展示当前支持的远程合并配置方式。
 function printHelp() {
   process.stdout.write(`
 Usage:
   icode config <command> [...args]
 
 Arguments:
-  <command>                子命令（list/get/set/delete/ai/protect）
+  <command>                子命令（list/get/set/delete/ai/protect/platform）
 
 Commands:
   list                    查看全部配置
@@ -43,6 +46,7 @@ Commands:
   protect list            查看受保护分支
   protect add <branch...> 添加受保护分支
   protect remove <branch...> 移除受保护分支
+  platform <subcommand>   平台级配置（如远程合并密钥）
 
 Options:
   --repo-mode <mode>      仓库模式: auto(自动继承父仓库) | strict(禁止继承)，仅影响 protect
@@ -52,11 +56,112 @@ Examples:
   icode config set defaults.repoMode strict
   icode config get defaults.repoMode
   icode config protect add main release
+  icode config platform remote-merge set --provider gitlab --api-key rm_xxx
   icode config ai set openai --format openai --base-url https://api.openai.com/v1 --api-key sk-xxx --model gpt-4o-mini --activate
   icode config ai set ollama --format ollama --base-url http://127.0.0.1:11434 --model qwen2.5:7b --activate
 `)
 }
 
+function maskSecret(secret) {
+  const raw = String(secret || '').trim()
+  if (!raw) {
+    return ''
+  }
+  if (raw.length <= 8) {
+    return `${raw.slice(0, 2)}****${raw.slice(-1)}`
+  }
+  return `${raw.slice(0, 4)}****${raw.slice(-4)}`
+}
+
+// 输出 platform 子命令帮助，明确 remote-merge 仅需平台名与密钥。
+function printPlatformHelp() {
+  process.stdout.write(`
+Usage:
+  icode config platform <subcommand> [options]
+
+Subcommands:
+  remote-merge show
+  remote-merge set --provider gitlab --api-key <key>
+
+Examples:
+  icode config platform remote-merge show
+  icode config platform remote-merge set --provider gitlab --api-key rm_xxx
+`)
+}
+
+// 处理平台级远程合并配置，当前只接受 GitLab 平台密钥写入。
+async function runPlatformConfigCommand(args) {
+  if (!args.length || args[0] === '-h' || args[0] === '--help') {
+    printPlatformHelp()
+    return
+  }
+
+  const [domain, action, ...rest] = args
+  if (domain !== 'remote-merge') {
+    throw new IcodeError(`未知 platform 子命令: ${domain}`, {
+      code: 'CONFIG_PLATFORM_UNKNOWN_SUBCOMMAND',
+      exitCode: 2
+    })
+  }
+
+  if (action === 'show') {
+    const config = getPlatformConfig('remoteMerge')
+    process.stdout.write(`${JSON.stringify({
+      provider: config.provider || '',
+      hasApiKey: Boolean(config.apiKey),
+      apiKeyMasked: maskSecret(config.apiKey)
+    }, null, 2)}\n`)
+    return
+  }
+
+  if (action === 'set') {
+    const parsed = parseArgs({
+      args: rest,
+      allowPositionals: true,
+      options: {
+        provider: { type: 'string' },
+        'api-key': { type: 'string' }
+      }
+    })
+
+    const provider = String(parsed.values.provider || '').trim()
+    const apiKey = String(parsed.values['api-key'] || '').trim()
+
+    if (!provider) {
+      throw new IcodeError('缺少 --provider，示例: icode config platform remote-merge set --provider gitlab --api-key xxx', {
+        code: 'CONFIG_PLATFORM_PROVIDER_REQUIRED',
+        exitCode: 2
+      })
+    }
+
+    if (!apiKey) {
+      throw new IcodeError('缺少 --api-key，示例: icode config platform remote-merge set --provider gitlab --api-key xxx', {
+        code: 'CONFIG_PLATFORM_API_KEY_REQUIRED',
+        exitCode: 2
+      })
+    }
+
+    if (provider !== 'gitlab') {
+      throw new IcodeError(`platform remote-merge 当前仅支持 gitlab，收到 provider=${provider}`, {
+        code: 'CONFIG_PLATFORM_PROVIDER_UNSUPPORTED',
+        exitCode: 2
+      })
+    }
+
+    setPlatformConfig('remoteMerge', {
+      provider,
+      apiKey
+    })
+    logger.success(`平台远程合并密钥已写入: ${provider}`)
+    return
+  }
+
+  throw new IcodeError('platform remote-merge 仅支持: show | set', {
+    code: 'CONFIG_PLATFORM_INVALID_ACTION',
+    exitCode: 2
+  })
+}
+
 function printAiHelp() {
   process.stdout.write(`
 Usage:
@@ -386,6 +491,11 @@ export async function runConfigCommand(rawArgs) {
     return
   }
 
+  if (rawArgs[0] === 'platform') {
+    await runPlatformConfigCommand(rawArgs.slice(1))
+    return
+  }
+
   const parsed = parseArgs({
     args: rawArgs,
     allowPositionals: true,

package/src/commands/explain.js

@@ -1,6 +1,6 @@
 import { parseArgs } from 'node:util'
-import { getAiCommandOptions } from '../core/ai-config.js'
-import { logger } from '../core/logger.js'
+import { getAiCommandOptions } from '../core/ai/config.js'
+import { logger } from '../core/tools/logger.js'
 import { runAiExplainWorkflow } from '../workflows/ai-explain-workflow.js'
 
 function printHelp() {

package/src/commands/help.js

@@ -1,3 +1,7 @@
+/**
+ * 输出主帮助文本，集中展示命令总览与常用示例。
+ * 输入为空，输出为标准输出文本。
+ */
 export function printMainHelp() {
   process.stdout.write(`
 icode v3 - Git workflow CLI
@@ -18,6 +22,7 @@ Commands:
   config      查看和修改本地配置（含 AI profile）
   explain     AI 解释 Git diff（自然语言）
   info        查看当前 git 与配置环境
+  completion  生成 bash/zsh tab 补全脚本
   help        查看帮助（命令总览）
 
 Global options:
@@ -38,12 +43,14 @@ Examples:
   icode push release test -m "feat: keep merge commit" --local-merge -y
   icode sync --all-local --merge-main
   icode clean --remote --force -y
+  icode undo a1b2c3d --mode revert -y
   icode undo --mode revert --ref HEAD~1 -y
   icode undo --recover abort
   icode migrate feature/login release --push -y
   icode migrate --interactive
   icode push --no-verify -m "chore: bypass hooks"
   icode config protect add main release
+  source <(icode completion zsh)
   icode info
 `)
 }

package/src/commands/info.js

@@ -1,5 +1,5 @@
 import { parseArgs } from 'node:util'
-import { logger } from '../core/logger.js'
+import { logger } from '../core/tools/logger.js'
 import { runInfoWorkflow } from '../workflows/info-workflow.js'
 
 function printHelp() {

package/src/commands/migrate.js

@@ -1,7 +1,7 @@
 import { parseArgs } from 'node:util'
-import { normalizeLegacyArgs } from '../core/args.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 { runMigrateWorkflow } from '../workflows/migrate-workflow.js'
 
 function printHelp() {