@icode-js/icode 3.0.4 → 3.2.0

package/src/workflows/ready-workflow.js

@@ -0,0 +1,278 @@
+import { getAiConfig } from '../core/ai/config.js'
+import { getPlatformConfig, getRepoPolicy } from '../core/config/store.js'
+import { resolveGitContext } from '../core/git/context.js'
+import { GitService } from '../core/git/service.js'
+
+/**
+ * 构建 ready 检查项。
+ * 输入为检查字段，输出稳定的检查项对象；关键假设是 status 只能是 pass/warn/fail。
+ */
+function buildCheck(id, status, title, detail, nextStep = '') {
+  return {
+    id,
+    status,
+    title,
+    detail,
+    nextStep
+  }
+}
+
+/**
+ * 汇总 ready 检查状态。
+ * 输入为检查项数组，输出整体 ok/status 和计数。
+ */
+function summarizeReadyChecks(checks) {
+  const summary = {
+    ok: true,
+    status: 'pass',
+    pass: 0,
+    warn: 0,
+    fail: 0
+  }
+
+  for (const check of checks) {
+    if (check.status === 'fail') {
+      summary.ok = false
+      summary.status = 'fail'
+      summary.fail += 1
+      continue
+    }
+
+    if (check.status === 'warn') {
+      summary.warn += 1
+      if (summary.status !== 'fail') {
+        summary.status = 'warn'
+      }
+      continue
+    }
+
+    summary.pass += 1
+  }
+
+  return summary
+}
+
+/**
+ * 从检查项提取下一步建议。
+ * 输入为检查项数组，输出去重后的建议文本数组。
+ */
+function collectNextSteps(checks) {
+  const nextSteps = []
+  const seen = new Set()
+
+  for (const check of checks) {
+    const nextStep = String(check.nextStep || '').trim()
+    if (!nextStep || seen.has(nextStep)) {
+      continue
+    }
+    seen.add(nextStep)
+    nextSteps.push(nextStep)
+  }
+
+  return nextSteps
+}
+
+/**
+ * 检查当前分支是否存在。
+ * 输入为分支名，输出 ready 检查项。
+ */
+function checkCurrentBranch(currentBranch) {
+  if (!currentBranch) {
+    return buildCheck(
+      'git.branch',
+      'fail',
+      '当前不在普通分支上',
+      '检测到 detached HEAD 或无法读取当前分支。',
+      '请先切换到明确分支，例如: icode checkout <branch>'
+    )
+  }
+
+  return buildCheck('git.branch', 'pass', '当前分支明确', currentBranch)
+}
+
+/**
+ * 检查是否存在未完成的 Git 操作。
+ * 输入为 operation 字符串，输出 ready 检查项。
+ */
+function checkInProgressOperation(operation) {
+  if (!operation) {
+    return buildCheck('git.operation', 'pass', '没有未完成的 Git 操作', '工作区未处于 merge/rebase/cherry-pick/revert 流程中。')
+  }
+
+  return buildCheck(
+    'git.operation',
+    'fail',
+    '存在未完成的 Git 操作',
+    `当前操作: ${operation}`,
+    `请先完成或中止 ${operation}，再继续执行 save/push。`
+  )
+}
+
+/**
+ * 检查工作区改动情况。
+ * 输入为结构化改动摘要，输出 ready 检查项。
+ */
+function checkChanges(changes) {
+  if (changes.conflicted > 0) {
+    return buildCheck(
+      'git.changes',
+      'fail',
+      '存在未解决冲突',
+      `冲突文件 ${changes.conflicted} 个，全部改动 ${changes.total} 个。`,
+      '请先解决冲突；如需要建议可执行: icode ai conflict'
+    )
+  }
+
+  if (!changes.clean) {
+    return buildCheck(
+      'git.changes',
+      'warn',
+      '存在未提交改动',
+      `staged=${changes.staged}, unstaged=${changes.unstaged}, untracked=${changes.untracked}`,
+      '如需安全快速提交，可执行: icode save -m "type: subject"'
+    )
+  }
+
+  return buildCheck('git.changes', 'pass', '工作区干净', '没有暂存、未暂存或未跟踪改动。')
+}
+
+/**
+ * 检查 upstream 关系。
+ * 输入为 upstream 状态，输出 ready 检查项。
+ */
+function checkUpstream(upstreamStatus) {
+  if (!upstreamStatus.configured) {
+    return buildCheck(
+      'git.upstream',
+      'warn',
+      '当前分支未设置 upstream',
+      '无法判断本地与远程领先/落后关系。',
+      '如需建立远程跟踪关系，可在首次推送时使用: icode push -m "type: subject"'
+    )
+  }
+
+  if (upstreamStatus.behind > 0) {
+    return buildCheck(
+      'git.upstream',
+      'warn',
+      '当前分支落后 upstream',
+      `${upstreamStatus.upstream}: ahead=${upstreamStatus.ahead}, behind=${upstreamStatus.behind}`,
+      '建议先同步远程变更: icode sync'
+    )
+  }
+
+  if (upstreamStatus.ahead > 0) {
+    return buildCheck(
+      'git.upstream',
+      'warn',
+      '当前分支有未推送提交',
+      `${upstreamStatus.upstream}: ahead=${upstreamStatus.ahead}, behind=${upstreamStatus.behind}`,
+      '如需发布当前分支，可执行: icode push'
+    )
+  }
+
+  return buildCheck(
+    'git.upstream',
+    'pass',
+    'upstream 已同步',
+    `${upstreamStatus.upstream}: ahead=0, behind=0`
+  )
+}
+
+/**
+ * 检查 AI profile 是否可用于 AI 场景。
+ * 输入为 AI 配置，输出 ready 检查项。
+ */
+function checkAiProfile(aiConfig) {
+  const activeProfile = String(aiConfig.activeProfile || '').trim()
+  const profileCount = Object.keys(aiConfig.profiles || {}).length
+
+  if (!activeProfile || profileCount === 0) {
+    return buildCheck(
+      'ai.profile',
+      'warn',
+      'AI profile 未配置',
+      'save --ai-commit、codereview、explain 等能力不可用。',
+      '如需 AI 能力，请先执行: icode config ai set <name> ... --activate'
+    )
+  }
+
+  return buildCheck('ai.profile', 'pass', 'AI profile 可用', `activeProfile=${activeProfile}, profileCount=${profileCount}`)
+}
+
+/**
+ * 检查远程合并配置是否可用于 remote-merge 场景。
+ * 输入为平台配置和仓库策略，输出 ready 检查项。
+ */
+function checkRemoteMerge(remoteMergePlatform, repoPolicy) {
+  const repoRemoteMerge = repoPolicy.remoteMerge && typeof repoPolicy.remoteMerge === 'object'
+    ? repoPolicy.remoteMerge
+    : {}
+
+  if (repoRemoteMerge.enabled === false) {
+    return buildCheck('remoteMerge.config', 'pass', '远程合并已禁用', '当前仓库策略明确禁用 remote merge。')
+  }
+
+  if (!remoteMergePlatform.provider || !remoteMergePlatform.apiKey) {
+    return buildCheck(
+      'remoteMerge.config',
+      'warn',
+      '远程合并配置不完整',
+      '缺少 provider 或 apiKey，push -r 不可用。',
+      '如需远程合并，请执行: icode config platform remote-merge set --provider gitlab --api-key <key>'
+    )
+  }
+
+  return buildCheck('remoteMerge.config', 'pass', '远程合并配置可用', `provider=${remoteMergePlatform.provider}`)
+}
+
+/**
+ * 执行场景化就绪检查。
+ * 输入为仓库选项，输出面向人类和 AI agent 的稳定状态结构。
+ */
+export async function runReadyWorkflow(options = {}) {
+  const context = await resolveGitContext({
+    cwd: options.cwd,
+    repoMode: options.repoMode
+  })
+  const git = new GitService(context)
+  const [currentBranch, operation, changes, upstream] = await Promise.all([
+    git.getCurrentBranch(),
+    git.getInProgressOperation(),
+    git.getStatusSummary(),
+    git.getUpstreamStatus()
+  ])
+  const aiConfig = getAiConfig()
+  const repoPolicy = getRepoPolicy(context.topLevelPath)
+  const remoteMergePlatform = getPlatformConfig('remoteMerge')
+
+  const checks = [
+    checkCurrentBranch(currentBranch),
+    checkInProgressOperation(operation),
+    checkChanges(changes),
+    checkUpstream(upstream),
+    checkAiProfile(aiConfig),
+    checkRemoteMerge(remoteMergePlatform, repoPolicy)
+  ]
+  const summary = summarizeReadyChecks(checks)
+
+  return {
+    ok: summary.ok,
+    status: summary.status,
+    summary,
+    context: {
+      cwd: context.cwd,
+      topLevelPath: context.topLevelPath,
+      repoMode: context.repoMode,
+      currentBranch,
+      defaultBranch: context.defaultBranch,
+      inheritedFromParent: context.inheritedFromParent,
+      isSubmodule: context.isSubmodule
+    },
+    operation,
+    changes,
+    upstream,
+    checks,
+    nextSteps: collectNextSteps(checks)
+  }
+}

