dsh-gitbar-lite 0.0.0-stage → 0.1.1

package/lib/host/diff.js

@@ -0,0 +1,216 @@
+/**
+ * Diff text assembly.
+ *
+ * Everything here is pure: strings and Buffers in, strings out. That matters
+ * because the archived copy in the trash is the *only* record of a discarded
+ * change — `git restore` has already thrown the change away by the time anyone
+ * reads it — so the assembly has to be verifiable without a repository, and
+ * `test/diff.test.mjs` pins it line by line.
+ *
+ * Two jobs:
+ *
+ *   1. `synthesizeNewFileDiff` fills the one hole `git diff HEAD` leaves.
+ *      Untracked paths are invisible to a diff against HEAD (they are not in
+ *      HEAD and not in the index), yet discarding one deletes it, so without a
+ *      synthesized diff the trash entry would say "one file, no content".
+ *
+ *   2. `limitDiff` caps what gets archived. A discarding user is having a bad
+ *      day already; a 200 MB generated file must not turn into a 200 MB JSON
+ *      write that then fails. The cap cuts on a *line* boundary, never
+ *      mid-character, and records how many lines it dropped.
+ *
+ * @module dsh-gitbar-lite/host/diff
+ */
+
+/** Bytes scanned when deciding whether a file is binary. */
+const SNIFF_BYTES = 8000
+
+/**
+ * Whether a file should be treated as binary, using git's own heuristic: a NUL
+ * byte within the first 8000 bytes.
+ *
+ * @param {Buffer | Uint8Array} bytes
+ */
+export function looksBinary(bytes) {
+  const end = Math.min(bytes.length, SNIFF_BYTES)
+  for (let index = 0; index < end; index += 1) {
+    if (bytes[index] === 0) return true
+  }
+  return false
+}
+
+/** The `100644`/`100755` git mode text for a `fs.Stats`-like object. */
+export function modeTextFor(stats) {
+  const mode = typeof stats?.mode === 'number' ? stats.mode : 0
+  return (mode & 0o111) !== 0 ? '100755' : '100644'
+}
+
+/**
+ * A unified diff for a file git does not track, shaped like the one git would
+ * have produced.
+ *
+ * Trailing `\r` is stripped from each line, matching what git shows for a
+ * repository with `text=auto` (this machine's global config has
+ * `core.autocrlf=true`, so a CRLF worktree file would otherwise diff
+ * differently from every tracked file next to it).
+ *
+ * @param {object} input
+ * @param {string} input.path repository-relative path
+ * @param {string} input.content decoded file content (ignored when binary)
+ * @param {boolean} [input.binary]
+ * @param {string} [input.mode] git mode text, from `modeTextFor`
+ * @returns {string}
+ */
+export function synthesizeNewFileDiff({ path, content, binary = false, mode = '100644' }) {
+  const header = [`diff --git a/${path} b/${path}`, `new file mode ${mode}`]
+  if (binary) return `${[...header, `Binary files /dev/null and b/${path} differ`].join('\n')}\n`
+
+  const body = ['--- /dev/null', `+++ b/${path}`]
+  if (content === '') return `${[...header, ...body].join('\n')}\n`
+
+  const endsWithNewline = content.endsWith('\n')
+  const lines = content.split('\n')
+  if (endsWithNewline) lines.pop()
+  const textLines = lines.map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line))
+
+  const hunks = [`@@ -0,0 +1,${textLines.length} @@`, ...textLines.map((line) => `+${line}`)]
+  if (!endsWithNewline) hunks.push('\')
+  return `${[...header, ...body, ...hunks].join('\n')}\n`
+}
+
+/**
+ * Cap a diff on a line boundary.
+ *
+ * @param {string} text
+ * @param {number} maxBytes ceiling for the returned text, in UTF-8 bytes
+ * @returns {{ text: string, truncated: boolean, droppedLines: number }}
+ */
+export function limitDiff(text, maxBytes) {
+  if (!Number.isFinite(maxBytes) || maxBytes <= 0) return { text, truncated: false, droppedLines: 0 }
+  if (Buffer.byteLength(text, 'utf8') <= maxBytes) return { text, truncated: false, droppedLines: 0 }
+
+  const lines = text.split('\n')
+  const kept = []
+  let used = 0
+  for (const line of lines) {
+    const cost = Buffer.byteLength(line, 'utf8') + 1
+    if (used + cost > maxBytes) break
+    kept.push(line)
+    used += cost
+  }
+
+  const dropped = lines.length - kept.length
+  const marker = `[dsh-gitbar-lite] diff truncated: ${dropped} more lines, ${Buffer.byteLength(text, 'utf8') - used} more bytes\n`
+  return { text: `${kept.join('\n')}\n${marker}`, truncated: true, droppedLines: dropped }
+}
+
+/**
+ * The path each block of a multi-file diff belongs to, for the reader's table
+ * of contents.
+ *
+ * `diff --git a/x b/y` is genuinely ambiguous when a path contains a space, so
+ * the more specific lines are preferred, in the order git emits them:
+ * `rename to` first, then the `+++`/`---` pair, then the header as a fallback.
+ *
+ * @param {string} text a full (possibly multi-file) diff
+ * @returns {{ path: string, text: string }[]}
+ */
+export function splitDiffByFile(text) {
+  if (text === '') return []
+
+  const lines = text.split('\n')
+  const starts = []
+  for (let index = 0; index < lines.length; index += 1) {
+    if (lines[index].startsWith('diff --git ')) starts.push(index)
+  }
+  if (starts.length === 0) return []
+
+  const blocks = []
+  for (let index = 0; index < starts.length; index += 1) {
+    const from = starts[index]
+    const to = index + 1 < starts.length ? starts[index + 1] : lines.length
+    const block = lines.slice(from, to)
+    blocks.push({ path: pathOfBlock(block), text: block.join('\n') })
+  }
+  return blocks
+}
+
+/** Recover the new path from one `diff --git` block. */
+function pathOfBlock(block) {
+  for (const line of block) {
+    if (line.startsWith('rename to ')) return line.slice('rename to '.length).trim()
+  }
+  for (const line of block) {
+    if (line.startsWith('+++ ')) {
+      const value = line.slice(4)
+      if (value === '/dev/null') continue
+      const path = value.startsWith('b/') ? value.slice(2) : value
+      const tab = path.indexOf('\t')
+      return (tab < 0 ? path : path.slice(0, tab)).trim()
+    }
+  }
+  for (const line of block) {
+    if (line.startsWith('--- ')) {
+      const value = line.slice(4)
+      if (value === '/dev/null') continue
+      const path = value.startsWith('a/') ? value.slice(2) : value
+      const tab = path.indexOf('\t')
+      return (tab < 0 ? path : path.slice(0, tab)).trim()
+    }
+  }
+  const header = block.find((line) => line.startsWith('diff --git '))
+  if (header === undefined) return ''
+  // Last resort: `diff --git a/x b/y` with no quoting (we always run with
+  // quotepath=false, so a path with spaces simply makes this ambiguous).
+  const body = header.slice('diff --git '.length)
+  const halves = body.split(' ')
+  const right = halves.length >= 2 ? halves[halves.length - 1] : body
+  return right.startsWith('b/') ? right.slice(2) : right
+}
+
+/**
+ * Join per-path diffs into the single blob a "discard all changes" entry
+ * archives, and report the per-file stats.
+ *
+ * @param {{ path: string, text: string }[]} parts
+ * @returns {string}
+ */
+export function joinDiffParts(parts) {
+  return parts.map((part) => (part.text.endsWith('\n') ? part.text : `${part.text}\n`)).join('')
+}
+
+/**
+ * Count the `+`/`-` lines one diff block contributes, mirroring what
+ * `--numstat` reports (so the UI's numbers match whether they came from git or
+ * from a synthesized untracked diff).
+ *
+ * @param {string} text
+ * @returns {{ added: number, deleted: number }}
+ */
+export function diffTotals(text) {
+  let added = 0
+  let deleted = 0
+  let inHunk = false
+  for (const line of text.split('\n')) {
+    if (line.startsWith('@@')) {
+      inHunk = true
+      continue
+    }
+    if (!inHunk) continue
+    if (line.startsWith('diff --git ')) {
+      inHunk = false
+      continue
+    }
+    if (line.startsWith('+')) added += 1
+    else if (line.startsWith('-')) deleted += 1
+  }
+  return { added, deleted }
+}
+
+/** Number of lines a brand-new file contributes (its `+` count). */
+export function countContentLines(content) {
+  if (content === '') return 0
+  const endsWithNewline = content.endsWith('\n')
+  const count = content.split('\n').length - (endsWithNewline ? 1 : 0)
+  return count
+}

