@icode-js/icode 3.2.0 → 3.4.0

package/src/commands/sw.js

@@ -0,0 +1,89 @@
+import { parseCommandArgs, printJson } from '../core/cli/output.js'
+import { c, print, table, ui } from '../core/cli/render.js'
+import { resolveGitContext } from '../core/git/context.js'
+import { GitService } from '../core/git/service.js'
+import { logger } from '../core/tools/logger.js'
+import { listSwitchCandidates, runSwitchWorkflow } from '../workflows/switch-workflow.js'
+
+function printHelp() {
+  process.stdout.write(`
+Usage:
+  icode sw [query] [options]
+
+Arguments:
+  [query]                分支名或关键字（支持模糊匹配）；"-" 切回上一个分支；不传则交互选择
+
+Options:
+  -c, --create           新建分支并切换（基于当前分支，或 --from 指定）
+  --from <ref>           新建分支的基线
+  -a, --all              候选里包含仅存在于远程的分支（自动创建 tracking 分支）
+  --autostash            有冲突的未提交改动时自动 stash，切换后恢复
+  -l, --list             只列出分支（最近使用在前，含 ahead/behind）
+  --json                 输出机器可读 JSON
+  -y, --yes              非交互：多个候选时直接报错
+  --repo-mode <mode>     仓库模式: auto | strict
+  -h, --help             查看帮助
+
+Examples:
+  icode sw                 # 交互选择
+  icode sw login           # 模糊匹配 feature/login
+  icode sw -               # 切回上一个分支
+  icode sw -c fix/typo     # 新建
+  icode sw -l
+`)
+}
+
+function printList(list, currentBranch) {
+  print(table(list, [
+    { key: 'name', label: '分支', format: (name, item) => `${name === currentBranch ? c.green('●') : ' '} ${name === currentBranch ? c.bold(ui.branch(name)) : ui.branch(name)}` },
+    { key: 'ahead', label: '同步', format: (_, item) => [ui.sync(item.ahead, item.behind), item.gone ? c.red('远程已删') : '', item.kind === 'remote' ? c.blue('仅远程') : ''].filter(Boolean).join(' ') },
+    { key: 'relativeDate', label: '最近提交', format: (value) => ui.time(value || '') },
+    { key: 'subject', label: '', maxWidth: 60, format: (value) => ui.subject(value || '') }
+  ]))
+}
+
+export async function runSwCommand(rawArgs) {
+  const parsed = parseCommandArgs(rawArgs, {
+    create: { type: 'boolean', short: 'c', default: false },
+    from: { type: 'string' },
+    all: { type: 'boolean', short: 'a', default: false },
+    autostash: { type: 'boolean', default: false },
+    list: { type: 'boolean', short: 'l', default: false }
+  })
+  const { values, positionals } = parsed
+
+  if (values.help) {
+    printHelp()
+    return
+  }
+
+  if (values.list || (values.json && !positionals.length && !values.create)) {
+    const context = await resolveGitContext({ repoMode: values['repo-mode'] })
+    const git = new GitService(context)
+    const list = await listSwitchCandidates(git, { all: values.all })
+    if (values.json) {
+      printJson({ currentBranch: context.currentBranch, branches: list })
+      return list
+    }
+    printList(list, context.currentBranch)
+    return list
+  }
+
+  const result = await runSwitchWorkflow({
+    query: positionals[0],
+    create: values.create,
+    from: values.from,
+    all: values.all,
+    autostash: values.autostash,
+    yes: values.yes,
+    repoMode: values['repo-mode']
+  })
+
+  if (values.json) {
+    printJson(result)
+    return result
+  }
+
+  logger.success(`已切换到 ${c.bold(ui.branch(result.branch))}${result.previousBranch ? c.gray(`（来自 ${result.previousBranch}）`) : ''}`)
+  return result
+}

package/src/commands/sync.js

@@ -1,5 +1,6 @@
 import { parseArgs } from 'node:util'
 import { normalizeLegacyArgs } from '../core/cli/args.js'
+import { print, renderBranchResults } from '../core/cli/render.js'
 import { logger } from '../core/tools/logger.js'
 import { runSyncWorkflow } from '../workflows/sync-workflow.js'
 
@@ -16,6 +17,8 @@ Options:
   --merge-main            同步后把主分支 merge 到目标分支
   --rebase                pull 时使用 rebase
   --push                  同步后自动 push
