@icode-js/icode 3.0.4 → 3.2.0

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 { normalizeLegacyArgs, 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:
@@ -380,14 +485,22 @@ async function resolvePolicyRoot(repoMode) {
   }
 }
 
+// 执行 config 子命令，输入原始参数，输出配置读写结果；参数会先归一化。
 export async function runConfigCommand(rawArgs) {
-  if (rawArgs[0] === 'ai') {
-    await runAiConfigCommand(rawArgs.slice(1))
+  const args = normalizeLegacyArgs(rawArgs)
+
+  if (args[0] === 'ai') {
+    await runAiConfigCommand(args.slice(1))
+    return
+  }
+
+  if (args[0] === 'platform') {
+    await runPlatformConfigCommand(args.slice(1))
     return
   }
 
   const parsed = parseArgs({
-    args: rawArgs,
+    args,
     allowPositionals: true,
     options: {
       help: { type: 'boolean', short: 'h', default: false },

package/src/commands/doctor.js

@@ -0,0 +1,80 @@
+import { parseArgs } from 'node:util'
+import { normalizeLegacyArgs } from '../core/cli/args.js'
+import { logger } from '../core/tools/logger.js'
+import { runDoctorWorkflow } from '../workflows/doctor-workflow.js'
+
+// 输出 doctor 子命令帮助，输入为空，输出标准帮助文本。
+function printHelp() {
+  process.stdout.write(`
+Usage:
+  icode doctor [options]
+
+Options:
+  --repo-mode <mode>     仓库模式: auto(自动继承父仓库) | strict(禁止继承)
+  --json                 输出机器可读 JSON
+  -h, --help             查看帮助
+
+Notes:
+  检查 Git、origin、hooks、AI profile 与远程合并配置，并给出修复建议。
+`)
+}
+
+// 根据检查状态选择输出函数，输入状态，输出 logger 方法。
+function resolveLogMethod(status) {
+  if (status === 'fail') {
+    return logger.error
+  }
+  if (status === 'warn') {
+    return logger.warn
+  }
+  return logger.success
+}
+
+// 输出单条 doctor 检查结果，输入检查项，输出彩色日志。
+function printCheck(check) {
+  const log = resolveLogMethod(check.status).bind(logger)
+  const statusLabel = check.status.toUpperCase()
+  log(`[${statusLabel}] ${check.title}: ${check.detail}`)
+  if (check.suggestion) {
+    logger.info(`建议: ${check.suggestion}`)
+  }
+}
+
+// 执行 doctor 子命令，输入原始参数，输出健康检查结果。
+// 执行 doctor 子命令，输入原始参数，输出健康检查结果；参数会先归一化。
+export async function runDoctorCommand(rawArgs) {
+  const args = normalizeLegacyArgs(rawArgs)
+  const parsed = parseArgs({
+    args,
+    allowPositionals: true,
+    options: {
+      'repo-mode': { type: 'string', default: 'auto' },
+      json: { type: 'boolean', default: false },
+      help: { type: 'boolean', short: 'h', default: false }
+    }
+  })
+
+  if (parsed.values.help) {
+    printHelp()
+    return
+  }
+
+  const result = await runDoctorWorkflow({
+    repoMode: parsed.values['repo-mode']
+  })
+
+  if (parsed.values.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+    return result
+  }
+
+  logger.info(`仓库根目录: ${result.context.topLevelPath}`)
+  logger.info(`配置文件: ${result.configPath}`)
+  result.checks.forEach((check) => {
+    printCheck(check)
+  })
+
+  const summary = result.summary
+  logger.info(`doctor 完成: pass=${summary.pass}, warn=${summary.warn}, fail=${summary.fail}`)
+  return result
+}

package/src/commands/explain.js

@@ -1,6 +1,7 @@
 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 { normalizeLegacyArgs } from '../core/cli/args.js'
+import { logger } from '../core/tools/logger.js'
 import { runAiExplainWorkflow } from '../workflows/ai-explain-workflow.js'
 
 function printHelp() {
@@ -47,10 +48,12 @@ function resolveStringOption(cliValue, configValue, fallback = '') {
   return fallback
 }
 
+// 执行 explain 子命令，输入原始参数，输出 AI 对 diff 的解释；参数会先归一化。
 export async function runExplainCommand(rawArgs) {
   const scopedOptions = getAiCommandOptions('explain')
+  const args = normalizeLegacyArgs(rawArgs)
   const parsed = parseArgs({
-    args: rawArgs,
+    args,
     allowPositionals: true,
     options: {
       base: { type: 'string' },

package/src/commands/help.js

@@ -1,3 +1,7 @@
+/**
+ * 输出主帮助文本，集中展示命令总览与常用示例。
+ * 输入为空，输出为标准输出文本。
+ */
 export function printMainHelp() {
   process.stdout.write(`
 icode v3 - Git workflow CLI
@@ -9,6 +13,8 @@ Commands:
   ai          AI 助手能力（提交信息/冲突建议/代码评审）
   codereview  AI 代码评审（不带 ai 前缀）
   checkout    切换/创建分支（本地/远程自动识别）
+  ready       检查仓库是否适合继续 save/push（适合 AI agent 读取）
+  save        安全快速提交本地改动（检查 + add + commit）
   push        提交并推送，可合并到多个目标分支
   sync        批量同步分支（fetch + pull）
   clean       清理已合并分支（可删远程）
@@ -16,8 +22,10 @@ Commands:
   migrate     迁移分支提交（cherry-pick）
   tag         创建并推送 tag（支持自动命名）
   config      查看和修改本地配置（含 AI profile）
+  doctor      检查 Git/AI/远程合并配置健康状态
   explain     AI 解释 Git diff（自然语言）
   info        查看当前 git 与配置环境
+  completion  生成 bash/zsh tab 补全脚本
   help        查看帮助（命令总览）
 
 Global options:
@@ -29,6 +37,11 @@ Tips:
 
 Examples:
   icode checkout feature/login main --push-origin
+  icode ready
+  icode ready --json
+  icode save -m "feat: add login form"
+  icode save --ai-commit -y
+  icode save -m "fix: adjust copy" --dry-run
   icode ai commit --apply -y
   icode ai codereview
   icode codereview --base origin/main --head HEAD
@@ -36,14 +49,18 @@ Examples:
   icode push release test -m "feat: batch publish" -y
   icode push release test --ai-commit -y
   icode push release test -m "feat: keep merge commit" --local-merge -y
+  icode push release test --dry-run
   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
+  icode doctor
+  source <(icode completion zsh)
   icode info
 `)
 }

package/src/commands/info.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 { runInfoWorkflow } from '../workflows/info-workflow.js'
 
 function printHelp() {
@@ -16,9 +17,11 @@ Notes:
 `)
 }
 
+// 执行 info 子命令，输入原始参数，输出仓库与配置概览；参数会先归一化。
 export async function runInfoCommand(rawArgs) {
+  const args = normalizeLegacyArgs(rawArgs)
   const parsed = parseArgs({
-    args: rawArgs,
+    args,
     allowPositionals: true,
     options: {
       'repo-mode': { type: 'string', default: 'auto' },

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() {
@@ -17,6 +17,8 @@ Arguments:
 Options:
   -i, --interactive      交互模式（单选/多选 source/target 与迁移范围）
   --range <spec>         指定提交范围，例如 main..feature-x（交互模式下若提供则直接使用）
+  --dry-run              只展示迁移计划，不 checkout/pull/cherry-pick/push
+  --json                 输出机器可读 JSON，适合 AI agent 或脚本消费
   --push                 迁移后自动推送 target 分支
   -y, --yes              自动确认（跳过确认提示）
   --repo-mode <mode>     仓库模式: auto(自动继承父仓库) | strict(禁止继承)
@@ -29,11 +31,32 @@ Notes:
 Examples:
   icode migrate feature/login release
   icode migrate --interactive
+  icode migrate feature/login release --dry-run --json
   icode migrate feature/login release --range HEAD~3..feature/login
   icode migrate feature/login release --push -y
 `)
 }
 
+// 输出 migrate dry-run 计划，输入 workflow 结果，输出人类可读步骤。
+function printDryRunPlan(result) {
+  const previewLimit = 10
+  const previewCommits = result.commits.slice(0, previewLimit)
+
+  logger.info(`[dry-run] source: ${result.sourceBranch} (${result.sourceRef})`)
+  logger.info(`[dry-run] target: ${result.targetBranch} (${result.targetRef})`)
+  logger.info(`[dry-run] range: ${result.rangeSpec}`)
+  logger.info(`[dry-run] commits: ${result.migratedCommits}`)
+  previewCommits.forEach((commit, index) => {
+    logger.info(`[dry-run] commit ${index + 1}: ${commit.summary || commit.hash}`)
+  })
+  if (result.commits.length > previewLimit) {
+    logger.info(`[dry-run] ... 还有 ${result.commits.length - previewLimit} 个提交未显示，可用 --json 查看完整计划`)
+  }
+  result.steps.forEach((step, index) => {
+    logger.info(`[dry-run] ${index + 1}. ${step.action}: ${step.detail}`)
+  })
+}
+
 export async function runMigrateCommand(rawArgs) {
   const args = normalizeLegacyArgs(rawArgs)
   const parsed = parseArgs({
@@ -42,6 +65,8 @@ export async function runMigrateCommand(rawArgs) {
     options: {
       interactive: { type: 'boolean', short: 'i', default: false },
       range: { type: 'string' },
+      'dry-run': { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
       push: { type: 'boolean', default: false },
       yes: { type: 'boolean', short: 'y', default: false },
       'repo-mode': { type: 'string', default: 'auto' },
@@ -70,16 +95,28 @@ export async function runMigrateCommand(rawArgs) {
     targetBranch,
     interactive,
     range: parsed.values.range,
+    dryRun: parsed.values['dry-run'],
     push: parsed.values.push,
     yes: parsed.values.yes,
     repoMode: parsed.values['repo-mode'],
-    noVerify: parsed.values['no-verify']
+    noVerify: parsed.values['no-verify'],
+    silentLog: parsed.values.json
   })
 
+  if (parsed.values.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+    return result
+  }
+
   if (result.canceled) {
     return
   }
 
+  if (result.dryRun) {
+    printDryRunPlan(result)
+    return result
+  }
+
   logger.success(
     `migrate 完成: ${result.sourceBranch} -> ${result.targetBranch}, commits=${result.migratedCommits}, mode=${result.rangeMode || 'range'}`
   )

package/src/commands/push.js

@@ -1,15 +1,33 @@
 import { parseArgs } from 'node:util'
-import { normalizeLegacyArgs } from '../core/args.js'
-import { getAiCommandOptions } from '../core/ai-config.js'
-import { logger } from '../core/logger.js'
+import { getAiCommandOptions } from '../core/ai/config.js'
+import { normalizeLegacyArgs } from '../core/cli/args.js'
+import { logger } from '../core/tools/logger.js'
 import { runPushWorkflow } from '../workflows/push-workflow.js'
 
+const PUSH_PARSE_OPTIONS = {
+  message: { type: 'string', short: 'm' },
+  yes: { type: 'boolean', short: 'y' },
+  'local-merge': { type: 'boolean' },
+  'remote-merge': { type: 'boolean', short: 'r' },
+  'dry-run': { type: 'boolean' },
+  'ai-commit': { type: 'boolean' },
+  'ai-profile': { type: 'string' },
+  help: { type: 'boolean', short: 'h' },
+  'pull-main': { type: 'boolean' },
+  'not-push-current': { type: 'boolean' },
+  'force-protected': { type: 'boolean' },
+  'repo-mode': { type: 'string' },
+  'no-verify': { type: 'boolean' }
+}
+
 function formatBranchStatus(status) {
   const map = {
     pushed: '已推送',
     'merged-and-pushed': '已合并并推送',
+    'remote-merged-and-pushed': '已远程合并并推送',
     'skipped-protected': '已跳过(受保护)',
-    'skipped-missing-remote': '已跳过(远程分支不存在)'
+    'skipped-missing-remote': '已跳过(远程分支不存在)',
+    paused: '已暂停'
   }
 
   return map[status] || status
@@ -27,6 +45,8 @@ Options:
   -m, --message <msg>         提交信息（未填会提示输入）
   -y, --yes                   自动确认（跳过确认提示）
   --local-merge               使用本地 merge 模式（默认，会切换分支并生成 merge commit）
+  -r, --remote-merge          使用远程 PR/MR 合并模式（默认启用项目远程合并）
+  --dry-run                   只展示计划，不执行 commit/fetch/pull/push/merge/MR
   --ai-commit                 push 前自动执行 AI commit（会参考本地 hook/commitlint 规范）
   --ai-profile <name>         指定 AI profile（用于 --ai-commit）
   --pull-main                 提交前将主分支同步到当前分支
@@ -39,6 +59,8 @@ Options:
 Notes:
   默认使用本地 merge 模式。
   未指定 target 时默认处理当前分支。
+  远程 merge 通过 PR/MR API 发起，不会本地切换到目标分支。
+  远程 merge 若出现冲突会暂停流程，并保留明确失败原因。
   布尔开关仅在命令行显式传入时生效（如 --ai-commit / --pull-main / --no-verify / -y）。
 `)
 }
@@ -69,12 +91,33 @@ function resolveStringOption(cliValue, configValue, fallback = '') {
   return fallback
 }
 
+// 统一输出 push 结果摘要，失败分支会追加具体原因，方便定位问题目标分支。
+function printPushSummary(summary = []) {
+  summary.forEach((item) => {
+    const reason = typeof item.reason === 'string' && item.reason.trim() ? ` - ${item.reason.trim()}` : ''
+    logger.info(`[结果] ${item.branch}: ${formatBranchStatus(item.status)}${reason}`)
+  })
+}
+
+// 输出 dry-run 计划摘要，输入 workflow 返回的计划，输出对用户可读的阶段列表。
+function printDryRunPlan(plan) {
+  logger.info(`[dry-run] 当前分支: ${plan.currentBranch}`)
+  logger.info(`[dry-run] 目标分支: ${plan.branchTargets.join(', ')}`)
+  logger.info(`[dry-run] 合并模式: ${plan.remoteMerge ? 'remote-merge' : 'local-merge'}`)
+  plan.steps.forEach((step, index) => {
+    const reason = step.reason ? ` - ${step.reason}` : ''
+    logger.info(`[dry-run] ${index + 1}. ${step.action}: ${step.branch}${reason}`)
+  })
+}
+
 export function resolvePushWorkflowOptions(parsedValues, parsedPositionals, scopedOptions = {}) {
   return {
     targetBranches: parsedPositionals,
     message: parsedValues.message,
     // 显式传入开关才生效，避免配置项隐式开启 push 行为。
     yes: resolveBooleanOption(parsedValues.yes, false),
+    remoteMerge: resolveBooleanOption(parsedValues['remote-merge'], false),
+    dryRun: resolveBooleanOption(parsedValues['dry-run'], false),
     aiCommit: resolveBooleanOption(parsedValues['ai-commit'], false),
     aiCommitLang: resolveStringOption(undefined, scopedOptions.aiCommitLang, 'zh'),
     aiProfile: resolveStringOption(parsedValues['ai-profile'], scopedOptions.aiProfile, ''),
@@ -86,40 +129,45 @@ export function resolvePushWorkflowOptions(parsedValues, parsedPositionals, scop
   }
 }
 
-export async function runPushCommand(rawArgs) {
+// 解析 push 子命令参数；rawArgs 是不含命令名的参数数组，返回 node:util parseArgs 的结构化结果。
+export function parsePushCommandArgs(rawArgs) {
   const args = normalizeLegacyArgs(rawArgs)
-  const scopedOptions = getAiCommandOptions('push')
-  const parsed = parseArgs({
+  return parseArgs({
     args,
     allowPositionals: true,
-    options: {
-      message: { type: 'string', short: 'm' },
-      yes: { type: 'boolean', short: 'y' },
-      'local-merge': { type: 'boolean' },
-      'ai-commit': { type: 'boolean' },
-      'ai-profile': { type: 'string' },
-      help: { type: 'boolean', short: 'h' },
-      'pull-main': { type: 'boolean' },
-      'not-push-current': { type: 'boolean' },
-      'force-protected': { type: 'boolean' },
-      'repo-mode': { type: 'string' },
-      'no-verify': { type: 'boolean' }
-    }
+    options: PUSH_PARSE_OPTIONS
   })
+}
+
+// 执行 push 子命令；rawArgs 是不含命令名的参数数组，输出结果摘要并保留 workflow 抛出的失败信息。
+export async function runPushCommand(rawArgs) {
+  const scopedOptions = getAiCommandOptions('push')
+  const parsed = parsePushCommandArgs(rawArgs)
 
   if (parsed.values.help) {
     printHelp()
     return
   }
 
-  const result = await runPushWorkflow(resolvePushWorkflowOptions(parsed.values, parsed.positionals, scopedOptions))
+  let result
+  try {
+    result = await runPushWorkflow(resolvePushWorkflowOptions(parsed.values, parsed.positionals, scopedOptions))
+  } catch (error) {
+    if (Array.isArray(error?.meta?.summary) && error.meta.summary.length) {
+      printPushSummary(error.meta.summary)
+    }
+    throw error
+  }
 
   if (result.canceled) {
     return
   }
 
-  result.summary.forEach((item) => {
-    logger.info(`[结果] ${item.branch}: ${formatBranchStatus(item.status)}`)
-  })
+  if (result.dryRun) {
+    printDryRunPlan(result.plan)
+    return
+  }
+
+  printPushSummary(result.summary)
   logger.success(`push 完成，共处理 ${result.summary.length} 个分支。`)
 }