@dsh-xhl/dsh-git-gui 0.1.3

package/lib/index.js

@@ -0,0 +1,24 @@
+/**
+ * dsh-git-gui — Host plugin entry.
+ *
+ * A zero-dependency dual-face package:
+ * - this file is the Node (host) half, loaded as an ordinary cordis plugin
+ *   row from the profile's `cordis.patch.yml`(bundle 补丁层自动注册);
+ * - `lib/client.js` is the browser half, built by `scripts/build-client.mjs`
+ *   into the `window.__ModuleLoader__.load` CJS shape the web module system
+ *   serves under `/plugins/<package name>/client.js`.
+ *
+ * The host half provides one Typert service (`gitService`, wire namespace
+ * `git`) whose `@Remote` methods become `git/*` endpoints for the browser,
+ * plus an ActivityTracker that attributes agent file mutations to
+ * (session, turn, tool) for the "AI 修改时间线" view.
+ */
+
+import { GitService } from './service.js'
+import { ActivityTracker } from './activity.js'
+
+/** @type {import('@deepseek-ai/cordis').Plugin.Function} */
+export default function gitGuiPlugin(ctx) {
+  const tracker = new ActivityTracker(ctx)
+  new GitService(ctx, tracker)
+}

package/lib/parse.js

@@ -0,0 +1,298 @@
+/**
+ * Pure parsers for git plumbing output (zero dependencies).
+ *
+ * Conventions followed throughout:
+ * - every git invocation uses NUL / custom separators (-z, --format with %x00),
+ *   so paths with spaces, quotes, CJK and newlines parse unambiguously;
+ * - `core.quotepath=false` keeps paths verbatim (UTF-8) on the wire;
+ * - parsers never throw on malformed input: they degrade to empty/partial
+ *   results so one weird repo cannot take the panel down.
+ */
+
+/**
+ * Parse `git status --porcelain=v2 -z --branch` output.
+ *
+ * Records are NUL-separated. v2 record shapes:
+ *   `1 XY sub mH mI mW hH hI path`
+ *   `2 XY sub mH mI mW hH hI Xscore path\0origPath`
+ *   `u XY sub m1 m2 m3 mW h1 h2 h3 path`
+ *   `? path`
+ *   `! path`            (ignored)
+ * Branch headers: `# branch.oid <sha|(initial)>`, `# branch.head <name|(detached)>`,
+ * `# branch.upstream <name>`, `# branch.ab +<a> -<b>`.
+ *
+ * @param {string} raw raw stdout of the status command
+ * @returns {{ branch: { head?: string, oid?: string, upstream?: string, ahead?: number, behind?: number, detached: boolean, noCommits: boolean }, files: Array<{ x: string, y: string, path: string, origPath?: string, sub: string }> }}
+ */
+export function parseStatusPorcelainV2(raw) {
+  const branch = { detached: false, noCommits: false }
+  const files = []
+  const tokens = raw.split('\0')
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i]
+    if (token === '') continue
+    if (token.startsWith('#')) {
+      // header shape: `# branch.oid <value>` — the key is the first two
+      // space-separated segments (`# branch.oid` itself contains a space).
+      const m = /^(#\s+\S+)\s?(.*)$/.exec(token)
+      if (!m) continue
+      const key = m[1]
+      const value = m[2]
+      if (key === '# branch.oid') {
+        branch.oid = value
+        branch.noCommits = value === '(initial)'
+      } else if (key === '# branch.head') {
+        if (value === '(detached)') {
+          branch.detached = true
+        } else {
+          branch.head = value
+        }
+      } else if (key === '# branch.upstream') {
+        branch.upstream = value
+      } else if (key === '# branch.ab') {
+        const ab = /^\+(\d+) -(\d+)$/.exec(value)
+        if (ab) {
+          branch.ahead = Number(ab[1])
+          branch.behind = Number(ab[2])
+        }
+      }
+      continue
+    }
+    if (token.startsWith('? ') || token.startsWith('! ')) {
+      // untracked / ignored: `? <path>` in one NUL-terminated record
+      files.push({ x: token[0], y: token[0], sub: '', path: token.slice(2) })
+      continue
+    }
+    const fields = token.split(' ')
+    const marker = fields[0]
+    // paths may contain spaces: everything after the fixed-width header is the path
+    if (marker === '1' && fields.length >= 9) {
+      files.push({ x: fields[1][0], y: fields[1][1], sub: fields[2], path: fields.slice(8).join(' ') })
+    } else if (marker === '2' && fields.length >= 10) {
+      const path = fields.slice(9).join(' ')
+      const origPath = tokens[++i]
+      files.push({ x: fields[1][0], y: fields[1][1], sub: fields[2], path, origPath })
+    } else if (marker === 'u' && fields.length >= 11) {
+      files.push({ x: fields[1][0], y: fields[1][1], sub: fields[2], path: fields.slice(10).join(' ') })
+    }
+    // anything else: unknown record shape, skip defensively
+  }
+  return { branch, files }
+}
+
+/** Sort status files: staged/unstaged first by path, untracked last. */
+export function sortStatusFiles(files) {
+  const rank = (f) => {
+    if (f.x === '?') return 3
+    if (f.x === 'U' || f.y === 'U') return 2
+    return f.x === '.' ? 1 : 0
+  }
+  return [...files].sort((a, b) => rank(a) - rank(b) || a.path.localeCompare(b.path))
+}
+
+/**
+ * Parse unified git diff output into structured files.
+ *
+ * @param {string} raw diff text
+ * @param {object} [caps]
+ * @param {number} [caps.maxLinesPerFile] safety cap for hunk lines
+ * @returns {{ files: Array<{ oldPath?: string, newPath: string, mode?: string, binary: boolean, newFile: boolean, deleted: boolean, hunks: Array<{ oldStart: number, oldCount: number, newStart: number, newCount: number, lines: Array<{ type: 'ctx'|'add'|'del', text: string, oldLine?: number, newLine?: number, newline: boolean }> }> }>, truncated: boolean }}
+ */
+export function parseUnifiedDiff(raw, caps = {}) {
+  const maxLinesPerFile = caps.maxLinesPerFile ?? 12000
+  const lines = raw.split('\n')
+  const files = []
+  let cur = null
+  let truncated = false
+  let hunk = null
+  let oldLine = 0
+  let newLine = 0
+  let pendingNoNewline = null
+
+  const finishHunk = () => { hunk = null }
+  const finishFile = () => {
+    if (cur && pendingNoNewline && cur.hunks.length > 0) {
+      const last = cur.hunks[cur.hunks.length - 1]
+      if (last.lines.length > 0) last.lines[last.lines.length - 1].newline = false
+    }
+    pendingNoNewline = null
+    cur = null
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (line.startsWith('diff --git ')) {
+      finishFile()
+      cur = { newPath: '', oldPath: undefined, mode: undefined, binary: false, newFile: false, deleted: false, hunks: [] }
+      const m = /^diff --git a\/(.*) b\/(.*)$/.exec(line)
+      if (m) {
+        cur.oldPath = m[1]
+        cur.newPath = m[2]
+      } else {
+        cur.newPath = line.slice('diff --git '.length)
+      }
+      files.push(cur)
+      continue
+    }
+    if (cur === null) {
+      if (line.startsWith('Binary files ')) {
+        // binary diff without a diff --git header (rare); attach to last file if any
+        const last = files[files.length - 1]
+        if (last) last.binary = true
+      }
+      continue
+    }
+    if (line.startsWith('Binary files ') || line.startsWith('GIT binary patch') || line.startsWith('cannot apply binary patch')) {
+      cur.binary = true
+      continue
+    }
+    if (line.startsWith('new file mode ')) {
+      cur.newFile = true
+      cur.mode = line.slice('new file mode '.length)
+      continue
+    }
+    if (line.startsWith('deleted file mode ')) {
+      cur.deleted = true
+      cur.mode = line.slice('deleted file mode '.length)
+      continue
+    }
+    if (line.startsWith('old mode ') || line.startsWith('new mode ')) {
+      continue
+    }
+    if (line.startsWith('--- ') || line.startsWith('+++ ')) {
+      continue
+    }
+    if (line.startsWith('@@')) {
+      finishHunk()
+      const m = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(line)
+      if (m) {
+        hunk = {
+          oldStart: Number(m[1]),
+          oldCount: m[2] === undefined ? 1 : Number(m[2]),
+          newStart: Number(m[3]),
+          newCount: m[4] === undefined ? 1 : Number(m[4]),
+          lines: [],
+        }
+        cur.hunks.push(hunk)
+        oldLine = hunk.oldStart
+        newLine = hunk.newStart
+        if (cur.hunks.length > 400) { truncated = true; break }
+      }
+      continue
+    }
+    if (line === '\') {
+      pendingNoNewline = true
+      if (hunk && hunk.lines.length > 0) {
+        hunk.lines[hunk.lines.length - 1].newline = false
+        pendingNoNewline = null
+      }
+      continue
+    }
+    if (hunk === null) continue
+    if (cur.binary) continue
+    const first = line[0]
+    if (first === ' ') {
+      hunk.lines.push({ type: 'ctx', text: line.slice(1), oldLine: oldLine++, newLine: newLine++, newline: true })
+    } else if (first === '+') {
+      hunk.lines.push({ type: 'add', text: line.slice(1), oldLine: undefined, newLine: newLine++, newline: true })
+    } else if (first === '-') {
+      hunk.lines.push({ type: 'del', text: line.slice(1), oldLine: oldLine++, newLine: undefined, newline: true })
+    }
+    if (hunk.lines.length > maxLinesPerFile) {
+      hunk.lines.push({ type: 'ctx', text: '… (hunk truncated by the Git panel)', newline: true })
+      truncated = true
+      finishHunk()
+    }
+  }
+  finishFile()
+  return { files, truncated }
+}
+
+/**
+ * Parse `git log --pretty=format:%H%x00%P%x00%an%x00%ae%x00%at%x00%s%x00%D%x1e`.
+ * @param {string} raw
+ * @returns {Array<{ hash: string, parents: string[], author: string, email: string, time: number, subject: string, refs: string[] }>}
+ */
+export function parseLog(raw) {
+  if (raw.trim() === '') return []
+  const commits = []
+  for (const record of raw.split('\x1e')) {
+    const fields = record.split('\0')
+    if (fields.length < 7) continue
+    const [hash, parents, author, email, time, subject, refsRaw] = fields
+    if (!hash) continue
+    commits.push({
+      hash,
+      parents: parents === '' ? [] : parents.split(' '),
+      author,
+      email,
+      time: Number(time) || 0,
+      subject: subject || '',
+      refs: (refsRaw || '')
+        .replace(/^\(|\)$/g, '')
+        .split(', ')
+        .map((r) => r.trim())
+        .filter((r) => r !== ''),
+    })
+  }
+  return commits
+}
+
+/**
+ * Parse `git for-each-ref` output with `%00` separators:
+ * `%(refname:short)%00%(objectname:short)%00%(upstream:short)%00%(upstream:track)%00%(HEAD)%00%(subject)`.
+ * @param {string} raw
+ * @returns {Array<{ name: string, short: string, upstream?: string, track?: string, current: boolean, subject?: string }>}
+ */
+export function parseRefs(raw) {
+  const refs = []
+  for (const line of raw.split('\n')) {
+    if (line.trim() === '') continue
+    const f = line.split('\0')
+    if (f.length < 5) continue
+    const name = f[0]
+    if (name === '' || name === 'origin/HEAD' || name.endsWith('/HEAD')) continue
+    refs.push({
+      name,
+      short: f[1],
+      upstream: f[2] === '' ? undefined : f[2],
+      track: f[3] === '' ? undefined : f[3],
+      current: f[4] === '*',
+      subject: f[5],
+    })
+  }
+  return refs
+}
+
+/**
+ * Parse `git stash list` with `--pretty=format:%gd%00%H%00%s` (one stash per line).
+ * @param {string} raw
+ * @returns {Array<{ ref: string, hash: string, subject: string }>}
+ */
+export function parseStashList(raw) {
+  if (raw.trim() === '') return []
+  const list = []
+  for (const line of raw.split('\n')) {
+    const f = line.split('\0')
+    if (f.length < 3) continue
+    list.push({ ref: f[0], hash: f[1], subject: f[2] })
+  }
+  return list
+}
+
+/**
+ * Parse `git remote -v` output into a unique remote list.
+ * @param {string} raw
+ * @returns {Array<{ name: string, fetch?: string, push?: string }>}
+ */
+export function parseRemotes(raw) {
+  const map = new Map()
+  for (const line of raw.split('\n')) {
+    const m = /^(\S+)\s+(\S+)\s+\((fetch|push)\)$/.exec(line.trim())
+    if (!m) continue
+    if (!map.has(m[1])) map.set(m[1], { name: m[1] })
+    const entry = map.get(m[1])
+    entry[m[3]] = m[2]
+  }
+  return [...map.values()]
+}

