dsh-git-ui 0.0.1

package/src/client/turn-signal.ts

@@ -0,0 +1,33 @@
+/**
+ * Turn-completion signal for the git pill's activity trigger.
+ *
+ * The client runtime's ConversationSnapshot carries `turnEnds` — completed
+ * turn numbers inside the snapshot window. A finished agent turn is the most
+ * likely moment the working tree changed, so the pill watches the highest
+ * completed turn and refreshes when it rises (best-effort; polling remains
+ * the fallback). Kept React-free so the logic is unit-testable without a
+ * browser runtime.
+ */
+
+/**
+ * The slice of the conversation snapshot the pill observes for activity.
+ * `turnEnds` maps completed turn numbers to their closing event seq inside
+ * the snapshot window (source: the client runtime's ConversationSnapshot).
+ */
+export interface TurnSignalSnapshot {
+  readonly turnEnds: ReadonlyMap<number, number>
+}
+
+/**
+ * Highest completed turn number in the snapshot window, 0 when none.
+ * Monotonic across ordinary activity (a finished turn only ever adds a
+ * larger key), so `next > prev` is a reliable "an agent turn just ended"
+ * edge — the best-effort trigger for an immediate refresh.
+ */
+export function completedTurnCount(snapshot: TurnSignalSnapshot): number {
+  let max = 0
+  for (const turn of snapshot.turnEnds.keys()) {
+    if (turn > max) max = turn
+  }
+  return max
+}

package/src/host/core.ts

