@icode-js/icode 3.0.4 → 3.2.0

package/src/commands/ready.js

@@ -0,0 +1,110 @@
+import { parseArgs } from 'node:util'
+import { normalizeLegacyArgs } from '../core/cli/args.js'
+import { logger } from '../core/tools/logger.js'
+import { withSpinner } from '../core/tools/loading.js'
+import { runReadyWorkflow } from '../workflows/ready-workflow.js'
+
+/**
+ * 输出 ready 子命令帮助。
+ * 输入为空，输出标准帮助文本。
+ */
+function printHelp() {
+  process.stdout.write(`
+Usage:
+  icode ready [options]
+
+Options:
+  --repo-mode <mode>     仓库模式: auto(自动继承父仓库) | strict(禁止继承)
+  --json                 输出机器可读 JSON，适合 AI agent 或脚本消费
+  -h, --help             查看帮助
+
+Notes:
+  ready 用于判断当前仓库是否适合继续 save/push/remote-merge，不会修改 Git 状态。
+`)
+}
+
+/**
+ * 根据检查状态选择彩色输出函数。
+ * 输入为 pass/warn/fail，输出 logger 方法。
+ */
+function resolveLogMethod(status) {
+  if (status === 'fail') {
+    return logger.error
+  }
+  if (status === 'warn') {
+    return logger.warn
+  }
+  return logger.success
+}
+
+/**
+ * 输出单条 ready 检查结果。
+ * 输入为检查项，输出彩色日志和下一步建议。
+ */
+function printCheck(check) {
+  const log = resolveLogMethod(check.status).bind(logger)
+  const statusLabel = check.status.toUpperCase()
+  log(`[${statusLabel}] ${check.title}: ${check.detail}`)
+  if (check.nextStep) {
+    logger.info(`下一步: ${check.nextStep}`)
+  }
+}
+
+/**
+ * 输出 ready 的人类可读摘要。
+ * 输入为 workflow 返回结果，输出分色日志。
+ */
+function printReadyResult(result) {
+  const branchText = logger.color('green', result.context.currentBranch || 'DETACHED')
+  const statusColor = result.status === 'fail' ? 'red' : result.status === 'warn' ? 'yellow' : 'green'
+  const statusText = logger.color(statusColor, result.status.toUpperCase())
+
+  logger.info(`仓库根目录: ${result.context.topLevelPath}`)
+  logger.info(`当前分支: ${branchText}`)
+  logger.info(`整体状态: ${statusText}`)
+  logger.info(`改动统计: staged=${result.changes.staged}, unstaged=${result.changes.unstaged}, untracked=${result.changes.untracked}, conflicted=${result.changes.conflicted}`)
+
+  if (result.upstream.configured) {
+    logger.info(`upstream: ${result.upstream.upstream} (ahead=${result.upstream.ahead}, behind=${result.upstream.behind})`)
+  } else {
+    logger.warn('upstream: 未配置')
+  }
+
+  result.checks.forEach((check) => {
+    printCheck(check)
+  })
+}
+
+/**
+ * 执行 ready 子命令。
+ * 输入为原始参数，输出 ready workflow 结果；关键假设是该命令只读，不产生 Git 副作用。
+ */
+export async function runReadyCommand(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 withSpinner('检查仓库就绪状态', () => runReadyWorkflow({
+    repoMode: parsed.values['repo-mode']
+  }))
+
+  if (parsed.values.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+    return result
+  }
+
+  printReadyResult(result)
+  return result
+}

package/src/commands/save.js