package/lib/runner.js

@@ -0,0 +1,294 @@
+/**
+ * Git process runner (zero dependencies).
+ *
+ * - spawns `git` with explicit argv (never a shell), `-C <cwd>` anchoring;
+ * - collects stdout/stderr with a byte cap (tail kept) so a runaway diff or
+ *   log cannot exhaust host memory;
+ * - serializes mutating commands per workspace (git's own index.lock is the
+ *   final arbiter, but the queue keeps UI state coherent);
+ * - classifies common failures into stable error codes for the client.
+ */
+
+import { spawn } from 'node:child_process'
+import path from 'node:path'
+
+export const GIT_ERROR_CODES = {
+  NOT_REPO: 'NOT_REPO',
+  NO_COMMITS: 'NO_COMMITS',
+  LOCKED: 'LOCKED',
+  UNMERGED: 'UNMERGED',
+  CONFLICT: 'CONFLICT',
+  HOOK_FAILED: 'HOOK_FAILED',
+  IDENTITY: 'IDENTITY',
+  AUTH: 'AUTH',
+  NETWORK: 'NETWORK',
+  NO_UPSTREAM: 'NO_UPSTREAM',
+  REMOTE_EXISTS: 'REMOTE_EXISTS',
+  NOT_FOUND: 'NOT_FOUND',
+  CANCELLED: 'CANCELLED',
+  TIMEOUT: 'TIMEOUT',
+  GIT: 'GIT',
+}
+
+export class GitError extends Error {
+  /**
+   * @param {string} code one of GIT_ERROR_CODES
+   * @param {string} message human readable
+   * @param {string} [detail] raw stderr tail for diagnostics
+   */
+  constructor(code, message, detail) {
+    super(message)
+    this.name = 'GitError'
+    this.code = code
+    this.detail = detail
+  }
+}
+
+const MAX_STREAM_BYTES = 4 * 1024 * 1024
+const TRUNCATION_MARKER = '\n\u2026 [output truncated by the Git panel]'
+const READ_ONLY_COMMANDS = new Set([
+  'status', 'diff', 'log', 'for-each-ref', 'show', 'rev-parse', 'config',
+  'remote', 'stash', 'var', 'version', 'rev-list', 'ls-files', 'branch',
+])
+
+/** Per-workspace FIFO queue for mutating commands. */
+const queues = new Map()
+
+/**
+ * Run one git command.
+ *
+ * @param {object} ctx cordis context (unused beyond logging, kept for the seam)
+ * @param {string} cwd workspace root (git resolves the real repo root itself)
+ * @param {string[]} args argv after `git` (first element = git subcommand)
+ * @param {object} [opts]
+ * @param {boolean} [opts.mutating] serialized per workspace when true
+ * @param {string} [opts.input] stdin text (e.g. commit message)
+ * @param {number} [opts.timeoutMs] deadline; default 30s
+ * @param {AbortSignal} [opts.signal] caller cancellation
+ * @param {string} [opts.gitPath] explicit git executable (settings override)
+ * @returns {Promise<{ stdout: string, stderr: string, exitCode: number, stdoutTruncated: boolean, stderrTruncated: boolean }>}
+ */
+export async function runGit(ctx, cwd, args, opts = {}) {
+  const mutating = opts.mutating === true
+  const run = () => executeGit(ctx, cwd, args, opts)
+  if (!mutating) return run()
+  const key = queueKey(cwd)
+  const prev = queues.get(key) ?? Promise.resolve()
+  const next = prev.then(run, run)
+  queues.set(key, next.catch(() => {}))
+  try {
+    return await next
+  } finally {
+    if (queues.get(key) === next) queues.delete(key)
+  }
+}
+
+function queueKey(cwd) {
+  return path.resolve(cwd).toLowerCase()
+}
+
+async function executeGit(ctx, cwd, args, opts) {
+  const gitPath = opts.gitPath && opts.gitPath.trim() !== '' ? opts.gitPath : 'git'
+  const argv = ['-C', path.resolve(cwd), ...args]
+  const timeoutMs = opts.timeoutMs ?? 30_000
+  const isRead = READ_ONLY_COMMANDS.has(args[0] ?? '')
+  const env = {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0',
+    LANG: 'en_US.UTF-8',
+    LC_ALL: 'en_US.UTF-8',
+    ...(isRead ? { GIT_OPTIONAL_LOCKS: '0' } : {}),
+    // 网络操作(ssh/https)禁交互:新主机密钥自动接受(BatchMode 下仅接受新密钥,
+    // 已知密钥变化仍会拒绝),口令/口令短语提示则直接失败而不是挂起。
+    ...(opts.remote === true ? { GIT_SSH_COMMAND: 'ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new' } : {}),
+  }
+
+  return await new Promise((resolve, reject) => {
+    let settled = false
+    const stdoutChunks = []
+    const stderrChunks = []
+    let stdoutBytes = 0
+    let stderrBytes = 0
+    let stdoutTruncated = false
+    let stderrTruncated = false
+    let timedOut = false
+
+    let child
+    try {
+      child = spawn(gitPath, argv, {
+        cwd: path.resolve(cwd),
+        env,
+        windowsHide: true,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      })
+    } catch (error) {
+      reject(new GitError(GIT_ERROR_CODES.GIT, `failed to start git: ${String(error.message ?? error)}`))
+      return
+    }
+
+    const timer = setTimeout(() => {
+      timedOut = true
+      killTree(child)
+    }, timeoutMs)
+    if (timer.unref) timer.unref()
+
+    const onAbort = () => killTree(child)
+    if (opts.signal) {
+      if (opts.signal.aborted) onAbort()
+      else opts.signal.addEventListener('abort', onAbort, { once: true })
+    }
+
+    child.on('error', (error) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      if (opts.signal) opts.signal.removeEventListener('abort', onAbort)
+      const message = /ENOENT/.test(String(error.code)) && gitPath === 'git'
+        ? 'git executable not found on PATH'
+        : `failed to start git: ${String(error.message ?? error)}`
+      reject(new GitError(GIT_ERROR_CODES.GIT, message))
+    })
+
+    child.stdout.on('data', (chunk) => {
+      const keep = Math.min(chunk.length, MAX_STREAM_BYTES - stdoutBytes)
+      if (keep > 0) stdoutChunks.push(chunk.subarray(0, keep))
+      stdoutBytes += chunk.length
+      if (stdoutBytes > MAX_STREAM_BYTES) stdoutTruncated = true
+    })
+    child.stderr.on('data', (chunk) => {
+      const keep = Math.min(chunk.length, MAX_STREAM_BYTES - stderrBytes)
+      if (keep > 0) stderrChunks.push(chunk.subarray(0, keep))
+      stderrBytes += chunk.length
+      if (stderrBytes > MAX_STREAM_BYTES) stderrTruncated = true
+    })
+
+    child.on('close', (code, signal) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      if (opts.signal) opts.signal.removeEventListener('abort', onAbort)
+      const stdout = Buffer.concat(stdoutChunks).toString('utf8')
+      const stderr = Buffer.concat(stderrChunks).toString('utf8')
+      if (timedOut) {
+        reject(new GitError(GIT_ERROR_CODES.TIMEOUT, `git ${args[0]} timed out after ${Math.round(timeoutMs / 1000)}s`, stderr))
+        return
+      }
+      if (opts.signal?.aborted) {
+        reject(new GitError(GIT_ERROR_CODES.CANCELLED, 'cancelled'))
+        return
+      }
+      resolve({
+        stdout: stdoutTruncated ? stdout + TRUNCATION_MARKER : stdout,
+        stderr: stderrTruncated ? stderr + TRUNCATION_MARKER : stderr,
+        exitCode: code ?? (signal === null ? 0 : 128),
+        stdoutTruncated,
+        stderrTruncated,
+      })
+    })
+
+    if (opts.input !== undefined && opts.input !== null) {
+      child.stdin.on('error', () => {})
+      child.stdin.end(opts.input, 'utf8')
+    } else {
+      child.stdin.end()
+    }
+  })
+}
+
+function killTree(child) {
+  try {
+    if (child && child.pid !== undefined && child.exitCode === null) {
+      child.kill('SIGTERM')
+      const force = setTimeout(() => {
+        try {
+          if (child.exitCode === null) child.kill('SIGKILL')
+        } catch { /* already gone */ }
+      }, 1500)
+      if (force.unref) force.unref()
+    }
+  } catch { /* already gone */ }
+}
+
+/**
+ * Classify a failed git exit into a stable code + message.
+ * @param {string} stderr
+ * @param {string} subcommand
+ * @returns {{ code: string, message: string } | null} null when unknown
+ */
+export function classifyGitFailure(stderr, subcommand) {
+  const s = stderr ?? ''
+  const hay = s.toLowerCase()
+  if (/not a git repository|does not appear to be a git repository|outside repository/.test(hay)) {
+    return { code: GIT_ERROR_CODES.NOT_REPO, message: '当前目录不是 Git 仓库 (not a git repository)' }
+  }
+  if (/unable to create .*index\.lock|another git process seems to be running/.test(hay)) {
+    return { code: GIT_ERROR_CODES.LOCKED, message: 'Git 索引被锁定:另一个 Git 进程正在运行 (index.lock)' }
+  }
+  if (/your local changes to the following files would be overwritten|untracked working tree files would be overwritten/.test(hay)) {
+    return { code: GIT_ERROR_CODES.UNMERGED, message: '切换被阻止:本地改动会被覆盖,请先提交或暂存 (checkout conflict)' }
+  }
+  if (/automatic merge failed|fix conflicts|unmerged paths|merge conflict|conflict \(content\)|conflict \(modify\/delete\)|conflict \(rename\/delete\)|conflict \(add\/add\)/.test(hay)) {
+    return { code: GIT_ERROR_CODES.CONFLICT, message: '合并冲突:请解决冲突后提交 (merge conflict)' }
+  }
+  if (/please tell me who you are|user\.name|user\.email|empty ident name/.test(hay)) {
+    return { code: GIT_ERROR_CODES.IDENTITY, message: '未配置 Git 身份 (user.name / user.email)' }
+  }
+  if (/authentication failed|could not read username|could not read password|permission denied \(publickey\)|terminal prompts disabled|credentials/.test(hay)) {
+    return { code: GIT_ERROR_CODES.AUTH, message: '认证失败:请配置凭据助手或 SSH key (authentication failed)' }
+  }
+  if (/host key verification failed|could not resolve host|connection timed out|connection refused|network is unreachable|failed to connect|operation timed out/.test(hay)) {
+    return { code: GIT_ERROR_CODES.NETWORK, message: '网络/SSH 连接失败:请检查网络与远程地址 (network error)' }
+  }
+  if (/no upstream branch|has no upstream|no tracking information/.test(hay)) {
+    return { code: GIT_ERROR_CODES.NO_UPSTREAM, message: '当前分支还没有关联远程分支,请先 Push 一次建立关联' }
+  }
+  if (/remote .* already exists/.test(hay)) {
+    return { code: GIT_ERROR_CODES.REMOTE_EXISTS, message: '同名远程仓库已存在' }
+  }
+  if (/hook declined|pre-commit hook exited|error: cannot run .* hook/.test(hay)) {
+    return { code: GIT_ERROR_CODES.HOOK_FAILED, message: 'Git 钩子 (hook) 拒绝或失败' }
+  }
+  if (/does not have any commits yet|ambiguous argument 'head|bad revision 'head/.test(hay)) {
+    return { code: GIT_ERROR_CODES.NO_COMMITS, message: '仓库还没有任何提交 (no commits yet)' }
+  }
+  if (/unknown revision or path not in the working tree|pathspec .* did not match/.test(hay)) {
+    return { code: GIT_ERROR_CODES.NOT_FOUND, message: '目标不存在于工作区 (path not found)' }
+  }
+  return null
+}
+
+/**
+ * Convenience: run a read command and return parsed output or throw GitError.
+ * @returns {Promise<{ stdout: string, stderr: string }>}
+ */
+export async function gitRead(ctx, cwd, args, opts = {}) {
+  const result = await runGit(ctx, cwd, args, { ...opts, mutating: false })
+  if (result.exitCode !== 0) {
+    const combined = `${result.stdout}\n${result.stderr}`
+    const classified = classifyGitFailure(combined, args[0])
+    throw new GitError(
+      classified?.code ?? GIT_ERROR_CODES.GIT,
+      classified?.message ?? `git ${args[0]} failed`,
+      combined.trim(),
+    )
+  }
+  return result
+}
+
+/**
+ * Convenience: run a mutating command (queued per workspace) or throw GitError.
+ * @returns {Promise<{ stdout: string, stderr: string }>}
+ */
+export async function gitWrite(ctx, cwd, args, opts = {}) {
+  const result = await runGit(ctx, cwd, args, { ...opts, mutating: true })
+  if (result.exitCode !== 0) {
+    const combined = `${result.stdout}\n${result.stderr}`
+    const classified = classifyGitFailure(combined, args[0])
+    throw new GitError(
+      classified?.code ?? GIT_ERROR_CODES.GIT,
+      classified?.message ?? `git ${args[0]} failed`,
+      combined.trim(),
+    )
+  }
+  return result
+}