@@ -0,0 +1,199 @@
+/**
+ * Framework-free snapshot orchestration: session cwd resolution + git command
+ * sequence + frozen GitSnapshot assembly. Every dependency is injected
+ * structurally, so the whole flow is testable without a cordis runtime; the
+ * cordis shell (GitStatusService) only adapts host services into these faces.
+ */
+import { parseBranchOutput, parseLogOutput, parseStatusOutput } from './parser.ts'
+import type { GitRunner } from './git.ts'
+import type { GitSnapshot, GitSnapshotResult } from './types.ts'
+
+/** Resolved plugin config (already normalized; see normalizeConfig). */
+export interface GitStatusConfig {
+  readonly timeoutMs: number
+  readonly maxStatusBytes: number
+  readonly maxChanges: number
+  readonly defaultRefreshIntervalMs: number
+}
+
+/** Session identity lookup: live first, persisted fallback. */
+export interface SessionLookup {
+  /** Live session cwd; undefined when the session is cold or absent in memory. */
+  liveCwd(sessionId: string): string | undefined
+  /**
+   * Persisted session metadata; resolves to undefined when no persisted
+   * session exists, and to `{ cwd }` (cwd possibly undefined) otherwise.
+   */
+  persistedMeta(sessionId: string): Promise<{ readonly cwd?: string } | undefined>
+}
+
+/** Filesystem primitives (node:fs/promises slices). */
+export interface FsLike {
+  realpath(path: string): Promise<string>
+  stat(path: string): Promise<{ isDirectory(): boolean }>
+}
+
+/** Everything the snapshot flow needs beyond the session lookup. */
+export interface SnapshotDeps {
+  readonly run: GitRunner
+  readonly fs: FsLike
+  readonly sessions: SessionLookup
+  /** Injectable clock for deterministic tests. */
+  readonly now?: () => number
+  /** Caller-side cancellation (Remote `signal` slot): aborts in-flight git runs. */
+  readonly signal?: AbortSignal
+}
+
+/** Defaults applied by normalizeConfig when a value is absent or invalid. */
+export const DEFAULT_CONFIG: GitStatusConfig = {
+  timeoutMs: 5000,
+  maxStatusBytes: 4 * 1024 * 1024,
+  maxChanges: 100,
+  defaultRefreshIntervalMs: 30_000,
+}
+
+/** Coerce a raw patch config value into a validated GitStatusConfig. */
+export function normalizeConfig(raw: unknown): GitStatusConfig {
+  const value = (raw ?? {}) as Record<string, unknown>
+  const numberOr = (key: string, fallback: number): number => {
+    const candidate = value[key]
+    return typeof candidate === 'number' && Number.isFinite(candidate) && candidate >= 0
+      ? candidate
+      : fallback
+  }
+  return {
+    timeoutMs: numberOr('timeoutMs', DEFAULT_CONFIG.timeoutMs) || DEFAULT_CONFIG.timeoutMs,
+    maxStatusBytes: numberOr('maxStatusBytes', DEFAULT_CONFIG.maxStatusBytes) || DEFAULT_CONFIG.maxStatusBytes,
+    maxChanges: Math.floor(numberOr('maxChanges', DEFAULT_CONFIG.maxChanges) || DEFAULT_CONFIG.maxChanges),
+    defaultRefreshIntervalMs: numberOr('defaultRefreshIntervalMs', DEFAULT_CONFIG.defaultRefreshIntervalMs),
+  }
+}
+
+/** Outcome of the cwd resolution step. */
+type CwdResolution =
+  | { readonly ok: true; readonly cwd: string }
+  | { readonly ok: false; readonly error: Extract<GitSnapshotResult, { ok: false }>['error'] }
+
+async function resolveCwd(sessions: SessionLookup, sessionId: string): Promise<CwdResolution> {
+  const live = sessions.liveCwd(sessionId)
+  if (live !== undefined) return { ok: true, cwd: live }
+  const persisted = await sessions.persistedMeta(sessionId)
+  if (persisted === undefined) return { ok: false, error: { code: 'session-not-found', sessionId } }
+  if (persisted.cwd === undefined) return { ok: false, error: { code: 'cwd-unavailable', sessionId } }
+  return { ok: true, cwd: persisted.cwd }
+}
+
+/** Classify a failed run outcome into a snapshot failure. */
+function runFailure(result: { readonly timedOut: boolean }, detail: string): Extract<GitSnapshotResult, { ok: false }>['error'] {
+  return result.timedOut ? { code: 'timeout' } : { code: 'git-unavailable', detail }
+}
+
+/** Run one command, mapping a spawn-level failure to a snapshot failure. */
+async function runCommand(
+  runner: GitRunner,
+  argv: readonly string[],
+  cwd: string,
+  label: string,
+  signal?: AbortSignal,
+): Promise<{ readonly run: Awaited<ReturnType<GitRunner['run']>> } | { readonly failure: Extract<GitSnapshotResult, { ok: false }>['error'] }> {
+  try {
+    return { run: await runner.run(argv, { cwd, ...(signal === undefined ? {} : { signal }) }) }
+  } catch (error) {
+    return { failure: { code: 'git-unavailable', detail: `${label}: ${error instanceof Error ? error.message : String(error)}` } }
+  }
+}
+
+/**
+ * Build one frozen GitSnapshot for a session working directory.
+ * Command sequence (all read-only; every command after the first runs with
+ * the repository root as cwd):
+ *   1. `git rev-parse --show-toplevel`      — repo detection (exit 128 → not-a-git-repo)
+ *   2. `git branch --show-current`          — null when detached
+ *   3. `git rev-parse --short HEAD`         — null + unborn when the repo has no commits
+ *   4. `git status --porcelain=v1 -z --branch`
+ *   5. `git log -n 5 --format=%H%x1f%h%x1f%s%x1f%an%x1f%aI`
+ */
+export async function snapshotForSession(
+  deps: SnapshotDeps,
+  config: GitStatusConfig,
+  sessionId: string,
+): Promise<GitSnapshotResult> {
+  const resolved = await resolveCwd(deps.sessions, sessionId)
+  if (!resolved.ok) return { ok: false, error: resolved.error }
+
+  let realCwd: string
+  try {
+    realCwd = await deps.fs.realpath(resolved.cwd)
+    const stat = await deps.fs.stat(realCwd)
+    if (!stat.isDirectory()) {
+      return { ok: false, error: { code: 'path-not-found', path: realCwd } }
+    }
+  } catch {
+    return { ok: false, error: { code: 'path-not-found', path: resolved.cwd } }
+  }
+
+  const toplevel = await runCommand(deps.run, ['git', 'rev-parse', '--show-toplevel'], realCwd, 'rev-parse', deps.signal)
+  if ('failure' in toplevel) return { ok: false, error: toplevel.failure }
+  if (toplevel.run.timedOut) return { ok: false, error: { code: 'timeout' } }
+  if (toplevel.run.exitCode !== 0) {
+    // exit 128 covers both "not a git repository" (plain directory) and
+    // other git failures (dubious ownership, unreadable work tree, …).
+    // Only the former is a stable non-repo state; everything else surfaces
+    // as git-unavailable with the actual reason instead of a misleading
+    // "no git repository" pill.
+    const stderr = toplevel.run.stderr
+    if (!stderr.includes('not a git repository')) {
+      return { ok: false, error: runFailure(toplevel.run, `git rev-parse failed: ${stderr.trim() || `exit ${String(toplevel.run.exitCode)}`}`) }
+    }
+    return { ok: false, error: { code: 'not-a-git-repo' } }
+  }
+  const root = toplevel.run.stdout.trim()
+  if (root === '') return { ok: false, error: { code: 'not-a-git-repo' } }
+
+  const branchRun = await runCommand(deps.run, ['git', 'branch', '--show-current'], root, 'branch', deps.signal)
+  if ('failure' in branchRun) return { ok: false, error: branchRun.failure }
+  if (branchRun.run.timedOut) return { ok: false, error: { code: 'timeout' } }
+  const branch = branchRun.run.exitCode === 0 ? parseBranchOutput(branchRun.run.stdout) : null
+
+  const headRun = await runCommand(deps.run, ['git', 'rev-parse', '--short', 'HEAD'], root, 'rev-parse HEAD', deps.signal)
+  if ('failure' in headRun) return { ok: false, error: headRun.failure }
+  if (headRun.run.timedOut) return { ok: false, error: { code: 'timeout' } }
+  // A failed HEAD read (non-timeout) only nulls the hash: the authoritative
+  // unborn flag comes from the status header below (`## No commits yet on
+  // main`), so a corrupt repo is never misreported as "no commits".
+  const head = headRun.run.exitCode === 0 ? (headRun.run.stdout.trim() || null) : null
+
+  const status = await runCommand(deps.run, ['git', 'status', '--porcelain=v1', '-z', '--branch'], root, 'status', deps.signal)
+  if ('failure' in status) return { ok: false, error: status.failure }
+  if (status.run.timedOut) return { ok: false, error: { code: 'timeout' } }
+  if (status.run.exitCode !== 0) {
+    return { ok: false, error: runFailure(status.run, `git status exited ${String(status.run.exitCode)}`) }
+  }
+  const parsed = parseStatusOutput(status.run.stdout, config.maxChanges)
+
+  const log = await runCommand(deps.run, ['git', 'log', '-n', '5', '--format=%H%x1f%h%x1f%s%x1f%an%x1f%aI'], root, 'log', deps.signal)
+  if ('failure' in log) return { ok: false, error: log.failure }
+  if (log.run.timedOut) return { ok: false, error: { code: 'timeout' } }
+  const recentCommits = log.run.exitCode === 0 ? parseLogOutput(log.run.stdout) : []
+
+  const checkedAt = deps.now?.() ?? Date.now()
+  const snapshot: GitSnapshot = {
+    root,
+    branch,
+    head,
+    unborn: parsed.unborn,
+    dirty: parsed.staged + parsed.modified + parsed.untracked > 0,
+    staged: parsed.staged,
+    modified: parsed.modified,
+    untracked: parsed.untracked,
+    ahead: parsed.ahead,
+    behind: parsed.behind,
+    lastCommit: recentCommits[0] ?? null,
+    recentCommits,
+    changes: parsed.changes,
+    truncated: parsed.truncated || ('run' in status && status.run.stdoutLossy),
+    refreshIntervalMs: config.defaultRefreshIntervalMs,
+    checkedAt,
+  }
+  return { ok: true, value: snapshot }
+}