+  --autostash             有未提交改动时自动 stash，结束后恢复
+  --json                  输出机器可读 JSON
   -y, --yes               自动确认（跳过确认提示）
   --repo-mode <mode>      仓库模式: auto(自动继承父仓库) | strict(禁止继承)
   --no-verify             push 时跳过 hook/husky 校验
@@ -42,6 +45,8 @@ export async function runSyncCommand(rawArgs) {
       'merge-main': { type: 'boolean', default: false },
       rebase: { type: 'boolean', default: false },
       push: { type: 'boolean', default: false },
+      autostash: { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
       yes: { type: 'boolean', short: 'y', default: false },
       'repo-mode': { type: 'string', default: 'auto' },
       'no-verify': { type: 'boolean', default: false },
@@ -60,15 +65,27 @@ export async function runSyncCommand(rawArgs) {
     mergeMain: parsed.values['merge-main'],
     rebase: parsed.values.rebase,
     push: parsed.values.push,
+    autostash: parsed.values.autostash,
     yes: parsed.values.yes,
     repoMode: parsed.values['repo-mode'],
     noVerify: parsed.values['no-verify']
   })
 
+  if (parsed.values.json) {
+    process.stdout.write(`${JSON.stringify({ ok: !result.canceled, ...result }, null, 2)}\n`)
+    return result
+  }
+
   if (result.canceled) {
     return
   }
 
-  const summaryText = result.summary.map((item) => `${item.branch}:${item.status}`).join(', ')
-  logger.success(`sync 完成: ${summaryText}`)
+  print('')
+  renderBranchResults(result.summary, {
+    synced: '已同步',
+    'synced-and-pushed': '已同步并推送',
+    missing: '本地和远程都不存在'
+  })
+  print('')
+  logger.success(`sync 完成，共 ${result.summary.length} 个分支`)
 }

package/src/commands/tag.js

@@ -1,5 +1,7 @@
 import { parseArgs } from 'node:util'
 import { normalizeLegacyArgs } from '../core/cli/args.js'
+import { printJson } from '../core/cli/output.js'
+import { c, ui } from '../core/cli/render.js'
 import { logger } from '../core/tools/logger.js'
 import { runTagWorkflow } from '../workflows/tag-workflow.js'
 
@@ -10,14 +12,28 @@ Usage:
 
 Options:
   -n, --name <tag>         指定 tag 名（默认 vYYYYMMDD_NN）
+  -b, --bump <kind>        按语义化版本递增: auto | patch | minor | major | prerelease
+  --preid <id>             预发布标识，例如 beta、rc（配合 --bump）
   -m, --message <msg>      tag 备注
   --from <ref>             从指定分支/commit 创建 tag
+  --no-push                只创建本地 tag，不推送
+  --dry-run                只计算 tag 名，不创建
+  --json                   输出机器可读 JSON
+  -y, --yes                不再询问 tag 名
   --repo-mode <mode>       仓库模式: auto(自动继承父仓库) | strict(禁止继承)
   --no-verify              跳过 hook/husky 校验
   -h, --help               查看帮助
 
 Notes:
   默认 tag 规则: vYYYYMMDD_NN（例如 v20260309_01）。