@@ -0,0 +1,98 @@
+import { parseArgs } from 'node:util'
+import { normalizeLegacyArgs } from '../core/cli/args.js'
+import { logger } from '../core/tools/logger.js'
+import { runSaveWorkflow } from '../workflows/save-workflow.js'
+
+/**
+ * 输出 save 子命令帮助。
+ * 输入为空，输出标准帮助文本。
+ */
+function printHelp() {
+  process.stdout.write(`
+Usage:
+  icode save (--message <msg> | --ai-commit) [options]
+
+Options:
+  -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 <mode>     仓库模式: auto(自动继承父仓库) | strict(禁止继承)
+  --no-verify            commit 时跳过 hook/husky 校验
+  -y, --yes              自动确认 AI 提交（仅 --ai-commit 且非 dry-run 时有意义）
+  -h, --help             查看帮助
+
+Notes:
+  save 是安全快速提交场景：检查状态 -> 暂存全部改动 -> commit。不会 push。
+`)
+}
+
+/**
+ * 输出 save 人类可读结果。
+ * 输入为 workflow 结果，输出分色摘要。
+ */
+function printSaveResult(result) {
+  logger.info(`仓库根目录: ${result.context.topLevelPath}`)
+  logger.info(`当前分支: ${logger.color('green', result.context.currentBranch)}`)
+  logger.info(`提交来源: ${result.source === 'ai' ? logger.color('cyan', 'AI') : logger.color('cyan', 'message')}`)
+  logger.info(`改动统计: staged=${result.changes.staged}, unstaged=${result.changes.unstaged}, untracked=${result.changes.untracked}`)
+
+  if (result.dryRun) {
+    logger.warn('dry-run: 未执行 git add 或 git commit')
+    logger.info(`计划提交信息:\n${logger.color('yellow', result.commitMessage)}`)
+    return
+  }
+
+  logger.success(`本地提交已创建: ${logger.color('green', result.commitId)}`)
+  logger.info(`提交信息:\n${result.commitMessage}`)
+}
+
+/**
+ * 执行 save 子命令。
+ * 输入为原始参数，输出 save workflow 结果；关键假设是提交信息来源必须显式且唯一。
+ */
+export async function runSaveCommand(rawArgs) {
+  const args = normalizeLegacyArgs(rawArgs)
+  const parsed = parseArgs({
+    args,
+    allowPositionals: true,
+    options: {
+      message: { type: 'string', short: 'm' },
+      'ai-commit': { type: 'boolean', default: false },
+      profile: { type: 'string', default: '' },
+      lang: { type: 'string', default: 'zh' },
+      'dry-run': { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+      'repo-mode': { type: 'string', default: 'auto' },
+      'no-verify': { type: 'boolean', default: false },
+      yes: { type: 'boolean', short: 'y', default: false },
+      help: { type: 'boolean', short: 'h', default: false }
+    }
+  })
+
+  if (parsed.values.help) {
+    printHelp()
+    return
+  }
+
+  const result = await runSaveWorkflow({
+    message: parsed.values.message,
+    aiCommit: parsed.values['ai-commit'],
+    profile: parsed.values.profile,
+    lang: parsed.values.lang,
+    dryRun: parsed.values['dry-run'],
+    repoMode: parsed.values['repo-mode'],
+    noVerify: parsed.values['no-verify'],
+    yes: parsed.values.yes
+  })
+
+  if (parsed.values.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+    return result
+  }
+
+  printSaveResult(result)
+  return result
+}

package/src/commands/sync.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 { runSyncWorkflow } from '../workflows/sync-workflow.js'
 
 function printHelp() {

package/src/commands/tag.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 { runTagWorkflow } from '../workflows/tag-workflow.js'
 
 function printHelp() {

package/src/commands/undo.js

@@ -1,16 +1,24 @@
 import { parseArgs } from 'node:util'
-import { logger } from '../core/logger.js'
+import { normalizeLegacyArgs } from '../core/cli/args.js'
+import { IcodeError } from '../core/errors.js'
+import { logger } from '../core/tools/logger.js'
 import { runUndoWorkflow } from '../workflows/undo-workflow.js'
 
+/**
+ * 输出 undo 命令帮助文本。
+ * 输入为空，输出为标准输出文本。
+ */
 function printHelp() {
   process.stdout.write(`
 Usage:
-  icode undo [options]
+  icode undo [ref] [options]
 
 Options:
   --mode <mode>          回滚模式: revert | soft | mixed | hard
   --ref <ref>            回滚目标，默认按 mode 自动给出
+  --hash <hash>          按 commit hash 指定回滚目标（等同 --ref）
   --recover <action>     冲突恢复策略: continue | abort | keep
+  --json                 输出机器可读 JSON，适合 AI agent 或脚本消费
   -y, --yes              自动确认（跳过确认提示）
   --repo-mode <mode>     仓库模式: auto(自动继承父仓库) | strict(禁止继承)
   -h, --help             查看帮助
@@ -20,20 +28,76 @@ Notes:
 
 Examples:
   icode undo
+  icode undo a1b2c3d
   icode undo --mode revert --ref HEAD~2
+  icode undo --mode hard --hash a1b2c3d -y
   icode undo --recover abort
+  icode undo --mode revert --ref HEAD --json
   icode undo --mode hard --ref HEAD~1 -y
 `)
 }
 
+/**
+ * 归一化 undo 命令参数。
+ * 输入为 parseArgs 的 values、positionals 与默认配置，输出为 workflow 可直接使用的显式选项。
+ */
+export function resolveUndoWorkflowOptions(values, positionals, defaults = {}) {
+  if (positionals.length > 1) {
+    throw new IcodeError('undo 最多支持一个位置参数作为回滚目标 ref/hash', {
+      code: 'UNDO_POSITIONAL_INVALID',
+      exitCode: 2
+    })
+  }
+
+  const refCandidates = [
+    { source: '--ref', value: values.ref },
+    { source: '--hash', value: values.hash },
+    { source: 'position', value: positionals[0] }
+  ].filter((candidate) => typeof candidate.value === 'string' && candidate.value.trim())
+
+  const normalizedRefs = refCandidates.map((candidate) => ({
+    source: candidate.source,
+    value: candidate.value.trim()
+  }))
+  const firstRef = normalizedRefs[0]?.value
+  const conflict = normalizedRefs.find((candidate) => candidate.value !== firstRef)
+
+  if (conflict) {
+    throw new IcodeError(
+      `undo 回滚目标冲突: ${normalizedRefs.map((item) => `${item.source}=${item.value}`).join(', ')}`,
+      {
+        code: 'UNDO_REF_CONFLICT',
+        exitCode: 2
+      }
+    )
+  }
+
+  return {
+    mode: values.mode,
+    ref: firstRef,
+    recover: values.recover,
+    json: values.json === true,
+    silentLog: values.json === true,
+    yes: values.yes === true,
+    repoMode: values['repo-mode'] || defaults.repoMode || 'auto'
+  }
+}
+
+/**
+ * 执行 undo 命令。
+ * 输入为子命令参数数组，输出为空；内部会按参数调用 undo workflow 并打印结果。
+ */
 export async function runUndoCommand(rawArgs) {
+  const args = normalizeLegacyArgs(rawArgs)
   const parsed = parseArgs({
-    args: rawArgs,
+    args,
     allowPositionals: true,
     options: {
       mode: { type: 'string' },
       ref: { type: 'string' },
+      hash: { type: 'string' },
       recover: { type: 'string' },
+      json: { type: 'boolean', default: false },
       yes: { type: 'boolean', short: 'y', default: false },
       'repo-mode': { type: 'string', default: 'auto' },
       help: { type: 'boolean', short: 'h', default: false }
@@ -45,13 +109,12 @@ export async function runUndoCommand(rawArgs) {
     return
   }
 
-  const result = await runUndoWorkflow({
-    mode: parsed.values.mode,
-    ref: parsed.values.ref,
-    recover: parsed.values.recover,
-    yes: parsed.values.yes,
-    repoMode: parsed.values['repo-mode']
-  })
+  const result = await runUndoWorkflow(resolveUndoWorkflowOptions(parsed.values, parsed.positionals))
+
+  if (parsed.values.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+    return result
+  }
 
   if (result.canceled) {
     return

package/src/core/{ai-client.js → ai/client.js}

@@ -1,6 +1,6 @@
-import { IcodeError } from './errors.js'
-import { getAiProfile } from './ai-config.js'
-import { withSpinner } from './loading.js'
+import { IcodeError } from '../errors.js'
+import { withSpinner } from '../tools/loading.js'
+import { getAiProfile } from './config.js'
 
 function trimSlash(value) {
   return value.replace(/\/+$/, '')

package/src/core/{ai-config.js → ai/config.js}

@@ -1,5 +1,5 @@
-import { IcodeError } from './errors.js'
-import { readConfig, writeConfig } from './config-store.js'
+import { IcodeError } from '../errors.js'
+import { readConfig, writeConfig } from '../config/store.js'
 
 const DEFAULT_PROFILE = {
   provider: 'custom',

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

@@ -0,0 +1,204 @@
+// 归一化 diff 字符预算，输入任意 limit，输出正整数预算。
+function normalizeLimit(limit) {
+  const value = Number(limit)
+  return Number.isInteger(value) && value > 0 ? value : 12000
+}
+
+// 从 diff 文件头中提取展示路径，输入 `diff --git` 头，输出新路径优先的文件路径。
+function extractFilePathFromDiffHeader(header) {
+  const match = String(header || '').match(/^diff --git\s+a\/(.+?)\s+b\/(.+)$/)
+  if (!match) {
+    return ''
+  }
+
+  const oldPath = match[1]
+  const newPath = match[2]
+  if (newPath && newPath !== 'dev/null') {
+    return newPath
+  }
+  return oldPath || ''
+}
+
+// 将 unified diff 拆成文件级块，输入为 diff 文本，输出前缀和按文件划分的块；关键假设是 git diff 使用标准 `diff --git` 文件头。
+export function splitUnifiedDiffByFile(diff) {
+  const text = String(diff || '')
+  const markerPattern = /^diff --git .+$/gm
+  const markers = [...text.matchAll(markerPattern)]
+
+  if (!markers.length) {
+    return {
+      prefix: '',
+      blocks: []
+    }
+  }
+
+  const prefix = text.slice(0, markers[0].index).trim()
+  const blocks = markers.map((marker, index) => {
+    const start = marker.index
+    const end = index + 1 < markers.length ? markers[index + 1].index : text.length
+    const content = text.slice(start, end).trimEnd()
+    return {
+      path: extractFilePathFromDiffHeader(marker[0]),
+      content,
+      length: content.length
+    }
+  })
+
+  return {
+    prefix,
+    blocks
+  }
+}
+
+// 在剩余预算内追加文件 diff 块，输入输出片段、文件块和预算，输出是否完整包含及部分内容。
+function appendBlockWithinBudget(parts, block, remainingBudget) {
+  if (block.content.length <= remainingBudget) {
+    parts.push(block.content)
+    return {
+      included: true,
+      partialContent: ''
+    }
+  }
+
+  if (remainingBudget <= 120) {
+    return {
+      included: false,
+      partialContent: ''
+    }
+  }
+
+  const partialContent = `${block.content.slice(0, remainingBudget - 40).trimEnd()}\n...<file diff truncated>`
+  parts.push(partialContent)
+  return {
+    included: false,
+    partialContent
+  }
+}
+
+// 构建 diff 覆盖范围说明，输入截断状态，输出模型可读的覆盖声明。
+export function formatDiffCoverage(coverage) {
+  if (!coverage.truncated) {
+    return [
+      'Diff Coverage: full',
+      `Total files: ${coverage.totalFiles}`,
+      `Original chars: ${coverage.originalChars}`
+    ].join('\n')
+  }
+
+  const lines = [
+    'Diff Coverage: partial',
+    `Original chars: ${coverage.originalChars}`,
+    `Prompt chars: ${coverage.promptChars}`,
+    `Total files: ${coverage.totalFiles}`,
+    `Included full file diffs: ${coverage.includedFiles.length ? coverage.includedFiles.join(', ') : '(none)'}`,
+    `Included partial file diffs: ${coverage.partialFiles.length ? coverage.partialFiles.join(', ') : '(none)'}`,
+    `Omitted file diffs: ${coverage.omittedFiles.length ? coverage.omittedFiles.join(', ') : '(none)'}`,
+    'Instruction: treat omitted or partial file diffs as unknown; do not claim they were reviewed in detail.'
+  ]
+
+  return lines.join('\n')
+}
+
+// 按文件边界限制 diff 长度，输入完整 diff 和字符预算，输出截断后的 diff 与覆盖元信息。
+export function buildLimitedDiffPrompt(diff, options = {}) {
+  const text = String(diff || '').trimEnd()
+  const limit = normalizeLimit(options.limit)
+
+  if (text.length <= limit) {
+    const parsed = splitUnifiedDiffByFile(text)
+    return {
+      diff: text,
+      coverage: {
+        truncated: false,
+        originalChars: text.length,
+        promptChars: text.length,
+        totalFiles: parsed.blocks.length,
+        includedFiles: parsed.blocks.map((block) => block.path).filter(Boolean),
+        partialFiles: [],
+        omittedFiles: []
+      }
+    }
+  }
+
+  const parsed = splitUnifiedDiffByFile(text)
+  if (!parsed.blocks.length) {
+    const limitedText = `${text.slice(0, limit).trimEnd()}\n...<diff truncated>`
+    return {
+      diff: limitedText,
+      coverage: {
+        truncated: true,
+        originalChars: text.length,
+        promptChars: limitedText.length,
+        totalFiles: 0,
+        includedFiles: [],
+        partialFiles: ['unknown'],
+        omittedFiles: ['unknown']
+      }
+    }
+  }
+
+  const parts = []
+  const includedFiles = []
+  const partialFiles = []
+  const omittedFiles = []
+  let usedChars = 0
+
+  if (parsed.prefix) {
+    const prefix = parsed.prefix.length > 300 ? `${parsed.prefix.slice(0, 300).trimEnd()}\n...<diff section prefix truncated>` : parsed.prefix
+    parts.push(prefix)
+    usedChars += prefix.length + 2
+  }
+
+  for (let index = 0; index < parsed.blocks.length; index += 1) {
+    const block = parsed.blocks[index]
+    const separatorCost = parts.length ? 2 : 0
+    const remainingBudget = limit - usedChars - separatorCost
+    const result = appendBlockWithinBudget(parts, block, remainingBudget)
+
+    if (result.included) {
+      includedFiles.push(block.path || '(unknown)')
+      usedChars += block.content.length + separatorCost
+      continue
+    }
+
+    if (result.partialContent) {
+      partialFiles.push(block.path || '(unknown)')
+      usedChars += result.partialContent.length + separatorCost
+    } else {
+      omittedFiles.push(block.path || '(unknown)')
+    }
+
+    const remainingBlocks = parsed.blocks.slice(index + 1)
+    remainingBlocks.forEach((item) => {
+      omittedFiles.push(item.path || '(unknown)')
+    })
+    break
+  }
+
+  const limitedText = parts.join('\n\n').trimEnd()
+  return {
+    diff: limitedText,
+    coverage: {
+      truncated: true,
+      originalChars: text.length,
+      promptChars: limitedText.length,
+      totalFiles: parsed.blocks.length,
+      includedFiles,
+      partialFiles,
+      omittedFiles
+    }
+  }
+}
+
+// 从覆盖信息中生成简短统计，输入 coverage，输出便于命令结果或测试读取的结构。
+export function summarizeDiffCoverage(coverage) {
+  return {
+    truncated: coverage.truncated,
+    totalFiles: coverage.totalFiles,
+    includedFiles: coverage.includedFiles.length,
+    partialFiles: coverage.partialFiles.length,
+    omittedFiles: coverage.omittedFiles.length,
+    originalChars: coverage.originalChars,
+    promptChars: coverage.promptChars
+  }
+}

package/src/core/{ai-diff-range.js → ai/diff-range.js}

@@ -1,5 +1,5 @@
-import { IcodeError } from './errors.js'
-import { logger } from './logger.js'
+import { IcodeError } from '../errors.js'
+import { logger } from '../tools/logger.js'
 
 function unique(values) {
   return [...new Set(values.filter(Boolean))]

package/src/core/{args.js → cli/args.js}

@@ -1,19 +1,40 @@
 const LEGACY_ALIAS_MAP = new Map([
   ['-pm', '--pull-main'],
+  ['--pullMain', '--pull-main'],
   ['--pullMainBranch', '--pull-main'],
   ['--pushOrigin', '--push-origin'],
+  ['--localMerge', '--local-merge'],
   ['--notPushCurrent', '--not-push-current'],
+  ['--forceProtected', '--force-protected'],
   ['--repoMode', '--repo-mode'],
   ['--noVerify', '--no-verify'],
   ['--allLocal', '--all-local'],
   ['--mergeMain', '--merge-main'],
   ['--aiReview', '--ai-review'],
   ['--aiProfile', '--ai-profile'],
-  ['--aiCommit', '--ai-commit']
+  ['--aiCommit', '--ai-commit'],
+  ['--remoteMerge', '--remote-merge'],
+  ['--dryRun', '--dry-run'],
+  ['--dumpResponse', '--dump-response'],
+  ['--mergedTarget', '--merged-target'],
+  ['--baseUrl', '--base-url'],
+  ['--apiKey', '--api-key'],
+  ['--maxTokens', '--max-tokens'],
+  ['--requestBody', '--request-body']
 ])
 
+// 统一历史 camelCase 参数到当前 kebab-case 参数；输入原始 argv，输出可直接交给 parseArgs 的参数。
 export function normalizeLegacyArgs(argv = []) {
-  return argv.map((arg) => LEGACY_ALIAS_MAP.get(arg) || arg)
+  return argv.map((arg) => {
+    const separatorIndex = String(arg).indexOf('=')
+    if (separatorIndex === -1) {
+      return LEGACY_ALIAS_MAP.get(arg) || arg
+    }
+
+    const key = arg.slice(0, separatorIndex)
+    const value = arg.slice(separatorIndex)
+    return `${LEGACY_ALIAS_MAP.get(key) || key}${value}`
+  })
 }
 
 export function parseConfigValue(raw) {