package/src/host/git.ts

@@ -0,0 +1,152 @@
+/**
+ * Git command execution adapter over the host subprocess service.
+ *
+ * The widget only needs a tiny slice of the subprocess contract; declaring it
+ * structurally here (instead of depending on the npm package, whose registry
+ * chain is incomplete) keeps the plugin buildable standalone while remaining
+ * wire-compatible with the host's `subprocess` service.
+ */
+import { readFile } from 'node:fs/promises'
+
+/** One collected stream disposition (matches the host SubprocessCollect). */
+interface CollectDisposition {
+  readonly collect: {
+    readonly maxBytes: number
+    /**
+     * Spill disposition: when the stream overflows the in-memory tail, the
+     * host appends the COMPLETE stream to a private spill file (up to this
+     * cap) and `readFrom` reports its path. Without it, only the tail is
+     * ever retained and the head (and its change counts) is lost.
+     */
+    readonly spill?: { readonly maxBytes: number }
+  }
+}
+
+/** Structural slice of the host subprocess spawn spec. */
+interface SpawnSpec {
+  readonly argv: readonly string[]
+  readonly cwd: string
+  readonly stdio: {
+    readonly stdout: CollectDisposition
+    readonly stderr: CollectDisposition
+  }
+  readonly graceMs: number
+  readonly signal?: AbortSignal
+}
+
+/** Structural slice of the host subprocess handle (collect-mode output). */
+interface SpawnHandle {
+  readonly done: Promise<{ readonly exitCode: number | null; readonly signal: NodeJS.Signals | null }>
+  readonly collected: {
+    readonly stdout?: {
+      readFrom(fromByte: number): { readonly text: string; readonly lossy: boolean; readonly spillPath?: string }
+    }
+    readonly stderr?: {
+      readFrom(fromByte: number): { readonly text: string; readonly lossy: boolean; readonly spillPath?: string }
+    }
+  }
+}
+
+/** Minimal subprocess-service face the adapter consumes. */
+export interface SubprocessLike {
+  spawn(spec: SpawnSpec): SpawnHandle
+}
+
+/** One git command outcome. */
+export interface GitRunResult {
+  /** Process exit code; null when terminated by a signal. */
+  readonly exitCode: number | null
+  readonly stdout: string
+  readonly stderr: string
+  /** True when the run was killed by our timeout (or the caller's signal). */
+  readonly timedOut: boolean
+  /**
+   * True when the final stdout text is still incomplete: the collected
+   * output overflowed its byte cap AND the spill file was unavailable (no
+   * spill configured on the host, or the spill cap also overflowed).
+   */
+  readonly stdoutLossy: boolean
+}
+
+/** The run primitive the snapshot orchestration uses. */
+export interface GitRunner {
+  run(argv: readonly string[], opts: { readonly cwd: string; readonly signal?: AbortSignal }): Promise<GitRunResult>
+}
+
+/**
+ * Adapt the host subprocess service into a `GitRunner` with a per-command
+ * timeout. A timed-out run resolves (never rejects) with `timedOut: true`;
+ * only spawn-level failures (e.g. git not installed) reject.
+ *
+ * Overflow handling: stdout/stderr collect with a spill cap of
+ * `maxBytes * 16` (default 4 MiB memory tail → 64 MiB spill file). When the
+ * tail overflowed but the spill file holds the complete stream, the runner
+ * reads the file and reports `stdoutLossy: false` — the change COUNTS stay
+ * exact. `stdoutLossy: true` is reserved for the doubly-overflowed case
+ * (spill also exceeded), where the head is genuinely lost.
+ */
+export function createGitRunner(subprocess: SubprocessLike, timeoutMs: number, maxBytes: number): GitRunner {
+  const spillMaxBytes = maxBytes * 16
+  return {
+    async run(argv, opts) {
+      const controller = new AbortController()
+      const timer = setTimeout(() => controller.abort(), timeoutMs)
+      try {
+        const signal = opts.signal === undefined
+          ? controller.signal
+          : AbortSignal.any([controller.signal, opts.signal])
+        const handle = subprocess.spawn({
+          argv,
+          cwd: opts.cwd,
+          stdio: {
+            stdout: { collect: { maxBytes, spill: { maxBytes: spillMaxBytes } } },
+            stderr: { collect: { maxBytes, spill: { maxBytes: spillMaxBytes } } },
+          },
+          graceMs: 200,
+          signal,
+        })
+        let outcome: Awaited<SpawnHandle['done']>
+        try {
+          // `done` rejects for spawn-level failures; an abort-triggered
+          // rejection is the timeout path and resolves as timedOut.
+          outcome = await handle.done
+        } catch (error) {
+          if (controller.signal.aborted || opts.signal?.aborted === true) {
+            return { exitCode: null, stdout: '', stderr: '', timedOut: true, stdoutLossy: false }
+          }
+          throw error
+        }
+        const stdout = handle.collected.stdout?.readFrom(0)
+        const stderr = handle.collected.stderr?.readFrom(0)
+        const stdoutResolved = await resolveStdout(stdout)
+        return {
+          exitCode: outcome.exitCode,
+          stdout: stdoutResolved.text,
+          stderr: stderr?.text ?? '',
+          timedOut: controller.signal.aborted || opts.signal?.aborted === true,
+          stdoutLossy: stdoutResolved.lossy,
+        }
+      } finally {
+        clearTimeout(timer)
+      }
+    },
+  }
+}
+
+/**
+ * Resolve the stdout text from a collect read: the in-memory tail, or — when
+ * the read is lossy and the host spilled the complete stream to a file — the
+ * spill file contents (so change COUNTS stay exact). A failed spill read
+ * falls back to the tail and keeps `lossy: true` (head genuinely lost).
+ */
+async function resolveStdout(
+  read: { readonly text: string; readonly lossy: boolean; readonly spillPath?: string } | undefined,
+): Promise<{ readonly text: string; readonly lossy: boolean }> {
+  if (read === undefined) return { text: '', lossy: false }
+  if (!read.lossy || read.spillPath === undefined) return { text: read.text, lossy: read.lossy }
+  try {
+    return { text: await readFile(read.spillPath, 'utf8'), lossy: false }
+  } catch {
+    return { text: read.text, lossy: true }
+  }
+}