package/src/workflows/rollback-workflow.js

@@ -1,14 +1,29 @@
 import { IcodeError } from '../core/errors.js'
-import { resolveGitContext } from '../core/git-context.js'
-import { GitService } from '../core/git-service.js'
-import { logger } from '../core/logger.js'
-import { confirm } from '../core/prompts.js'
+import { resolveGitContext } from '../core/git/context.js'
+import { GitService } from '../core/git/service.js'
+import { confirm } from '../core/tools/interactive.js'
+import { logger } from '../core/tools/logger.js'
 
 function isRevertConflict(error) {
   const output = `${error?.meta?.stdout || ''}\n${error?.meta?.stderr || ''}\n${error?.message || ''}`
   return /revert is already in progress|could not revert|after resolving the conflicts|CONFLICT \(/i.test(output)
 }
 
+// 静默模式下输出 info 日志，输入执行选项和日志文本，输出为空。
+function logInfo(options, message) {
+  if (!options.silentLog) {
+    logger.info(message)
+  }
+}
+
+// 静默模式下输出 warn 日志，输入执行选项和日志文本，输出为空。
+function logWarn(options, message) {
+  if (!options.silentLog) {
+    logger.warn(message)
+  }
+}
+
+// 执行底层回滚操作，输入 mode/ref/仓库选项，输出执行结果。
 export async function runRollbackWorkflow(options) {
   const mode = options.mode || 'revert'
   const ref = options.ref || (mode === 'revert' ? 'HEAD' : 'HEAD~1')
@@ -20,13 +35,13 @@ export async function runRollbackWorkflow(options) {
 
   const git = new GitService(context)
 
-  logger.info(`仓库根目录: ${context.topLevelPath}`)
+  logInfo(options, `仓库根目录: ${context.topLevelPath}`)
   if (context.inheritedFromParent) {
-    logger.warn('当前目录继承了父级 Git 仓库，命令将基于父仓库根目录执行。')
+    logWarn(options, '当前目录继承了父级 Git 仓库，命令将基于父仓库根目录执行。')
   }
 
   if (mode === 'revert') {
-    logger.info(`执行回滚(revert): ${ref}`)
+    logInfo(options, `执行回滚(revert): ${ref}`)
     try {
       await git.revert(ref)
     } catch (error) {
@@ -63,7 +78,7 @@ export async function runRollbackWorkflow(options) {
       false
     )
     if (!accepted) {
-      logger.warn('已取消 hard 回滚。')
+      logWarn(options, '已取消 hard 回滚。')
       return {
         canceled: true,
         mode,
@@ -73,7 +88,7 @@ export async function runRollbackWorkflow(options) {
     }
   }
 
-  logger.info(`执行回滚(reset --${mode}): ${ref}`)
+  logInfo(options, `执行回滚(reset --${mode}): ${ref}`)
   await git.reset(mode, ref)
 
   return {

package/src/workflows/save-workflow.js

@@ -0,0 +1,152 @@
+import { getAiProfile } from '../core/ai/config.js'
+import { IcodeError } from '../core/errors.js'
+import { resolveGitContext } from '../core/git/context.js'
+import {
+  assertNoConflictedFiles,
+  assertNoPendingOperation,
+  assertOnBranch,
+  readGitSafetyState
+} from '../core/git/preconditions.js'
+import { GitService } from '../core/git/service.js'
+import { runAiCommitWorkflow } from './ai-commit-workflow.js'
+
+/**
+ * 清理提交信息。
+ * 输入为任意字符串，输出去掉首尾空白后的提交信息。
+ */
+function normalizeMessage(message) {
+  return String(message || '').trim()
+}
+
+/**
+ * 校验 save 的提交信息来源。
+ * 输入为 workflow options，输出为空；发现冲突配置时抛错。
+ */
+function validateMessageSource(options) {
+  const hasMessage = Boolean(normalizeMessage(options.message))
+  const useAiCommit = options.aiCommit === true
+
+  if (hasMessage && useAiCommit) {
+    throw new IcodeError('不能同时使用 --message 和 --ai-commit。请明确选择一种提交信息来源。', {
+      code: 'SAVE_MESSAGE_SOURCE_CONFLICT',
+      exitCode: 2
+    })
+  }
+
+  if (!hasMessage && !useAiCommit) {
+    throw new IcodeError('缺少提交信息。请使用 --message <msg>，或显式使用 --ai-commit。', {
+      code: 'SAVE_MESSAGE_REQUIRED',
+      exitCode: 2
+    })
+  }
+}
+
+/**
+ * 校验当前仓库是否允许执行 save。
+ * 输入为当前分支、未完成操作和改动摘要，输出为空；不满足条件时抛出明确错误。
+ */
+function validateSavePreconditions(currentBranch, operation, changes) {
+  assertOnBranch(currentBranch, 'save', 'SAVE_DETACHED_HEAD')
+  assertNoPendingOperation(operation, 'save', 'SAVE_GIT_OPERATION_IN_PROGRESS')
+  assertNoConflictedFiles(changes, 'save', 'SAVE_CONFLICTED_FILES')
+
+  if (changes.clean) {
+    throw new IcodeError('没有可提交的改动，save 已停止。', {
+      code: 'SAVE_NO_CHANGES',
+      exitCode: 2
+    })
+  }
+}
+
+/**
+ * 构建 dry-run 结果。
+ * 输入为上下文、分支、改动和计划提交信息，输出不会产生副作用的预览结构。
+ */
+function buildDryRunResult(context, currentBranch, changes, commitMessage, source) {
+  return {
+    applied: false,
+    dryRun: true,
+    commitId: '',
+    commitMessage,
+    source,
+    context: {
+      topLevelPath: context.topLevelPath,
+      currentBranch
+    },
+    changes
+  }
+}
+
+/**
+ * 执行安全快速提交。
+ * 输入为 save 参数，输出提交结果；关键假设：dry-run 不执行 add/commit，AI 模式必须使用有效 profile。
+ */
+export async function runSaveWorkflow(options = {}) {
+  validateMessageSource(options)
+
+  const context = await resolveGitContext({
+    cwd: options.cwd,
+    repoMode: options.repoMode
+  })
+  const git = new GitService(context)
+  const { currentBranch, operation, changes } = await readGitSafetyState(git)
+
+  validateSavePreconditions(currentBranch, operation, changes)
+
+  if (options.aiCommit === true) {
+    // AI 模式必须先校验 profile 存在，避免 askAiJson 在缺配置时隐式选择其它配置。
+    getAiProfile(options.profile)
+    const aiResult = await runAiCommitWorkflow({
+      cwd: context.topLevelPath,
+      repoMode: 'strict',
+      profile: options.profile,
+      lang: options.lang || 'zh',
+      apply: options.dryRun !== true,
+      yes: options.yes === true,
+      noVerify: options.noVerify === true,
+      silentContextLog: true,
+      silentResultLog: true
+    })
+
+    if (options.dryRun === true) {
+      return buildDryRunResult(context, currentBranch, changes, aiResult.commitMessage, 'ai')
+    }
+
+    return {
+      applied: aiResult.applied,
+      dryRun: false,
+      commitId: aiResult.commitId || '',
+      commitMessage: aiResult.commitMessage,
+      source: 'ai',
+      context: {
+        topLevelPath: context.topLevelPath,
+        currentBranch
+      },
+      changes
+    }
+  }
+
+  const commitMessage = normalizeMessage(options.message)
+  if (options.dryRun === true) {
+    return buildDryRunResult(context, currentBranch, changes, commitMessage, 'message')
+  }
+
+  await git.stageAll()
+  await git.commit(commitMessage, {
+    noVerify: options.noVerify === true
+  })
+  const commitId = await git.revParseShort('HEAD')
+
+  return {
+    applied: true,
+    dryRun: false,
+    commitId,
+    commitMessage,
+    source: 'message',
+    context: {
+      topLevelPath: context.topLevelPath,
+      currentBranch
+    },
+    changes
+  }
+}

package/src/workflows/sync-workflow.js

@@ -1,8 +1,15 @@
 import { IcodeError } from '../core/errors.js'
-import { resolveGitContext } from '../core/git-context.js'
-import { GitService } from '../core/git-service.js'
-import { logger } from '../core/logger.js'
-import { confirm } from '../core/prompts.js'
+import { resolveGitContext } from '../core/git/context.js'
+import {
+  assertCleanWorktree,
+  assertNoConflictedFiles,
+  assertNoPendingOperation,
+  assertOnBranch,
+  readGitSafetyState
+} from '../core/git/preconditions.js'
+import { GitService } from '../core/git/service.js'
+import { confirm } from '../core/tools/interactive.js'
+import { logger } from '../core/tools/logger.js'
 
 function unique(list) {
   return [...new Set(list.map((item) => item.trim()).filter(Boolean))]
@@ -33,6 +40,10 @@ async function ensureBranchReady(git, branchName) {
   }
 }
 
+/**
+ * 执行 sync 工作流。
+ * 输入为目标分支与同步选项，输出每个分支的同步摘要；实际切换分支前要求当前仓库处于干净状态。
+ */
 export async function runSyncWorkflow(options) {
   const context = await resolveGitContext({
     cwd: options.cwd,
@@ -40,7 +51,12 @@ export async function runSyncWorkflow(options) {
   })
 
   const git = new GitService(context)
-  const currentBranch = (await git.getCurrentBranch()) || context.currentBranch
+  const safetyState = await readGitSafetyState(git)
+  const currentBranch = safetyState.currentBranch || context.currentBranch
+  assertOnBranch(currentBranch, 'sync', 'SYNC_DETACHED_HEAD')
+  assertNoPendingOperation(safetyState.operation, 'sync', 'SYNC_GIT_OPERATION_IN_PROGRESS')
+  assertNoConflictedFiles(safetyState.changes, 'sync', 'SYNC_CONFLICTED_FILES')
+  assertCleanWorktree(safetyState.changes, 'sync', 'SYNC_DIRTY_WORKTREE')
 
   let targetInput = options.branches?.length
     ? [...options.branches]
@@ -99,7 +115,7 @@ export async function runSyncWorkflow(options) {
       if (setup.remoteExists) {
         await git.pull(branchName, {
           noRebase: !options.rebase,
-          allowUnrelatedHistories: true
+          rebase: options.rebase
         })
       }
 

package/src/workflows/tag-workflow.js

@@ -1,8 +1,8 @@
 import { IcodeError } from '../core/errors.js'
-import { GitService } from '../core/git-service.js'
-import { resolveGitContext } from '../core/git-context.js'
-import { logger } from '../core/logger.js'
-import { input } from '../core/prompts.js'
+import { resolveGitContext } from '../core/git/context.js'
+import { GitService } from '../core/git/service.js'
+import { input } from '../core/tools/interactive.js'
+import { logger } from '../core/tools/logger.js'
 
 function todayStamp() {
   const now = new Date()