@icode-js/icode 3.0.4 → 3.2.0

package/src/core/cli/update-notifier.js

@@ -0,0 +1,138 @@
+import { createRequire } from 'node:module'
+import { runCommand } from '../commands/shell.js'
+import { logger } from '../tools/logger.js'
+
+const require = createRequire(import.meta.url)
+const packageJson = require('../../../package.json')
+
+/**
+ * 规范化版本号，输出仅包含数字段的 semver 主体数组。
+ * 输入为字符串版本号，输出为数字数组；若格式不合法则返回 null。
+ */
+function normalizeVersionSegments(version) {
+  const normalized = String(version || '').trim()
+  if (!normalized) {
+    return null
+  }
+
+  const coreVersion = normalized.split('-')[0]
+  if (!/^\d+(?:\.\d+)*$/.test(coreVersion)) {
+    return null
+  }
+
+  return coreVersion.split('.').map((segment) => Number(segment))
+}
+
+/**
+ * 解析 npm view 返回的版本文本，兼容 JSON 字符串与纯文本两种输出。
+ * 输入为命令 stdout，输出为去空白后的版本号字符串。
+ */
+function parsePublishedVersion(stdout) {
+  const normalized = String(stdout || '').trim()
+  if (!normalized) {
+    return ''
+  }
+
+  try {
+    const parsed = JSON.parse(normalized)
+    if (typeof parsed === 'string') {
+      return parsed.trim()
+    }
+  } catch {
+    // npm 在异常场景下也可能输出纯文本版本号，这里保留原始文本继续解析。
+  }
+
+  return normalized.replace(/^"|"$/g, '').trim()
+}
+
+/**
+ * 比较两个版本号，判断远端版本是否严格高于当前版本。
+ * 输入为当前版本和远端版本，输出为布尔值。
+ */
+export function hasNewerVersion(currentVersion, latestVersion) {
+  const currentSegments = normalizeVersionSegments(currentVersion)
+  const latestSegments = normalizeVersionSegments(latestVersion)
+
+  if (!currentSegments || !latestSegments) {
+    return false
+  }
+
+  const maxLength = Math.max(currentSegments.length, latestSegments.length)
+  for (let index = 0; index < maxLength; index += 1) {
+    const currentValue = currentSegments[index] || 0
+    const latestValue = latestSegments[index] || 0
+
+    if (latestValue > currentValue) {
+      return true
+    }
+
+    if (latestValue < currentValue) {
+      return false
+    }
+  }
+
+  return false
+}
+
+/**
+ * 查询 npm registry 上当前包的最新发布版本。
+ * 输入为可选 runner/packageName，输出为最新版本号；失败时返回空字符串。
+ */
+export async function fetchLatestPublishedVersion(options = {}) {
+  const packageName = options.packageName || packageJson.name
+  const runner = options.runner || runCommand
+
+  try {
+    const result = await runner('npm', ['view', packageName, 'version', '--json'], {
+      allowFailure: true,
+      env: {
+        ...process.env,
+        NO_UPDATE_NOTIFIER: '1',
+        npm_config_update_notifier: 'false',
+        npm_config_loglevel: 'silent'
+      }
+    })
+
+    if (result.exitCode !== 0) {
+      return ''
+    }
+
+    return parsePublishedVersion(result.stdout)
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * 在命令成功结束后提示可用更新版本。
+ * 输入为可选 runner/warn/packageName/currentVersion，输出为通知结果对象。
+ */
+export async function notifyIfCliUpdateAvailable(options = {}) {
+  const packageName = options.packageName || packageJson.name
+  const currentVersion = options.currentVersion || packageJson.version
+  const warn = options.warn || logger.warn
+
+  const latestVersion = await fetchLatestPublishedVersion({
+    runner: options.runner,
+    packageName
+  })
+
+  if (!latestVersion || !hasNewerVersion(currentVersion, latestVersion)) {
+    return {
+      notified: false,
+      packageName,
+      currentVersion,
+      latestVersion
+    }
+  }
+
+  warn(`发现新版本可用: ${currentVersion} -> ${latestVersion}`)
+  warn(`更新命令: npm i -g ${packageName}@latest`)
+
+  return {
+    notified: true,
+    packageName,
+    currentVersion,
+    latestVersion
+  }
+}

package/src/core/{shell.js → commands/shell.js}

@@ -1,10 +1,18 @@
 import { spawn } from 'node:child_process'
-import { IcodeError } from './errors.js'
+import { IcodeError } from '../errors.js'
 
+/**
+ * 把命令与参数拼成可读字符串，供日志与报错复用。
+ * 输入为命令名与参数数组，输出为单行命令文本。
+ */
 function stringifyCommand(command, args) {
   return [command, ...args].join(' ')
 }
 
+/**
+ * 组合命令失败消息，尽量附带 stderr/stdout 便于定位问题。
+ * 输入为命令信息与执行结果，输出为最终错误文案。
+ */
 function formatFailureMessage(command, args, result) {
   const baseMessage = `命令执行失败(${result.exitCode}): ${stringifyCommand(command, args)}`
   const detailLines = [result.stderr, result.stdout].map((item) => item.trim()).filter(Boolean)
@@ -16,6 +24,10 @@ function formatFailureMessage(command, args, result) {
   return `${baseMessage}\n${detailLines.join('\n')}`
 }
 
+/**
+ * 执行外部命令并收集 stdout/stderr；允许按需把非零退出码作为普通结果返回。
+ * 输入为命令名、参数数组与执行选项，输出为标准化执行结果。
+ */
 export async function runCommand(command, args = [], options = {}) {
   const { cwd = process.cwd(), env = process.env, allowFailure = false } = options
 

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

@@ -1,7 +1,7 @@
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
-import { IcodeError } from './errors.js'
+import { IcodeError } from '../errors.js'
 
 const DEFAULT_CONFIG = {
   version: 1,
@@ -9,6 +9,12 @@ const DEFAULT_CONFIG = {
     repoMode: 'auto',
     defaultMainBranches: ['main', 'master']
   },
+  platforms: {
+    remoteMerge: {
+      provider: '',
+      apiKey: ''
+    }
+  },
   ai: {
     activeProfile: '',
     profiles: {},
@@ -74,6 +80,14 @@ export function readConfig() {
         ...cloneDefault().defaults,
         ...(parsed.defaults || {})
       },
+      platforms: {
+        ...cloneDefault().platforms,
+        ...(parsed.platforms || {}),
+        remoteMerge: {
+          ...cloneDefault().platforms.remoteMerge,
+          ...(parsed.platforms?.remoteMerge || {})
+        }
+      },
       ai: {
         ...cloneDefault().ai,
         ...(parsed.ai || {}),
@@ -176,8 +190,12 @@ function normalizeRepoKey(repoRootPath) {
 export function getRepoPolicy(repoRootPath) {
   const key = normalizeRepoKey(repoRootPath)
   const config = readConfig()
-  return config.repositories[key] || {
-    protectedBranches: []
+  return {
+    protectedBranches: [],
+    remoteMerge: {
+      enabled: true
+    },
+    ...(config.repositories[key] || {})
   }
 }
 
@@ -186,9 +204,41 @@ export function setRepoPolicy(repoRootPath, policy) {
   const config = readConfig()
   config.repositories[key] = {
     protectedBranches: [],
+    remoteMerge: {
+      enabled: true
+    },
     ...(config.repositories[key] || {}),
     ...policy
   }
   writeConfig(config)
   return config.repositories[key]
 }
+
+export function getPlatformConfig(platformName) {
+  const config = readConfig()
+  const name = String(platformName || '').trim()
+  if (!name) {
+    return {}
+  }
+
+  return config.platforms?.[name] || {}
+}
+
+export function setPlatformConfig(platformName, value) {
+  const config = readConfig()
+  const name = String(platformName || '').trim()
+  if (!name) {
+    throw new IcodeError('平台名称不能为空', { code: 'CONFIG_PLATFORM_EMPTY', exitCode: 2 })
+  }
+
+  config.platforms = {
+    ...(config.platforms || {}),
+    [name]: {
+      ...(config.platforms?.[name] || {}),
+      ...(value || {})
+    }
+  }
+
+  writeConfig(config)
+  return config.platforms[name]
+}

package/src/core/{git-context.js → git/context.js}

@@ -1,8 +1,8 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { readConfig } from './config-store.js'
-import { IcodeError } from './errors.js'
-import { runCommand } from './shell.js'
+import { runCommand } from '../commands/shell.js'
+import { readConfig } from '../config/store.js'
+import { IcodeError } from '../errors.js'
 
 function cleanOutput(text) {
   return (text || '').trim()
@@ -13,6 +13,22 @@ async function commandOutput(cwd, args, allowFailure = false) {
   return result
 }
 
+/**
+ * 确认当前目录属于 Git 仓库。
+ * 输入为工作目录，输出为空；不在仓库中时直接抛错，不隐式初始化仓库。
+ */
+async function ensureGitRepository(cwd) {
+  const inside = await commandOutput(cwd, ['rev-parse', '--is-inside-work-tree'], true)
+  if (inside.exitCode === 0 && cleanOutput(inside.stdout) === 'true') {
+    return
+  }
+
+  throw new IcodeError('当前目录不在 Git 仓库中。请先进入已有仓库，或手动执行 git init。', {
+    code: 'NOT_IN_GIT_REPO',
+    exitCode: 2
+  })
+}
+
 async function detectDefaultBranch(topLevelPath, fallbackCandidates = ['main', 'master']) {
   const headRefResult = await commandOutput(topLevelPath, ['symbolic-ref', 'refs/remotes/origin/HEAD'], true)
   if (headRefResult.exitCode === 0) {
@@ -38,19 +54,17 @@ async function detectDefaultBranch(topLevelPath, fallbackCandidates = ['main', '
   return 'main'
 }
 
+/**
+ * 解析当前 Git 仓库上下文。
+ * 输入为 cwd/repoMode 等选项，输出仓库根路径、git 目录、当前分支和默认分支等稳定上下文。
+ */
 export async function resolveGitContext(options = {}) {
   const cwd = path.resolve(options.cwd || process.cwd())
   const config = readConfig()
   const configRepoMode = config.defaults?.repoMode || 'auto'
   const repoMode = options.repoMode || configRepoMode
 
-  const inside = await commandOutput(cwd, ['rev-parse', '--is-inside-work-tree'], true)
-  if (inside.exitCode !== 0 || cleanOutput(inside.stdout) !== 'true') {
-    throw new IcodeError('当前目录不在 Git 仓库中。', {
-      code: 'NOT_IN_GIT_REPO',
-      exitCode: 2
-    })
-  }
+  await ensureGitRepository(cwd)
 
   const topLevelPath = cleanOutput((await commandOutput(cwd, ['rev-parse', '--show-toplevel'])).stdout)
   const gitDirRaw = cleanOutput((await commandOutput(cwd, ['rev-parse', '--git-dir'])).stdout)

package/src/core/git/preconditions.js

@@ -0,0 +1,88 @@
+import { IcodeError } from '../errors.js'
+
+/**
+ * 读取当前仓库执行状态。
+ * 输入为 GitService 实例，输出当前分支、未完成操作和工作区改动摘要。
+ */
+export async function readGitSafetyState(git) {
+  const [currentBranch, operation, changes] = await Promise.all([
+    git.getCurrentBranch(),
+    git.getInProgressOperation(),
+    git.getStatusSummary()
+  ])
+
+  return {
+    currentBranch,
+    operation,
+    changes
+  }
+}
+
+/**
+ * 断言当前处于普通分支。
+ * 输入为分支名、命令名和错误码，输出为空；不满足时抛出 IcodeError。
+ */
+export function assertOnBranch(currentBranch, commandName, code) {
+  if (currentBranch) {
+    return
+  }
+
+  throw new IcodeError(`当前不在普通分支上，${commandName} 已停止。`, {
+    code,
+    exitCode: 2
+  })
+}
+
+/**
+ * 断言不存在未完成的 Git 操作。
+ * 输入为操作名、命令名和错误码，输出为空；检测到 merge/rebase/cherry-pick/revert 时抛错。
+ */
+export function assertNoPendingOperation(operation, commandName, code) {
+  if (!operation) {
+    return
+  }
+
+  throw new IcodeError(`检测到未完成的 Git 操作: ${operation}。请先完成或中止该操作，${commandName} 已停止。`, {
+    code,
+    exitCode: 2,
+    meta: {
+      operation
+    }
+  })
+}
+
+/**
+ * 断言不存在冲突文件。
+ * 输入为改动摘要、命令名和错误码，输出为空；存在冲突文件时抛错。
+ */
+export function assertNoConflictedFiles(changes, commandName, code) {
+  if (!changes || changes.conflicted === 0) {
+    return
+  }
+
+  throw new IcodeError(`存在 ${changes.conflicted} 个冲突文件，${commandName} 已停止。`, {
+    code,
+    exitCode: 2,
+    meta: {
+      changes
+    }
+  })
+}
+
+/**
+ * 断言工作区干净。
+ * 输入为改动摘要、命令名和错误码，输出为空；存在任何未提交改动时抛错。
+ */
+export function assertCleanWorktree(changes, commandName, code) {
+  if (changes && changes.clean) {
+    return
+  }
+
+  throw new IcodeError(`工作区存在未提交改动，${commandName} 已停止。请先执行 save 或手动清理。`, {
+    code,
+    exitCode: 2,
+    meta: {
+      changes
+    }
+  })
+}

package/src/core/{git-service.js → git/service.js}

@@ -1,14 +1,101 @@
-import { IcodeError } from './errors.js'
-import { buildHookHint, detectHookFailure } from './hook-diagnostics.js'
-import { logger } from './logger.js'
-import { runCommand } from './shell.js'
 import fs from 'node:fs'
 import path from 'node:path'
+import { buildHookHint, detectHookFailure } from './hook-diagnostics.js'
+import { runCommand } from '../commands/shell.js'
+import { IcodeError } from '../errors.js'
+import { logger } from '../tools/logger.js'
 
 function cleanOutput(text) {
   return (text || '').trim()
 }
 
+/**
+ * 解析 porcelain v1 单行状态。
+ * 输入为 `git status --porcelain` 的一行文本，输出为索引区状态、工作区状态和文件路径。
+ * 关键假设：本项目只需要稳定分类改动，不在这里还原 rename 的源路径细节。
+ */
+function parsePorcelainLine(line) {
+  const indexStatus = line.slice(0, 1)
+  const worktreeStatus = line.slice(1, 2)
+  const rawPath = line.slice(3).trim()
+  const separatorIndex = rawPath.indexOf(' -> ')
+  const filePath = separatorIndex === -1 ? rawPath : rawPath.slice(separatorIndex + 4)
+
+  return {
+    raw: line,
+    indexStatus,
+    worktreeStatus,
+    filePath
+  }
+}
+
+/**
+ * 汇总 porcelain 状态行。
+ * 输入为状态行数组，输出为 staged/unstaged/untracked/conflicted 计数和文件明细。
+ * 关键假设：`??` 表示未跟踪文件，`U` 或双边冲突组合表示未解决冲突。
+ */
+function summarizeStatusEntries(entries) {
+  const files = []
+  const summary = {
+    staged: 0,
+    unstaged: 0,
+    untracked: 0,
+    conflicted: 0,
+    files
+  }
+
+  for (const entry of entries) {
+    const isUntracked = entry.indexStatus === '?' && entry.worktreeStatus === '?'
+    const isConflicted = entry.indexStatus === 'U' ||
+      entry.worktreeStatus === 'U' ||
+      (entry.indexStatus === 'A' && entry.worktreeStatus === 'A') ||
+      (entry.indexStatus === 'D' && entry.worktreeStatus === 'D')
+    const hasStaged = !isUntracked && entry.indexStatus !== ' ' && entry.indexStatus !== '?' && !isConflicted
+    const hasUnstaged = !isUntracked && entry.worktreeStatus !== ' ' && entry.worktreeStatus !== '?' && !isConflicted
+
+    if (isUntracked) {
+      summary.untracked += 1
+    }
+    if (isConflicted) {
+      summary.conflicted += 1
+    }
+    if (hasStaged) {
+      summary.staged += 1
+    }
+    if (hasUnstaged) {
+      summary.unstaged += 1
+    }
+
+    files.push({
+      path: entry.filePath,
+      indexStatus: entry.indexStatus,
+      worktreeStatus: entry.worktreeStatus,
+      staged: hasStaged,
+      unstaged: hasUnstaged,
+      untracked: isUntracked,
+      conflicted: isConflicted
+    })
+  }
+
+  return summary
+}
+
+function parseGitLogRecords(output) {
+  return output
+    .split('\x1e')
+    .map((record) => record.trim())
+    .filter(Boolean)
+    .map((record) => {
+      const [hash = '', subject = '', body = ''] = record.split('\x1f')
+      return {
+        hash: hash.trim(),
+        subject: subject.trim(),
+        body: body.trim()
+      }
+    })
+    .filter((item) => item.hash && item.subject)
+}
+
 export class GitService {
   constructor(context) {
     this.context = context
@@ -60,6 +147,10 @@ export class GitService {
       return 'rebase'
     }
 
+    if (this.operationFileExists('MERGE_HEAD')) {
+      return 'merge'
+    }
+
     return null
   }
 
@@ -77,6 +168,13 @@ export class GitService {
     return result.exitCode === 0
   }
 
+  async getRemoteUrl(remoteName = 'origin') {
+    const result = await this.exec(['remote', 'get-url', remoteName], {
+      allowFailure: true
+    })
+    return cleanOutput(result.stdout)
+  }
+
   async listLocalBranches() {
     const result = await this.exec(['for-each-ref', '--format=%(refname:short)', 'refs/heads'])
     return result.stdout
@@ -127,7 +225,9 @@ export class GitService {
   async pull(branchName, options = {}) {
     const args = ['pull', 'origin', branchName]
 
-    if (options.noRebase !== false) {
+    if (options.rebase) {
+      args.push('--rebase')
+    } else if (options.noRebase !== false) {
       args.push('--no-rebase')
     }
 
@@ -153,6 +253,16 @@ export class GitService {
     await this.exec(args)
   }
 
+  // 继续已解决冲突的 merge 操作，供 undo recover 统一恢复合并现场。
+  async mergeContinue() {
+    await this.exec(['merge', '--continue'])
+  }
+
+  // 中止未完成的 merge 操作，保留给显式 recover abort 使用，不自动清理用户现场。
+  async mergeAbort() {
+    await this.exec(['merge', '--abort'], { allowFailure: true })
+  }
+
   async rebase(fromRef) {
     await this.exec(['rebase', fromRef])
   }
@@ -167,12 +277,75 @@ export class GitService {
     return result.stdout
   }
 
+  /**
+   * 读取并解析工作区状态。
+   * 输入为空，输出为结构化改动摘要，供 ready/save 等场景命令复用。
+   */
+  async getStatusSummary() {
+    const output = await this.statusPorcelain()
+    const entries = output
+      .split('\n')
+      .map((line) => line.trimEnd())
+      .filter(Boolean)
+      .map(parsePorcelainLine)
+
+    return {
+      clean: entries.length === 0,
+      total: entries.length,
+      ...summarizeStatusEntries(entries)
+    }
+  }
+
   async hasChanges() {
     // 只要 porcelain 有输出，就说明暂存区、工作区或未跟踪文件存在改动。
     const output = await this.statusPorcelain()
     return cleanOutput(output).length > 0
   }
 
+  /**
+   * 读取当前分支的 upstream ref。
+   * 输入为空，输出为 upstream 短 ref；没有 upstream 时返回空字符串。
+   */
+  async getUpstreamRef() {
+    const result = await this.exec(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], {
+      allowFailure: true
+    })
+
+    if (result.exitCode !== 0) {
+      return ''
+    }
+
+    return cleanOutput(result.stdout)
+  }
+
+  /**
+   * 读取当前 HEAD 与 upstream 的领先/落后数量。
+   * 输入为空，输出 upstream、ahead、behind；没有 upstream 时 explicitly 标记 configured=false。
+   */
+  async getUpstreamStatus() {
+    const upstream = await this.getUpstreamRef()
+    if (!upstream) {
+      return {
+        configured: false,
+        upstream: '',
+        ahead: 0,
+        behind: 0
+      }
+    }
+
+    const result = await this.exec(['rev-list', '--left-right', '--count', `${upstream}...HEAD`])
+    const [behindRaw = '0', aheadRaw = '0'] = cleanOutput(result.stdout).split(/\s+/)
+    const behind = Number.parseInt(behindRaw, 10)
+    const ahead = Number.parseInt(aheadRaw, 10)
+
+    return {
+      configured: true,
+      upstream,
+      ahead: Number.isInteger(ahead) ? ahead : 0,
+      behind: Number.isInteger(behind) ? behind : 0
+    }
+  }
+
   // 列出未被忽略的未跟踪文件，供 AI 工作流补全新文件 diff。
   async listUntrackedFiles() {
     const result = await this.exec(['ls-files', '--others', '--exclude-standard'])
@@ -431,6 +604,23 @@ export class GitService {
       .filter(Boolean)
   }
 
+  // 读取指定 range 内的提交信息，返回按时间顺序排列的 hash/subject/body 列表。
+  async listCommitMessages(rangeSpec) {
+    const result = await this.exec(['log', '--reverse', '--format=%H%x1f%s%x1f%b%x1e', rangeSpec], {
+      allowFailure: true
+    })
+    return parseGitLogRecords(result.stdout)
+  }
+
+  // 读取单个 ref 的最新提交信息，供无法从 range 提取提交时回退使用。
+  async getCommitMessage(ref = 'HEAD') {
+    const result = await this.exec(['log', '-1', '--format=%H%x1f%s%x1f%b%x1e', ref], {
+      allowFailure: true
+    })
+    const commits = parseGitLogRecords(result.stdout)
+    return commits[0] || null
+  }
+
   async cherryPick(commits) {
     const normalized = Array.isArray(commits) ? commits : [commits]
     const list = normalized.map((item) => item.trim()).filter(Boolean)