package/src/host/index.ts

@@ -0,0 +1,80 @@
+/**
+ * dsh-git-ui host half: the `gitInfo` Remote service.
+ *
+ * Cordis shell only — every behavior lives in `core.ts` behind injected
+ * structural faces, so tests never need a cordis runtime. The class is a
+ * plugin in its own right (class form), mounted by the bundle patch row with
+ * the package name; the gateway exposes `gitInfo/snapshot` through SRC
+ * discovery (`typertRemote` binding + `@Remote` marker).
+ */
+import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
+import type { Context } from '@deepseek-ai/cordis'
+import { realpath, stat } from 'node:fs/promises'
+import { createGitRunner, type SubprocessLike } from './git.ts'
+import { normalizeConfig, snapshotForSession, type GitStatusConfig } from './core.ts'
+import type { GitSnapshotRequest, GitSnapshotResult } from './types.ts'
+
+export type { GitSnapshot, GitSnapshotResult, GitSnapshotFailure, GitSnapshotRequest, GitCommit, GitChange } from './types.ts'
+export { normalizeConfig, DEFAULT_CONFIG } from './core.ts'
+export { parseStatusOutput, parseLogOutput, parseBranchOutput } from './parser.ts'
+
+/** Structural face of a live session header. */
+interface SessionLike {
+  readonly header?: { readonly cwd?: string }
+}
+
+/** Structural face of the sessions service. */
+interface SessionsLike {
+  get(id: string): SessionLike | undefined
+}
+
+/** Structural face of the session-persistence service. */
+interface SessionPersistenceLike {
+  inspect(id: string): Promise<{ readonly meta: { readonly cwd?: string } }>
+}
+
+/** The `gitInfo` service: one `snapshot` Remote endpoint. */
+export class GitStatusService extends TypertRemoteService {
+  static inject = ['subprocess', 'sessions', 'sessionPersistence']
+
+  private readonly config: GitStatusConfig
+
+  constructor(ctx: Context, config: unknown) {
+    super(ctx, 'gitInfo')
+    this.config = normalizeConfig(config)
+  }
+
+  @Remote('snapshot')
+  async snapshot(request: GitSnapshotRequest, signal?: AbortSignal): Promise<GitSnapshotResult> {
+    const subprocess = this.ctx.get('subprocess') as SubprocessLike | undefined
+    if (subprocess === undefined) {
+      return { ok: false, error: { code: 'git-unavailable', detail: 'subprocess service unavailable' } }
+    }
+    const sessions = this.ctx.get('sessions') as SessionsLike | undefined
+    const persistence = this.ctx.get('sessionPersistence') as SessionPersistenceLike | undefined
+    const runner = createGitRunner(subprocess, this.config.timeoutMs, this.config.maxStatusBytes)
+    return snapshotForSession(
+      {
+        run: runner,
+        fs: { realpath, stat },
+        sessions: {
+          liveCwd: (id) => sessions?.get(id)?.header?.cwd,
+          persistedMeta: async (id) => {
+            if (persistence === undefined) return undefined
+            try {
+              const inspection = await persistence.inspect(id)
+              return { cwd: inspection.meta.cwd }
+            } catch {
+              return undefined
+            }
+          },
+        },
+        signal,
+      },
+      this.config,
+      request.sessionId,
+    )
+  }
+}
+
+export default GitStatusService