package/lib/host/git.js

@@ -0,0 +1,211 @@
+/**
+ * Git process layer.
+ *
+ * Everything this plugin knows about a repository comes through here, and every
+ * command goes through `ctx.subprocess` rather than `node:child_process`:
+ *
+ *   - the harness resolves the executable for us (`resolveExecutable` checks an
+ *     absolute path exists, walks the scrubbed PATH for a bare name, and
+ *     rejects a relative path with separators);
+ *   - the child is contained (a Windows Job object here), gets a bounded output
+ *     buffer with spill, and is killed through `graceMs` rather than leaking;
+ *   - the environment is scrubbed of `*TOKEN*`/`*SECRET*`-shaped variables
+ *     before we even add ours.
+ *
+ * The environment we add on top is the one `@deepseek-ai/dsh-workspace-changes`
+ * uses for the same job: no terminal prompt (a credential prompt would hang a
+ * headless child forever), no optional index locks, no user config in the way,
+ * and a stable locale so the output we parse is the output we expect.
+ *
+ * Note the documented boundary: the harness file sandbox wraps the *shell*
+ * executors (pwsh/bash), not this service. A git child therefore runs with the
+ * OS user's full rights. That is why every path this plugin passes to git is
+ * derived from a repository root the host itself resolved, never from a raw
+ * client string.
+ *
+ * @module dsh-gitbar-lite/host/git
+ */
+
+import { ERROR_CODES, GIT_ENV } from '../shared.js'
+
+/** Milliseconds a git child gets to exit after termination starts. */
+const TERMINATE_GRACE_MS = 2000
+
+/** Retained stderr tail for diagnostics. */
+const STDERR_TAIL_BYTES = 16 * 1024
+
+/** Default stdout ceiling for one command; diffs go through a larger cap. */
+export const DEFAULT_MAX_OUTPUT_BYTES = 8 * 1024 * 1024
+
+/** `git rev-parse` exits 128 when the directory is not inside a repository. */
+export const NOT_A_REPOSITORY_EXIT = 128
+
+/** The one stderr signature that means "not a repository" rather than "broken". */
+const NOT_A_REPOSITORY = /not a git repository/i
+
+/**
+ * A git command that ran and failed, carrying the command and its output.
+ *
+ * Kept distinct from a spawn/timeout failure so callers can classify the
+ * message (a conflict, a rejected push, a missing credential) without
+ * re-parsing a generic error string.
+ */
+export class GitFailure extends Error {
+  /**
+   * @param {string} command the human-readable command, e.g. `git commit`
+   * @param {{ exitCode: number | null, stdout: string, stderr: string }} result
+   */
+  constructor(command, result) {
+    const detail = String(result.stderr ?? '').trim() || String(result.stdout ?? '').trim()
+    super(detail === '' ? `${command} failed (exit ${result.exitCode})` : `${command} failed: ${detail}`)
+    this.name = 'GitFailure'
+    this.command = command
+    this.exitCode = result.exitCode
+    this.stdout = result.stdout
+    this.stderr = result.stderr
+  }
+}
+
+/**
+ * Build the git runner for one plugin instance.
+ *
+ * @param {object} ctx host context (must have `subprocess` injected)
+ * @param {object} config resolved plugin config
+ */
+export function createGit(ctx, config) {
+  /** Resolved once per plugin instance: the executable cannot change under us. */
+  let resolved
+
+  /**
+   * Resolve the git executable, honouring an explicit `gitPath` override.
+   *
+   * A failure here is tagged with `E_NO_GIT` so the route layer reports "git is
+   * not installed (or the configured path is wrong)" rather than a generic
+   * internal error the user cannot act on.
+   *
+   * @returns {Promise<string>} absolute path to the executable
+   */
+  async function executable(signal) {
+    if (resolved !== undefined) return resolved
+    const configured = typeof config.gitPath === 'string' ? config.gitPath.trim() : ''
+    const name = configured === '' ? 'git' : configured
+    try {
+      resolved = await ctx.subprocess.resolveExecutable(name, undefined, signal)
+    } catch (error) {
+      const wrapped = new Error(
+        configured === ''
+          ? `找不到 git 可执行文件：${String(error?.message ?? error)}`
+          : `配置的 git 路径不可用（${configured}）：${String(error?.message ?? error)}`,
+      )
+      wrapped.code = ERROR_CODES.NO_GIT
+      throw wrapped
+    }
+    return resolved
+  }
+
+  /**
+   * Run one git command.
+   *
+   * Never throws for a non-zero exit code — that is data, and callers use `ok()`
+   * when they want it to be an error. Throws only when the child could not be
+   * started, or when the timeout/abort fired.
+   *
+   * @param {readonly string[]} args arguments after the executable
+   * @param {object} [options]
+   * @param {string} [options.cwd] working directory (must be an absolute path)
+   * @param {AbortSignal} [options.signal] caller's cancellation
+   * @param {string} [options.stdin] text written to the child's stdin
+   * @param {number} [options.maxBytes] stdout ceiling for this command
+   * @returns {Promise<{ exitCode: number | null, stdout: string, stderr: string, truncated: boolean }>}
+   */
+  async function run(args, options = {}) {
+    const executablePath = await executable(options.signal)
+    const timeoutMs = Number.isFinite(config.timeoutMs) ? config.timeoutMs : 30000
+    // A zero/negative timeout means "no deadline of our own": still pass the
+    // caller's signal so an aborted request does not leave a child running.
+    const timeout = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined
+    const signal =
+      timeout === undefined
+        ? options.signal
+        : options.signal === undefined
+          ? timeout
+          : AbortSignal.any([options.signal, timeout])
+
+    const handle = ctx.subprocess.spawn({
+      argv: [executablePath, ...args],
+      cwd: options.cwd,
+      stdio: {
+        stdin: options.stdin === undefined ? 'ignore' : { data: options.stdin },
+        stdout: { maxBytes: options.maxBytes ?? DEFAULT_MAX_OUTPUT_BYTES },
+        stderr: { maxBytes: STDERR_TAIL_BYTES },
+      },
+      graceMs: TERMINATE_GRACE_MS,
+      ...(signal === undefined ? {} : { signal }),
+      env: { ...GIT_ENV, ...(options.env ?? {}) },
+    })
+
+    const outcome = await handle.done
+
+    if (signal !== undefined && signal.aborted) {
+      const why = timeout !== undefined && timeout.aborted ? `timed out after ${timeoutMs}ms` : 'was aborted'
+      throw new GitFailure(`git ${args[0] ?? ''}`.trim(), { exitCode: null, stdout: '', stderr: why })
+    }
+
+    const out = handle.collected.stdout?.readFrom(0) ?? { text: '', lossy: false }
+    const err = handle.collected.stderr?.readFrom(0) ?? { text: '', lossy: false }
+    return { exitCode: outcome.exitCode, stdout: out.text, stderr: err.text, truncated: out.lossy === true }
+  }
+
+  /**
+   * Run a git command and treat a non-zero exit as a failure.
+   *
+   * @param {readonly string[]} args
+   * @param {object} [options] same as `run`
+   * @returns {Promise<{ exitCode: number, stdout: string, stderr: string, truncated: boolean }>}
+   */
+  async function must(args, options = {}) {
+    const result = await run(args, options)
+    if (result.exitCode !== 0) throw new GitFailure(`git ${args.join(' ')}`, result)
+    return result
+  }
+
+  /**
+   * The repository root containing `cwd`, or `undefined` when there is none.
+   *
+   * The "not a repository" case is identified the way the shipped
+   * `workspace-changes` plugin identifies it — exit 128 plus that exact stderr
+   * — so a genuinely broken repository still surfaces as an error instead of
+   * being reported as "no repository here".
+   *
+   * @param {string} cwd absolute directory to probe
+   * @param {AbortSignal} [signal]
+   * @returns {Promise<string | undefined>}
+   */
+  async function repoRootOf(cwd, signal) {
+    const result = await run(['rev-parse', '--show-toplevel'], { cwd, signal })
+    if (result.exitCode === NOT_A_REPOSITORY_EXIT && NOT_A_REPOSITORY.test(result.stderr)) return undefined
+    if (result.exitCode !== 0) throw new GitFailure('git rev-parse --show-toplevel', result)
+    const first = result.stdout.split('\n')[0]
+    const root = typeof first === 'string' ? first.trim() : ''
+    return root === '' ? undefined : root
+  }
+
+  /**
+   * `true` when `candidate` is the root of a real working tree.
+   *
+   * Used to validate a user-chosen directory before it is persisted, so a bad
+   * pick fails here with a message instead of poisoning the binding file.
+   *
+   * @param {string} candidate absolute path
+   * @param {AbortSignal} [signal]
+   */
+  async function isRepoRoot(candidate, signal) {
+    const result = await run(['rev-parse', '--show-toplevel', '--is-inside-work-tree'], { cwd: candidate, signal })
+    if (result.exitCode !== 0) return undefined
+    const [toplevel, inside] = result.stdout.split('\n').map((line) => line.trim())
+    if (inside !== 'true' || typeof toplevel !== 'string' || toplevel === '') return undefined
+    return toplevel
+  }
+
+  return { executable, run, must, repoRootOf, isRepoRoot }
+}