+  --bump auto 会根据上个版本以来的提交推断：破坏性变更 -> major，feat -> minor，其它 -> patch。
+  需要同时生成 changelog 和平台 Release，请用 icode release。
+
+Examples:
+  icode tag
+  icode tag --bump auto --dry-run
+  icode tag --bump minor -y
+  icode tag --bump prerelease --preid rc
 `)
 }
 
@@ -28,8 +44,14 @@ export async function runTagCommand(rawArgs) {
     allowPositionals: true,
     options: {
       name: { type: 'string', short: 'n' },
+      bump: { type: 'string', short: 'b' },
+      preid: { type: 'string' },
       message: { type: 'string', short: 'm' },
       from: { type: 'string' },
+      'no-push': { type: 'boolean', default: false },
+      'dry-run': { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+      yes: { type: 'boolean', short: 'y', default: false },
       'repo-mode': { type: 'string', default: 'auto' },
       'no-verify': { type: 'boolean', default: false },
       help: { type: 'boolean', short: 'h', default: false }
@@ -43,11 +65,28 @@ export async function runTagCommand(rawArgs) {
 
   const result = await runTagWorkflow({
     tagName: parsed.values.name,
+    bump: parsed.values.bump,
+    preid: parsed.values.preid,
     message: parsed.values.message,
     fromRef: parsed.values.from,
+    noPush: parsed.values['no-push'],
+    dryRun: parsed.values['dry-run'],
+    yes: parsed.values.yes || parsed.values.json,
+    silentLog: parsed.values.json,
     repoMode: parsed.values['repo-mode'],
     noVerify: parsed.values['no-verify']
   })
 
-  logger.success(`tag 完成: ${result.tagName}`)
+  if (parsed.values.json) {
+    printJson(result)
+    return result
+  }
+
+  if (result.dryRun) {
+    logger.info(`下一个 tag: ${c.bold(ui.tag(result.tagName))}${result.previousTag ? c.gray(`（上一个 ${result.previousTag} · ${result.bump}）`) : ''}  ${c.gray('dry-run')}`)
+    return result
+  }
+
+  logger.success(`已创建 tag ${c.bold(ui.tag(result.tagName))}${result.pushed ? c.gray(' 并已推送') : c.yellow('（未推送）')}`)
+  return result
 }

package/src/commands/undo.js

@@ -1,6 +1,7 @@
 import { parseArgs } from 'node:util'
 import { normalizeLegacyArgs } from '../core/cli/args.js'
 import { IcodeError } from '../core/errors.js'
+import { c } from '../core/cli/render.js'
 import { logger } from '../core/tools/logger.js'
 import { runUndoWorkflow } from '../workflows/undo-workflow.js'
 
@@ -17,7 +18,7 @@ Options:
   --mode <mode>          回滚模式: revert | soft | mixed | hard
   --ref <ref>            回滚目标，默认按 mode 自动给出
   --hash <hash>          按 commit hash 指定回滚目标（等同 --ref）
-  --recover <action>     冲突恢复策略: continue | abort | keep
+  --recover <action>     冲突恢复策略: continue | abort | keep（推荐直接用 icode continue / icode abort）
   --json                 输出机器可读 JSON，适合 AI agent 或脚本消费
   -y, --yes              自动确认（跳过确认提示）
   --repo-mode <mode>     仓库模式: auto(自动继承父仓库) | strict(禁止继承)
@@ -121,9 +122,14 @@ export async function runUndoCommand(rawArgs) {
   }
 
   if (result.resolvedOperation) {
-    logger.success(`undo 已处理未完成操作: ${result.resolvedOperation} -> ${result.recoverAction}`)
+    const action = result.recoverAction === 'continue' ? '已继续完成' : '已中止'
+    logger.success(`${action}未完成的 ${c.bold(result.resolvedOperation)}`)
     return
   }
 
-  logger.success(`undo 完成: mode=${result.mode}, ref=${result.ref}`)
+  const modeLabel = { revert: '生成反向提交 (revert)', soft: '撤销提交，保留暂存区', mixed: '撤销提交，保留工作区改动', hard: '撤销提交并丢弃改动' }[result.mode] || result.mode
+  logger.success(`${modeLabel}  ${c.gray(`ref=${result.ref}`)}`)
+  if (result.backupId) {
+    logger.hint(`已创建恢复点 ${result.backupId}，后悔了可以 icode rescue 找回`)
+  }
 }

package/src/core/ai/diff-range.js

@@ -25,7 +25,7 @@ function summarizeGitError(error) {
 
 export async function resolveAiDiffRange({ git, context, baseRef = '', headRef = 'HEAD', label = 'AI', explicitHead = false }) {
   const explicitBase = Boolean((baseRef || '').trim())
-  const remoteDefaultBase = `origin/${context.defaultBranch}`
+  const remoteDefaultBase = `${context.remote || 'origin'}/${context.defaultBranch}`
   const localDefaultBase = context.defaultBranch || ''
   const candidates = explicitBase
     ? [(baseRef || '').trim()]

package/src/core/cli/completion.js

@@ -8,9 +8,21 @@ const AI_COMMIT_LANG_VALUES = ['zh', 'en']
 const UNDO_MODE_VALUES = ['revert', 'soft', 'mixed', 'hard']
 const UNDO_RECOVER_VALUES = ['continue', 'abort', 'keep']
 const SHELL_VALUES = ['bash', 'zsh']
+const BUMP_VALUES = ['auto', 'patch', 'minor', 'major', 'prerelease']
+const PLATFORM_VALUES = ['github', 'gitlab', 'gitee', 'gitea']
+const PR_STATE_VALUES = ['open', 'closed', 'merged', 'all']
+const PR_MERGE_METHOD_VALUES = ['merge', 'squash', 'rebase']
+const OPEN_TARGET_VALUES = ['repo', 'pr', 'prs', 'commit', 'compare', 'ci', 'releases']
 const CONFIG_PATH_VALUES = [
+  'remote',
+  'main',
+  'repo-mode',
+  'ai-profile',
   'defaults.repoMode',
   'defaults.defaultMainBranches',
+  'defaults.remote',
+  'platforms.tokens',
+  'platforms.hosts',
   'ai.activeProfile',
   'ai.profiles',
   'ai.options',
@@ -40,8 +52,44 @@ const EXPLAIN_NODE = {
   ]
 }
 
+const JSON_OPTION = { long: '--json' }
+const YES_OPTION = { long: '--yes', short: '-y' }
+const HELP_OPTION = { long: '--help', short: '-h' }
+const REPO_MODE_OPTION = { long: '--repo-mode', valueSource: 'repo-mode' }
+const BASIC_OPTIONS = [JSON_OPTION, YES_OPTION, REPO_MODE_OPTION, HELP_OPTION]
+
+const PR_OPTIONS = [
+  { long: '--base', short: '-b', valueSource: 'branch' },
+  { long: '--title', short: '-t', valueSource: 'text' },
+  { long: '--body', valueSource: 'text' },
+  { long: '--draft' },
+  { long: '--ai' },
+  { long: '--profile', valueSource: 'ai-profile' },
+  { long: '--lang', valueSource: 'ai-commit-lang' },
+  { long: '--no-push' },
+  { long: '--web' },
+  { long: '--state', valueSource: 'pr-state' },
+  { long: '--method', valueSource: 'pr-merge-method' },
+  { long: '--branch', valueSource: 'text' },
+  { long: '--provider', valueSource: 'platform' },
+  ...BASIC_OPTIONS
+]
+
+const SW_NODE = {
+  positionals: [{ valueSource: 'branch' }],
+  options: [
+    { long: '--create', short: '-c' },
+    { long: '--from', valueSource: 'ref' },
+    { long: '--all', short: '-a' },
+    { long: '--autostash' },
+    { long: '--list', short: '-l' },
+    ...BASIC_OPTIONS
+  ]
+}
+
 const ROOT_COMPLETION_SPEC = {
   options: [
+    { long: '--remote', short: '-R', valueSource: 'remote' },
     { long: '--debug', short: '-d' },
     { long: '--help', short: '-h' }
   ],
@@ -82,6 +130,8 @@ const ROOT_COMPLETION_SPEC = {
         { long: '--yes', short: '-y' },
         { long: '--push-origin' },
         { long: '--pull-main' },
+        { long: '--autostash' },
+        { long: '--json' },
         { long: '--repo-mode', valueSource: 'repo-mode' },
         { long: '--no-verify' },
         { long: '--help', short: '-h' }
@@ -100,6 +150,8 @@ const ROOT_COMPLETION_SPEC = {
         { long: '--ai-commit' },
         { long: '--profile', valueSource: 'ai-profile' },
         { long: '--lang', valueSource: 'ai-commit-lang' },
+        { long: '--staged-only' },
+        { long: '--allow-risky' },
         { long: '--dry-run' },
         { long: '--json' },
         { long: '--repo-mode', valueSource: 'repo-mode' },
@@ -122,6 +174,10 @@ const ROOT_COMPLETION_SPEC = {
         { long: '--pull-main' },
         { long: '--not-push-current' },
         { long: '--force-protected' },
+        { long: '--force', short: '-f' },
+        { long: '--create-target' },
+        { long: '--allow-risky' },
+        { long: '--json' },
         { long: '--repo-mode', valueSource: 'repo-mode' },
         { long: '--no-verify' }
       ]
@@ -133,6 +189,8 @@ const ROOT_COMPLETION_SPEC = {
         { long: '--merge-main' },
         { long: '--rebase' },
         { long: '--push' },
+        { long: '--autostash' },
+        { long: '--json' },
         { long: '--yes', short: '-y' },
         { long: '--repo-mode', valueSource: 'repo-mode' },
         { long: '--no-verify' },
@@ -142,9 +200,14 @@ const ROOT_COMPLETION_SPEC = {
     clean: {
       options: [
         { long: '--merged-target', valueSource: 'branch' },
+        { long: '--merged' },
+        { long: '--gone' },
+        { long: '--stale', valueSource: 'text' },
         { long: '--keep', valueSource: 'branch' },
         { long: '--remote' },
         { long: '--force' },
+        { long: '--dry-run' },
+        { long: '--json' },
         { long: '--yes', short: '-y' },
         { long: '--repo-mode', valueSource: 'repo-mode' },
         { long: '--help', short: '-h' }
@@ -183,8 +246,14 @@ const ROOT_COMPLETION_SPEC = {
     tag: {
       options: [
         { long: '--name', short: '-n', valueSource: 'text' },
+        { long: '--bump', short: '-b', valueSource: 'bump' },
+        { long: '--preid', valueSource: 'text' },
         { long: '--message', short: '-m', valueSource: 'text' },
         { long: '--from', valueSource: 'ref' },
+        { long: '--no-push' },
+        { long: '--dry-run' },
+        { long: '--json' },
+        { long: '--yes', short: '-y' },
         { long: '--repo-mode', valueSource: 'repo-mode' },
         { long: '--no-verify' },
         { long: '--help', short: '-h' }
@@ -196,7 +265,34 @@ const ROOT_COMPLETION_SPEC = {
         { long: '--help', short: '-h' }
       ],
       subcommands: {
-        list: {},
+        list: {
+          options: [{ long: '--show-secrets' }]
+        },
+        path: {},
+        edit: {},
+        init: {
+          options: [{ long: '--force' }, { long: '--yes', short: '-y' }]
+        },
+        platform: {
+          subcommands: {
+            token: {
+              subcommands: {
+                show: {},
+                set: { positionals: [{ valueSource: 'platform' }] },
+                remove: { positionals: [{ valueSource: 'platform' }] }
+              }
+            },
+            host: {
+              subcommands: {
+                set: { positionals: [{ valueSource: 'text' }, { valueSource: 'platform' }] },
+                remove: {}
+              }
+            },
+            'remote-merge': {
+              subcommands: { show: {}, set: { options: [{ long: '--provider', valueSource: 'platform' }, { long: '--api-key', valueSource: 'text' }] } }
+            }
+          }
+        },
         get: {
           positionals: [{ valueSource: 'config-path' }]
         },
@@ -285,9 +381,116 @@ const ROOT_COMPLETION_SPEC = {
     info: {
       options: [
         { long: '--repo-mode', valueSource: 'repo-mode' },
+        { long: '--json' },
         { long: '--help', short: '-h' }
       ]
     },
+    continue: { options: [JSON_OPTION, REPO_MODE_OPTION, HELP_OPTION] },
+    abort: { options: BASIC_OPTIONS },
+    sw: SW_NODE,
+    switch: SW_NODE,
+    stash: {
+      options: [
+        { long: '--message', short: '-m', valueSource: 'text' },
+        { long: '--staged' },
+        { long: '--no-untracked' },
+        { long: '--index' },
+        ...BASIC_OPTIONS
+      ],
+      subcommands: {
+        list: {},
+        save: {},
+        push: {},
+        apply: {},
+        pop: {},
+        drop: {},
+        show: {}
+      }
+    },
+    log: {
+      positionals: [{ valueSource: 'ref' }],
+      options: [
+        { long: '--limit', short: '-n', valueSource: 'text' },
+        { long: '--mine' },
+        { long: '--author', valueSource: 'text' },
+        { long: '--since', valueSource: 'text' },
+        { long: '--grep', valueSource: 'text' },
+        { long: '--file', valueSource: 'text' },
+        { long: '--unpushed' },
+        { long: '--no-merges' },
+        { long: '--graph' },
+        ...BASIC_OPTIONS
+      ]
+    },
+    amend: {
+      options: [
+        { long: '--message', short: '-m', valueSource: 'text' },
+        { long: '--all', short: '-a' },
+        { long: '--allow-risky' },
+        { long: '--no-verify' },
+        ...BASIC_OPTIONS
+      ]
+    },
+    fixup: {
+      positionals: [{ valueSource: 'ref' }],
+      options: [
+        { long: '--all', short: '-a' },
+        { long: '--no-rebase' },
+        { long: '--allow-risky' },
+        { long: '--no-verify' },
+        ...BASIC_OPTIONS
+      ]
+    },
+    rescue: {
+      options: [
+        { long: '--branch', valueSource: 'text' },
+        { long: '--reset' },
+        { long: '--limit', valueSource: 'text' },
+        { long: '--keep', valueSource: 'text' },
+        ...BASIC_OPTIONS
+      ],
+      subcommands: {
+        list: {},
+        restore: {},
+        prune: {}
+      }
+    },
+    pr: {
+      options: PR_OPTIONS,
+      subcommands: {
+        create: { options: PR_OPTIONS },
+        list: { options: PR_OPTIONS },
+        view: { options: PR_OPTIONS },
+        checkout: { options: PR_OPTIONS },
+        merge: { options: PR_OPTIONS },
+        open: { options: PR_OPTIONS }
+      }
+    },
+    open: {
+      positionals: [{ valueSource: 'open-target' }],
+      options: [
+        { long: '--print', short: '-p' },
+        { long: '--branch', valueSource: 'branch' },
+        ...BASIC_OPTIONS
+      ]
+    },
+    release: {
+      options: [
+        { long: '--bump', short: '-b', valueSource: 'bump' },
+        { long: '--preid', valueSource: 'text' },
+        { long: '--name', short: '-n', valueSource: 'text' },
+        { long: '--write-changelog' },
+        { long: '--changelog-file', valueSource: 'text' },
+        { long: '--update-package' },
+        { long: '--no-platform' },
+        { long: '--draft' },
+        { long: '--prerelease' },
+        { long: '--no-push' },
+        { long: '--dry-run' },
+        { long: '--no-verify' },
+        ...BASIC_OPTIONS
+      ]
+    },
     help: {},
     completion: {
       positionals: [{ valueSource: 'shell' }],
@@ -562,6 +765,30 @@ function resolveValueCandidates(valueSource, providers) {
     return CONFIG_PATH_VALUES
   }
 
+  if (valueSource === 'bump') {
+    return BUMP_VALUES
+  }
+
+  if (valueSource === 'platform') {
+    return PLATFORM_VALUES
+  }
+
+  if (valueSource === 'pr-state') {
+    return PR_STATE_VALUES
+  }
+
+  if (valueSource === 'pr-merge-method') {
+    return PR_MERGE_METHOD_VALUES
+  }
+
+  if (valueSource === 'open-target') {
+    return OPEN_TARGET_VALUES
+  }
+
+  if (valueSource === 'remote') {
+    return listRemoteCandidates()
+  }
+
   if (valueSource === 'branch') {
     return providers.listBranchCandidates()
   }
@@ -603,6 +830,15 @@ function filterCandidates(candidates, currentWord) {
  * 读取当前仓库的分支候选项，失败时静默返回空数组。
  * 输入为空，输出为本地与远程分支名数组。
  */
+function listRemoteCandidates() {
+  try {
+    const result = spawnSync('git', ['remote'], { encoding: 'utf8' })
+    return result.status === 0 ? result.stdout.split('\n').map((item) => item.trim()).filter(Boolean) : []
+  } catch {
+    return []
+  }
+}
+
 function listBranchCandidates() {
   return listGitCandidates(['refs/heads', 'refs/remotes'])
 }

package/src/core/cli/output.js

@@ -0,0 +1,46 @@
+import { parseArgs } from 'node:util'
+import { normalizeLegacyArgs } from './args.js'
+
+/**
+ * 输出 JSON 结果；统一带上 ok 字段，方便脚本和 AI agent 判断。
+ * 输入为结果对象，输出为空。
+ */
+export function printJson(result, ok = true) {
+  const payload = result && typeof result === 'object' && !Array.isArray(result)
+    ? { ok: result.canceled ? false : ok, ...result }
+    : { ok, data: result }
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`)
+}
+
+// 所有命令共用的参数。
+export const COMMON_OPTIONS = {
+  'repo-mode': { type: 'string', default: 'auto' },
+  json: { type: 'boolean', default: false },
+  yes: { type: 'boolean', short: 'y', default: false },
+  help: { type: 'boolean', short: 'h', default: false }
+}
+
+/**
+ * 解析子命令参数：历史别名归一化 + 合并公共参数。
+ * 输入为原始参数与命令自有参数定义，输出 parseArgs 结果。
+ */
+export function parseCommandArgs(rawArgs, options = {}) {
+  return parseArgs({
+    args: normalizeLegacyArgs(rawArgs),
+    allowPositionals: true,
+    options: {
+      ...COMMON_OPTIONS,
+      ...options
+    }
+  })
+}
+
+// 左对齐补空格（按显示宽度粗略处理中文）。
+export function padDisplay(text, width) {
+  const value = String(text ?? '')
+  let displayWidth = 0
+  for (const char of value) {
+    displayWidth += /[ᄀ-￿]/.test(char) ? 2 : 1
+  }
+  return displayWidth >= width ? value : `${value}${' '.repeat(width - displayWidth)}`
+}