package/src/host/parser.ts

@@ -0,0 +1,176 @@
+/**
+ * Pure parsers for the git porcelain/log output shapes used by the widget.
+ * No side effects and no I/O — fully unit-testable against literal fixtures
+ * (verified against real `git status --porcelain=v1 -z --branch` output).
+ */
+import type { GitChange, GitChangeStatus, GitCommit } from './types.ts'
+
+/** Parsed status counts plus the (possibly capped) change list. */
+export interface ParsedStatus {
+  readonly branch: string | null
+  readonly unborn: boolean
+  readonly staged: number
+  readonly modified: number
+  readonly untracked: number
+  readonly ahead: number
+  readonly behind: number
+  readonly changes: readonly GitChange[]
+  readonly truncated: boolean
+}
+
+/** The NUL byte separating porcelain v1 -z entries. */
+const NUL = '\u0000'
+/** The unit separator used by the log --format payload. */
+const LOG_SEP = '\u001f'
+
+interface StatusHeader {
+  readonly branch: string | null
+  readonly unborn: boolean
+  readonly ahead: number
+  readonly behind: number
+}
+
+/**
+ * Parse the `## ` header line of `git status --porcelain=v1 -z --branch`.
+ * Recognized shapes (verified against git 2.x):
+ *   `## main`
+ *   `## main...origin/main`
+ *   `## main...origin/main [ahead 1]`
+ *   `## main...origin/main [behind 2]`
+ *   `## main...origin/main [ahead 1, behind 2]`
+ *   `## HEAD (no branch)`                 (detached)
+ *   `## HEAD (detached at <hash>)`        (detached, older git)
+ *   `## No commits yet on main`           (unborn)
+ *   `## Initial commit on main`           (unborn, older git)
+ */
+export function parseStatusHeader(line: string): StatusHeader {
+  const body = line.startsWith('## ') ? line.slice(3) : line
+  if (body === '') return { branch: null, unborn: false, ahead: 0, behind: 0 }
+
+  const unbornMatch = /^(?:No commits yet on|Initial commit on)\s+(.+)$/.exec(body)
+  if (unbornMatch !== null) {
+    return { branch: unbornMatch[1] ?? null, unborn: true, ahead: 0, behind: 0 }
+  }
+
+  const detached = /^HEAD(?:\s+\([^)]*\))?$/.exec(body)
+  if (detached !== null) {
+    return { branch: null, unborn: false, ahead: 0, behind: 0 }
+  }
+
+  const bracketMatch = /^(.*?)\s*\[([^\]]+)\]$/.exec(body)
+  const core = bracketMatch?.[1] ?? body
+  let ahead = 0
+  let behind = 0
+  if (bracketMatch?.[2] !== undefined) {
+    for (const part of bracketMatch[2].split(',')) {
+      const trimmed = part.trim()
+      const aheadMatch = /^ahead (\d+)$/.exec(trimmed)
+      const behindMatch = /^behind (\d+)$/.exec(trimmed)
+      if (aheadMatch !== null) ahead = Number(aheadMatch[1])
+      if (behindMatch !== null) behind = Number(behindMatch[1])
+    }
+  }
+  // The core is `<branch>...<upstream>` — the branch never contains `...`.
+  const branch = core.split('...', 1)[0] ?? core
+  return { branch: branch === '' ? null : branch, unborn: false, ahead, behind }
+}
+
+/** Map one porcelain XY pair to a change status. */
+function changeStatus(x: string, y: string): GitChangeStatus {
+  if (x === '?' && y === '?') return 'untracked'
+  if (x === 'U' || y === 'U' || (x !== ' ' && y !== ' ')) return 'conflicted'
+  switch (x) {
+    case 'A': return 'added'
+    case 'M': return 'modified'
+    case 'D': return 'deleted'
+    case 'R': return 'renamed'
+    case 'T': return 'typechange'
+    case 'C': return 'added'
+    default: return 'modified'
+  }
+}
+
+/**
+ * Parse the full `git status --porcelain=v1 -z --branch` output.
+ * -z format: every entry (header and each `XY path`) is NUL-terminated; a
+ * rename/copy entry emits `R  <new>\0<old>\0` so the following item is the
+ * source path and must be consumed without becoming a change itself.
+ */
+export function parseStatusOutput(output: string, maxChanges: number): ParsedStatus {
+  const raw = output.split(NUL)
+  // Trailing NUL produces a final empty segment; drop it.
+  const segments = raw[raw.length - 1] === '' ? raw.slice(0, -1) : raw
+  const header = parseStatusHeader(segments[0] ?? '')
+
+  let staged = 0
+  let modified = 0
+  let untracked = 0
+  const changes: GitChange[] = []
+  let truncated = false
+
+  for (let index = 1; index < segments.length; index += 1) {
+    const entry = segments[index] ?? ''
+    const x = entry[0] ?? ' '
+    const y = entry[1] ?? ' '
+    const path = entry.slice(3)
+    if (x === ' ' && y === ' ') continue
+    if (x === 'R' || x === 'C') {
+      // -z: the source path is the next segment — consume it.
+      index += 1
+    }
+    if (x === '?' && y === '?') {
+      untracked += 1
+    } else {
+      if (x !== ' ' && x !== '?') staged += 1
+      if (y !== ' ' && y !== '?') modified += 1
+    }
+    if (changes.length < maxChanges) {
+      changes.push({ path, status: changeStatus(x, y), staged: x !== ' ' && x !== '?' })
+    } else {
+      truncated = true
+    }
+  }
+
+  return {
+    branch: header.branch,
+    unborn: header.unborn,
+    staged,
+    modified,
+    untracked,
+    ahead: header.ahead,
+    behind: header.behind,
+    changes,
+    truncated,
+  }
+}
+
+/**
+ * Parse `git log -n 5 --format=%H%x1f%h%x1f%s%x1f%an%x1f%aI` output.
+ * One commit per line, fields separated by the unit separator; empty output
+ * (unborn repository) yields `[]`.
+ */
+export function parseLogOutput(output: string): readonly GitCommit[] {
+  const commits: GitCommit[] = []
+  for (const line of output.split('\n')) {
+    if (line === '') continue
+    const [hash, shortHash, subject, author, dateIso] = line.split(LOG_SEP)
+    if (hash === undefined || hash === '') continue
+    commits.push({
+      hash,
+      shortHash: shortHash ?? '',
+      subject: subject ?? '',
+      author: author ?? '',
+      dateIso: dateIso ?? '',
+    })
+  }
+  return commits
+}
+
+/**
+ * Parse `git branch --show-current` output: the branch name, or null when
+ * empty (detached HEAD).
+ */
+export function parseBranchOutput(output: string): string | null {
+  const trimmed = output.trim()
+  return trimmed === '' ? null : trimmed
+}