package/lib/host/parse.js

@@ -0,0 +1,267 @@
+/**
+ * Parsers for the two git outputs this plugin reads.
+ *
+ * Both are pure: no `ctx`, no filesystem, no clock. That is deliberate — the
+ * status parser is the single place where a wrong assumption turns into a
+ * plausible-looking but wrong file list, and `test/status.test.mjs` pins it
+ * against bytes captured from real repositories (including a rename, a staged
+ * delete, an intent-to-add, a non-ASCII path, and a conflicted index).
+ *
+ * Format reference (all read from `git status --porcelain=v2 --branch -z` with
+ * `core.quotepath=false`):
+ *
+ *   # branch.oid <oid>|(initial)
+ *   # branch.head <name>|(detached)
+ *   # branch.upstream <name>            (only when an upstream is configured)
+ *   # branch.ab +<ahead> -<behind>      (only when an upstream is configured)
+ *   1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>
+ *   2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path>\0<origPath>
+ *   u <XY> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>
+ *   ? <path>
+ *   ! <path>
+ *
+ * With `-z` every record is NUL-terminated and paths are raw bytes, never
+ * quoted — which is why the parsers split on NUL and then count *fields* from
+ * the left instead of splitting on spaces: a path may contain spaces, and with
+ * `-z` git gives us no quoting to lean on.
+ *
+ * @module dsh-gitbar-lite/host/parse
+ */
+
+import { FILE_STATUS } from '../shared.js'
+
+/** Split a `-z` stream into records, dropping the trailing empty field. */
+function splitNul(raw) {
+  const text = typeof raw === 'string' ? raw : ''
+  if (text === '') return []
+  const fields = text.split('\0')
+  if (fields.length > 0 && fields[fields.length - 1] === '') fields.pop()
+  return fields
+}
+
+/**
+ * Peel `count` space-separated tokens off the front of `text`.
+ *
+ * @returns {{ tokens: string[], rest: string }} `rest` is everything after the
+ *   last token, verbatim (so it may be empty, and may itself contain spaces).
+ */
+function takeTokens(text, count) {
+  const tokens = []
+  let rest = text
+  for (let index = 0; index < count; index += 1) {
+    const space = rest.indexOf(' ')
+    if (space < 0) return { tokens, rest: '' }
+    tokens.push(rest.slice(0, space))
+    rest = rest.slice(space + 1)
+  }
+  return { tokens, rest }
+}
+
+/**
+ * Bucket one `XY` pair into the status the UI shows.
+ *
+ * `U` anywhere, and the `AA`/`DD` both-added/both-deleted pairs, are conflicts:
+ * git reports those on `u` records, but the same letters can appear on an
+ * ordinary record once a merge has left the index dirty, so both are checked.
+ *
+ * @param {string} type record tag: `1`, `2`, `u`, `?` or `!`
+ * @param {string} index the `X` (index) status character
+ * @param {string} worktree the `Y` (worktree) status character
+ */
+export function classify(type, index, worktree) {
+  if (type === '?') return FILE_STATUS.UNTRACKED
+  const conflicted =
+    type === 'u' ||
+    index === 'U' ||
+    worktree === 'U' ||
+    (index === 'A' && worktree === 'A') ||
+    (index === 'D' && worktree === 'D')
+  if (conflicted) return FILE_STATUS.CONFLICTED
+  if (index === 'R' || index === 'C') return FILE_STATUS.RENAMED
+  if (index === 'A') return FILE_STATUS.ADDED
+  if (index === 'D' || worktree === 'D') return FILE_STATUS.DELETED
+  return FILE_STATUS.MODIFIED
+}
+
+/** Build the normalized file entry both halves speak about. */
+function makeEntry({ type, xy, path, origPath }) {
+  const index = xy.slice(0, 1)
+  const worktree = xy.slice(1, 2)
+  const kind = classify(type, index, worktree)
+  const untracked = type === '?'
+  const ignored = type === '!'
+  return {
+    /** Repository-relative path, git's own spelling (forward slashes). */
+    path,
+    /** Present only for a rename/copy: the path it came from. */
+    ...(origPath === undefined ? {} : { origPath }),
+    index,
+    worktree,
+    kind,
+    untracked,
+    ignored,
+    conflicted: kind === FILE_STATUS.CONFLICTED,
+    /**
+     * Whether *all* of this file's change is in the index.
+     *
+     * This is what the client's tick box mirrors: a ticked file is fully
+     * staged, so `git commit` (plain, no pathspec) commits exactly the ticked
+     * set. An untracked file is by definition not staged.
+     */
+    staged: !untracked && !ignored && index !== '.',
+    /** Both sides dirty — the tick box renders as indeterminate. */
+    partial: !untracked && !ignored && index !== '.' && worktree !== '.',
+  }
+}
+
+/**
+ * Parse `git status --porcelain=v2 --branch -z`.
+ *
+ * @param {string} raw the command's stdout
+ * @returns {{
+ *   branch: {
+ *     oid: string | null, head: string | null, upstream: string | null,
+ *     ahead: number, behind: number, detached: boolean, unborn: boolean,
+ *   },
+ *   files: ReturnType<typeof makeEntry>[],
+ * }}
+ */
+export function parseStatus(raw) {
+  const branch = {
+    oid: null,
+    head: null,
+    upstream: null,
+    ahead: 0,
+    behind: 0,
+    detached: false,
+    unborn: false,
+  }
+  const files = []
+  const fields = splitNul(raw)
+
+  for (let cursor = 0; cursor < fields.length; cursor += 1) {
+    const field = fields[cursor]
+    if (field === '') continue
+    const tag = field.slice(0, 1)
+
+    if (tag === '#') {
+      const body = field.slice(2)
+      const space = body.indexOf(' ')
+      const key = space < 0 ? body : body.slice(0, space)
+      const value = space < 0 ? '' : body.slice(space + 1)
+      if (key === 'branch.oid') {
+        branch.oid = value
+        branch.unborn = value === '(initial)'
+      } else if (key === 'branch.head') {
+        branch.head = value
+        branch.detached = value === '(detached)'
+      } else if (key === 'branch.upstream') {
+        branch.upstream = value
+      } else if (key === 'branch.ab') {
+        const match = /^\+(\d+)\s+-(\d+)$/.exec(value)
+        if (match !== null) {
+          branch.ahead = Number(match[1])
+          branch.behind = Number(match[2])
+        }
+      }
+      continue
+    }
+
+    if (tag === '1') {
+      const { tokens, rest } = takeTokens(field.slice(2), 7)
+      if (tokens.length < 7) continue
+      files.push(makeEntry({ type: '1', xy: tokens[0], path: rest }))
+      continue
+    }
+
+    if (tag === '2') {
+      const { tokens, rest } = takeTokens(field.slice(2), 8)
+      if (tokens.length < 8) continue
+      // With -z the original path is its own NUL-terminated field, so consume it.
+      const origPath = fields[cursor + 1]
+      cursor += 1
+      files.push(makeEntry({ type: '2', xy: tokens[0], path: rest, origPath }))
+      continue
+    }
+
+    if (tag === 'u') {
+      // `u XY sub m1 m2 m3 mW h1 h2 h3 <path>` — nine fixed fields after the
+      // tag, then the path. Counting ten here consumes the first word of the
+      // path and yields an entry whose path is empty, which is a *silent* wrong
+      // answer: the conflict simply vanishes from the list.
+      const { tokens, rest } = takeTokens(field.slice(2), 9)
+      if (tokens.length < 9) continue
+      files.push(makeEntry({ type: 'u', xy: tokens[0], path: rest }))
+      continue
+    }
+
+    if (tag === '?' || tag === '!') {
+      files.push(makeEntry({ type: tag, xy: tag === '?' ? '??' : '!!', path: field.slice(2) }))
+      continue
+    }
+  }
+
+  return { branch, files }
+}
+
+/**
+ * Parse `git diff --numstat -z --find-renames`.
+ *
+ * Records are `<added>\t<deleted>\t<path>`, except a rename, where the path is
+ * empty and the next two NUL fields carry the old and new path. A binary file
+ * reports `-` for both counts.
+ *
+ * @param {string} raw the command's stdout
+ * @returns {Map<string, { path: string, origPath?: string, added: number, deleted: number, binary: boolean }>}
+ *   keyed by the new path
+ */
+export function parseNumstat(raw) {
+  const result = new Map()
+  const fields = splitNul(raw)
+  let cursor = 0
+
+  while (cursor < fields.length) {
+    const record = fields[cursor]
+    cursor += 1
+    if (record === '') continue
+
+    const firstTab = record.indexOf('\t')
+    if (firstTab < 0) continue
+    const secondTab = record.indexOf('\t', firstTab + 1)
+    if (secondTab < 0) continue
+
+    const addedText = record.slice(0, firstTab)
+    const deletedText = record.slice(firstTab + 1, secondTab)
+    let path = record.slice(secondTab + 1)
+    let origPath
+
+    if (path === '') {
+      origPath = fields[cursor]
+      path = fields[cursor + 1]
+      cursor += 2
+      if (path === undefined) break
+    }
+
+    const binary = addedText === '-'
+    result.set(path, {
+      path,
+      ...(origPath === undefined ? {} : { origPath }),
+      added: binary ? 0 : Number(addedText) || 0,
+      deleted: binary ? 0 : Number(deletedText) || 0,
+      binary,
+    })
+  }
+
+  return result
+}
+
+/**
+ * Parse `git diff --name-only -z`, used to learn the path list a bare
+ * `git diff HEAD` would cover without materializing the diff itself.
+ *
+ * @param {string} raw the command's stdout
+ * @returns {string[]}
+ */
+export function parseNameOnly(raw) {
+  return splitNul(raw)
+}