dsh-github-router 0.1.0

package/lib/routes/api.js

@@ -0,0 +1,136 @@
+/**
+ * api.github.com REST client — GET-only by construction. There is no method
+ * field, no body, and no verb other than GET anywhere in this module. The
+ * token is attached only to api.github.com requests and is never logged.
+ * @module dsh-github-router/routes/api
+ */
+import { RouteError } from '../net.js'
+
+export const API_BASE = 'https://api.github.com'
+export const USER_AGENT = 'dsh-github-router/0.1.0'
+const ACCEPT = 'application/vnd.github+json'
+const API_VERSION = '2022-11-28'
+
+/** Classify a non-2xx api.github.com response into a stable failure code. */
+export function apiErrorCode(status, headers) {
+  if (status === 401) return 'AUTH_REQUIRED'
+  if (status === 404) return 'NOT_FOUND'
+  if (status === 403 && headers !== undefined && headers['x-ratelimit-remaining'] === '0') return 'RATE_LIMITED'
+  if (status === 429) return 'RATE_LIMITED'
+  if (status >= 500) return 'HTTP'
+  return 'HTTP'
+}
+
+/** Build one api.github.com URL from a validated path and query values. */
+export function apiUrl(path, query) {
+  const url = new URL(API_BASE + path)
+  if (query !== undefined && query !== null) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value === undefined || value === null || value === '') continue
+      const v = String(value)
+      if (/[\u0000-\u001f\u007f]/.test(v) || v.length > 1024) continue
+      url.searchParams.set(key, v)
+    }
+  }
+  return url.toString()
+}
+
+/**
+ * A GitHub API client bound to the router's transport and options.
+ * Token resolution happens per call so settings changes apply immediately.
+ */
+export class GithubApi {
+  constructor(options) {
+    this.options = options // { retries, directTimeoutMs, proxyTimeoutMs, maxBytes }
+  }
+
+  headers(token) {
+    const headers = {
+      accept: ACCEPT,
+      'user-agent': USER_AGENT,
+      'x-github-api-version': API_VERSION,
+    }
+    if (token !== undefined && token !== null && token !== '') {
+      headers.authorization = `Bearer ${token}`
+    }
+    return headers
+  }
+
+  /**
+   * GET a JSON endpoint with cache and retry handling.
+   * @param path - validated api.github.com relative path
+   * @param call - { query, token, signal, proxy, timeoutMs, cache, ttlMs, forceRefresh }
+   */
+  async getJson(path, call = {}) {
+    const url = apiUrl(path, call.query)
+    const { cache, ttlMs, forceRefresh } = call
+    const fetcher = async () => {
+      const raw = await call.fetchImpl(url, {
+        headers: this.headers(call.token),
+        timeoutMs: call.timeoutMs !== undefined ? call.timeoutMs : call.proxy !== undefined ? this.options.proxyTimeoutMs : this.options.directTimeoutMs,
+        proxy: call.proxy,
+        signal: call.signal,
+        maxBytes: this.options.maxBytes,
+        retries: this.options.retries,
+      })
+      if (raw.ok) {
+        let json
+        try {
+          json = JSON.parse(raw.body.toString('utf8'))
+        } catch (error) {
+          throw new RouteError('TRANSPORT', `unprocessable JSON from ${url}: ${String(error && error.message ? error.message : error)}`, { cause: error })
+        }
+        return { ok: true, status: raw.status, json, headers: raw.headers, truncated: raw.truncated }
+      }
+      const code = apiErrorCode(raw.status, raw.headers)
+      let detail = `GitHub API error (HTTP ${raw.status})`
+      try {
+        const parsed = JSON.parse(raw.body.toString('utf8'))
+        const message = parsed && (parsed.message || (parsed.error && parsed.error.message))
+        if (typeof message === 'string' && message.length > 0) detail = message
+      } catch { /* keep generic detail */ }
+      throw new RouteError(code, detail, { status: raw.status })
+    }
+
+    const withMeta = (value, hit) => {
+      const out = Array.isArray(value) ? [...value] : { ...value }
+      // Arrays serialize indices only — enumerable side props would violate
+      // the lossless-JSON tool contract, so they are attached only to
+      // object endpoints (where rate-limit notes actually read them).
+      if (!Array.isArray(value)) {
+        Object.defineProperties(out, {
+          _headers: { value: hit.headers, enumerable: true },
+          _status: { value: hit.status, enumerable: true },
+          cached: { value: true, enumerable: true },
+        })
+      }
+      return out
+    }
+    if (cache !== undefined && ttlMs > 0 && !forceRefresh) {
+      const hit = cache.get(url, ttlMs)
+      if (hit !== undefined) return withMeta(hit.json, hit)
+    }
+    const fresh = await fetcher()
+    if (cache !== undefined && ttlMs > 0 && fresh.ok) {
+      cache.set(url, { json: fresh.json, headers: fresh.headers, status: fresh.status }, ttlMs)
+    }
+    return withMeta(fresh.json, fresh)
+  }
+
+  /**
+   * GET a text/diff endpoint (Accept overridden). Used for PR diffs.
+   */
+  async getText(path, accept, call = {}) {
+    const url = apiUrl(path, call.query)
+    const raw = await call.fetchImpl(url, {
+      headers: { ...this.headers(call.token), accept },
+      timeoutMs: call.timeoutMs !== undefined ? call.timeoutMs : call.proxy !== undefined ? this.options.proxyTimeoutMs : this.options.directTimeoutMs,
+      proxy: call.proxy,
+      signal: call.signal,
+      maxBytes: this.options.maxBytes,
+      retries: this.options.retries,
+    })
+    if (raw.ok) return { ok: true, status: raw.status, text: raw.body.toString('utf8'), truncated: raw.truncated, headers: raw.headers }
+    throw new RouteError(apiErrorCode(raw.status, raw.headers), `GitHub API error (HTTP ${raw.status})`, { status: raw.status })
+  }
+}

package/lib/routes/gh.js

@@ -0,0 +1,109 @@
+/**
+ * gh CLI route. Only read-only subcommands are ever constructed here:
+ * `gh --version`, `gh auth status`, `gh api` (GET by default), and the
+ * `--json` viewers (`pr view`, `issue view`, `repo view`). JSON field lists
+ * are fixed constants — user input never reaches argv beyond validated
+ * owner/repo/number/path values, and nothing is ever passed through a shell.
+ * @module dsh-github-router/routes/gh
+ */
+import { childEnv, runCaptured } from '../util.js'
+
+const PR_FIELDS =
+  'author,title,body,state,isDraft,mergedAt,additions,deletions,changedFiles,' +
+  'createdAt,updatedAt,baseRefName,headRefName,headRefOid,baseRefOid,' +
+  'mergeable,reviewDecision,reviews,comments,commits,files'
+const ISSUE_FIELDS = 'author,title,body,state,stateReason,createdAt,updatedAt,closedAt,comments,labels,assignees'
+const REPO_FIELDS = 'nameWithOwner,description,defaultBranchRef,stargazerCount,forkCount,updatedAt,licenseInfo,isPrivate'
+
+export async function ghVersion(subprocess, signal) {
+  const out = await runCaptured(subprocess, { argv: ['gh', '--version'], graceMs: 8_000, signal, env: childEnv(), maxStdout: 4096, maxStderr: 4096 })
+  return out.ok
+}
+
+export async function ghAuthed(subprocess, signal) {
+  const out = await runCaptured(subprocess, { argv: ['gh', 'auth', 'status'], graceMs: 8_000, signal, env: childEnv(), maxStdout: 8192, maxStderr: 8192 })
+  return out.ok
+}
+
+/** Run a fixed gh invocation and parse its JSON stdout. */
+async function ghJson(subprocess, argv, spec = {}) {
+  const out = await runCaptured(subprocess, {
+    argv,
+    graceMs: spec.graceMs ?? 30_000,
+    signal: spec.signal,
+    env: childEnv(),
+    maxStdout: spec.maxStdout ?? 1048576,
+    maxStderr: 262144,
+  })
+  if (!out.ok) {
+    const err = new Error(`gh exited with code ${out.exitCode}: ${out.stderr.text.slice(0, 400)}`)
+    err.code = 'GH_FAILED'
+    throw err
+  }
+  try {
+    return JSON.parse(out.stdout.text)
+  } catch (error) {
+    const err = new Error(`gh produced unprocessable JSON: ${String(error && error.message ? error.message : error)}`)
+    err.code = 'GH_FAILED'
+    throw err
+  }
+}
+
+/** `gh pr view <owner/repo/N> --json ...` */
+export async function ghPrView(subprocess, owner, repo, number, spec = {}) {
+  return ghJson(subprocess, ['gh', 'pr', 'view', `${owner}/${repo}/${number}`, '--json', PR_FIELDS], spec)
+}
+
+/** `gh pr diff <owner/repo/N>` — capped text of the PR diff. */
+export async function ghPrDiff(subprocess, owner, repo, number, spec = {}) {
+  const out = await runCaptured(subprocess, {
+    argv: ['gh', 'pr', 'diff', `${owner}/${repo}/${number}`],
+    graceMs: 30_000,
+    signal: spec.signal,
+    env: childEnv(),
+    maxStdout: spec.maxStdout ?? 1048576,
+    maxStderr: 262144,
+  })
+  if (!out.ok) {
+    const err = new Error(`gh pr diff exited with code ${out.exitCode}: ${out.stderr.text.slice(0, 400)}`)
+    err.code = 'GH_FAILED'
+    throw err
+  }
+  return { text: out.stdout.text, truncated: out.stdout.truncated }
+}
+
+/** `gh issue view <owner/repo/N> --json ...` */
+export async function ghIssueView(subprocess, owner, repo, number, spec = {}) {
+  return ghJson(subprocess, ['gh', 'issue', 'view', `${owner}/${repo}/${number}`, '--json', ISSUE_FIELDS], spec)
+}
+
+/** `gh repo view <owner/repo> --json ...` */
+export async function ghRepoView(subprocess, owner, repo, spec = {}) {
+  return ghJson(subprocess, ['gh', 'repo', 'view', `${owner}/${repo}`, '--json', REPO_FIELDS], spec)
+}
+
+/**
+ * `gh api <path>` — GET only, with the validated api path as a single argv
+ * element. Output is parsed as JSON when possible, else returned as text.
+ */
+export async function ghApi(subprocess, path, spec = {}) {
+  const out = await runCaptured(subprocess, {
+    argv: ['gh', 'api', path],
+    graceMs: 30_000,
+    signal: spec.signal,
+    env: childEnv(),
+    maxStdout: spec.maxStdout ?? 1048576,
+    maxStderr: 262144,
+  })
+  if (!out.ok) {
+    const err = new Error(`gh api exited with code ${out.exitCode}: ${out.stderr.text.slice(0, 400)}`)
+    err.code = 'GH_FAILED'
+    throw err
+  }
+  const text = out.stdout.text
+  try {
+    return { json: JSON.parse(text), truncated: out.stdout.truncated }
+  } catch {
+    return { json: null, text, truncated: out.stdout.truncated }
+  }
+}

package/lib/routes/git.js

@@ -0,0 +1,429 @@
+/**
+ * git protocol route — the empirically surviving path on machines where
+ * HTTPS to github.com/api.github.com is reset.
+ *
+ * Two strictly separated modes:
+ * 1. Plugin fetch cache: a plugin-owned bare-less repo under the host
+ *    storage dir. `git init` + `git fetch` of pull refs write ONLY there.
+ * 2. Local repo reads: user-granted repos (settings `repos`, the session
+ *    cwd repo when its origin matches, or an explicit per-call path) are
+ *    read with log/diff/show/rev-parse ONLY. The plugin never fetches into,
+ *    checks out, resets, or pushes to a user repository.
+ *
+ * All subprocess calls are argv arrays; nothing is shell-interpolated.
+ * @module dsh-github-router/routes/git
+ */
+import { existsSync, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { GIT_CACHE_DIR, childEnv, ownerRepoFromUrl, runCaptured } from '../util.js'
+
+const FETCH_GRACE_MS = 90_000
+const READ_GRACE_MS = 20_000
+
+export async function gitVersion(subprocess, signal) {
+  const out = await runCaptured(subprocess, { argv: ['git', '--version'], graceMs: 8_000, signal, env: childEnv(), maxStdout: 4096, maxStderr: 4096 })
+  return out.ok
+}
+
+function proxyEnv(proxy) {
+  if (proxy === undefined || proxy === null || proxy === '') return {}
+  return { http_proxy: proxy, https_proxy: proxy, HTTP_PROXY: proxy, HTTPS_PROXY: proxy }
+}
+
+/** `git ls-remote <url> <ref>` — a pure connectivity + sha probe. */
+export async function gitLsRemote(subprocess, remoteUrl, ref, spec = {}) {
+  const out = await runCaptured(subprocess, {
+    argv: ['git', 'ls-remote', remoteUrl, ref],
+    graceMs: spec.graceMs ?? 20_000,
+    signal: spec.signal,
+    env: childEnv(proxyEnv(spec.proxy)),
+    maxStdout: 8192,
+    maxStderr: 8192,
+  })
+  if (!out.ok) return { ok: false, sha: null, error: (out.stderr.text || out.spawnError || `exit ${out.exitCode}`).slice(0, 300) }
+  const match = /^([0-9a-f]{40})\s+/.exec(out.stdout.text)
+  if (match === null) return { ok: true, sha: null, error: 'no sha in ls-remote output' }
+  return { ok: true, sha: match[1], error: null }
+}
+
+/** In-process mutex per cache repo: fetches to one repo are serialized. */
+const repoLocks = new Map()
+async function withRepoLock(key, fn) {
+  const prev = repoLocks.get(key) ?? Promise.resolve()
+  const next = prev.then(fn, fn)
+  repoLocks.set(key, next.catch(() => {}))
+  try {
+    return await next
+  } finally {
+    if (repoLocks.get(key) === next) repoLocks.delete(key)
+  }
+}
+
+/**
+ * The plugin-owned fetch cache. Every write stays under the host storage
+ * dir; nothing outside it is ever created.
+ */
+export class GitFetchCache {
+  constructor(subprocess, gitCacheDir = GIT_CACHE_DIR) {
+    this.subprocess = subprocess
+    this.gitDir = gitCacheDir
+  }
+
+  repoDir(owner, repo) {
+    return join(this.gitDir, `${owner}__${repo}`)
+  }
+
+  async ensure(owner, repo) {
+    const dir = this.repoDir(owner, repo)
+    if (existsSync(join(dir, '.git'))) return dir
+    try { mkdirSync(this.gitDir, { recursive: true }) } catch { /* exists */ }
+    const init = await runCaptured(this.subprocess, {
+      argv: ['git', 'init', '--quiet', dir],
+      graceMs: 15_000,
+      env: childEnv(),
+      maxStdout: 8192,
+      maxStderr: 8192,
+    })
+    if (!init.ok) throw new Error(`git init failed: ${init.stderr.text.slice(0, 300)}`)
+    const add = await runCaptured(this.subprocess, {
+      argv: ['git', '-C', dir, 'remote', 'add', 'origin', `https://github.com/${owner}/${repo}.git`],
+      graceMs: 15_000,
+      env: childEnv(),
+      maxStdout: 8192,
+      maxStderr: 8192,
+    })
+    if (!add.ok) {
+      // A race with another process: recover with set-url.
+      const set = await runCaptured(this.subprocess, {
+        argv: ['git', '-C', dir, 'remote', 'set-url', 'origin', `https://github.com/${owner}/${repo}.git`],
+        graceMs: 15_000,
+        env: childEnv(),
+        maxStdout: 8192,
+        maxStderr: 8192,
+      })
+      if (!set.ok) throw new Error(`git remote setup failed: ${set.stderr.text.slice(0, 300)}`)
+    }
+    return dir
+  }
+
+  /**
+   * Fetch refs/pull/N/{head,merge} into refs/pr/N/* in the cache repo.
+   * A missing merge ref (conflicted PR) degrades, not fails.
+   */
+  async fetchPr(owner, repo, number, spec = {}) {
+    return withRepoLock(`${owner}/${repo}#${number}`, async () => {
+      const dir = await this.ensure(owner, repo)
+      const env = childEnv(proxyEnv(spec.proxy))
+      const head = await runCaptured(this.subprocess, {
+        argv: ['git', '-C', dir, 'fetch', '--quiet', '--no-tags', '--depth=64', 'origin', `refs/pull/${number}/head:refs/pr/${number}/head`],
+        graceMs: spec.graceMs ?? FETCH_GRACE_MS,
+        signal: spec.signal,
+        env,
+        maxStdout: 8192,
+        maxStderr: 16384,
+      })
+      const merge = await runCaptured(this.subprocess, {
+        argv: ['git', '-C', dir, 'fetch', '--quiet', '--no-tags', '--depth=64', 'origin', `refs/pull/${number}/merge:refs/pr/${number}/merge`],
+        graceMs: spec.graceMs ?? FETCH_GRACE_MS,
+        signal: spec.signal,
+        env,
+        maxStdout: 8192,
+        maxStderr: 16384,
+      })
+      if (!head.ok) {
+        throw new Error(`git fetch failed: ${(head.stderr.text || head.spawnError || `exit ${head.exitCode}`).slice(0, 400)}`)
+      }
+      return { dir, mergeFetched: merge.ok, mergeError: merge.ok ? null : merge.stderr.text.slice(0, 300) }
+    })
+  }
+
+  async fetchRef(owner, repo, ref, spec = {}) {
+    return withRepoLock(`${owner}/${repo}@${ref}`, async () => {
+      const dir = await this.ensure(owner, repo)
+      const out = await runCaptured(this.subprocess, {
+        argv: ['git', '-C', dir, 'fetch', '--quiet', '--no-tags', '--depth=1', 'origin', `+refs/heads/${ref}:refs/gh-router/${ref}`],
+        graceMs: spec.graceMs ?? FETCH_GRACE_MS,
+        signal: spec.signal,
+        env: childEnv(proxyEnv(spec.proxy)),
+        maxStdout: 8192,
+        maxStderr: 16384,
+      })
+      if (!out.ok) {
+        throw new Error(`git fetch failed: ${(out.stderr.text || out.spawnError || `exit ${out.exitCode}`).slice(0, 400)}`)
+      }
+      return { dir }
+    })
+  }
+
+  /** Fetch a full commit sha (GitHub allows reachable-sha wants). */
+  async fetchSha(owner, repo, sha, spec = {}) {
+    return withRepoLock(`${owner}/${repo}@${sha}`, async () => {
+      const dir = await this.ensure(owner, repo)
+      const out = await runCaptured(this.subprocess, {
+        argv: ['git', '-C', dir, 'fetch', '--quiet', '--no-tags', 'origin', sha],
+        graceMs: spec.graceMs ?? FETCH_GRACE_MS,
+        signal: spec.signal,
+        env: childEnv(proxyEnv(spec.proxy)),
+        maxStdout: 8192,
+        maxStderr: 16384,
+      })
+      if (!out.ok) {
+        throw new Error(`git fetch sha failed: ${(out.stderr.text || out.spawnError || `exit ${out.exitCode}`).slice(0, 400)}`)
+      }
+      return { dir }
+    })
+  }
+
+  /** Fetch the default branch head into FETCH_HEAD. */
+  async fetchHead(owner, repo, spec = {}) {
+    return withRepoLock(`${owner}/${repo}@HEAD`, async () => {
+      const dir = await this.ensure(owner, repo)
+      const out = await runCaptured(this.subprocess, {
+        argv: ['git', '-C', dir, 'fetch', '--quiet', '--no-tags', '--depth=1', 'origin', 'HEAD'],
+        graceMs: spec.graceMs ?? FETCH_GRACE_MS,
+        signal: spec.signal,
+        env: childEnv(proxyEnv(spec.proxy)),
+        maxStdout: 8192,
+        maxStderr: 16384,
+      })
+      if (!out.ok) {
+        throw new Error(`git fetch HEAD failed: ${(out.stderr.text || out.spawnError || `exit ${out.exitCode}`).slice(0, 400)}`)
+      }
+      return { dir }
+    })
+  }
+}
+
+// --------------------------------------------------------- local repo reads
+
+/** The session/local repo the git route may READ, or null. */
+export async function findLocalRepo(subprocess, cwd, owner, repo, extraRepos, localRepo) {
+  const candidates = []
+  if (typeof localRepo === 'string' && localRepo.trim().length > 0) candidates.push(localRepo.trim())
+  for (const r of extraRepos ?? []) candidates.push(r)
+  if (typeof cwd === 'string' && cwd.length > 0) candidates.push(cwd)
+  for (const candidate of candidates) {
+    if (candidate === undefined || candidate === null) continue
+    const rootOut = await runCaptured(subprocess, {
+      argv: ['git', '-C', candidate, 'rev-parse', '--show-toplevel'],
+      graceMs: 10_000,
+      env: childEnv(),
+      maxStdout: 8192,
+      maxStderr: 8192,
+    })
+    if (!rootOut.ok) continue
+    const root = rootOut.stdout.text.trim().replace(/\/+$/, '')
+    if (root.length === 0) continue
+    const urlOut = await runCaptured(subprocess, {
+      argv: ['git', '-C', root, 'config', '--get', 'remote.origin.url'],
+      graceMs: 10_000,
+      env: childEnv(),
+      maxStdout: 8192,
+      maxStderr: 8192,
+    })
+    if (!urlOut.ok) continue
+    const parsed = ownerRepoFromUrl(urlOut.stdout.text)
+    if (parsed !== null && parsed.owner.toLowerCase() === owner.toLowerCase() && parsed.repo.toLowerCase() === repo.toLowerCase()) {
+      return root
+    }
+  }
+  return null
+}
+
+/** Ref names the local repo may hold for a PR, in lookup order. */
+function prRefCandidates(number) {
+  return [
+    `refs/pull/${number}/merge`,
+    `refs/pull/${number}/head`,
+    `refs/remotes/origin/pull/${number}/merge`,
+    `refs/remotes/origin/pull/${number}/head`,
+    `refs/remotes/origin/pr/${number}`,
+  ]
+}
+
+async function resolveLocalRef(subprocess, repoDir, candidates) {
+  for (const ref of candidates) {
+    const out = await runCaptured(subprocess, {
+      argv: ['git', '-C', repoDir, 'rev-parse', '--verify', '--quiet', `${ref}^{commit}`],
+      graceMs: 10_000,
+      env: childEnv(),
+      maxStdout: 8192,
+      maxStderr: 8192,
+    })
+    if (out.ok && out.stdout.text.trim().length > 0) return ref
+  }
+  return null
+}
+
+/**
+ * Read PR commits/diff from a LOCAL repo without touching its network or
+ * working tree: rev-parse / log / merge-base / diff / show only.
+ */
+export async function readLocalPr(subprocess, repoDir, number, spec = {}) {
+  const found = await resolveLocalRef(subprocess, repoDir, prRefCandidates(number))
+  if (found === null) return null
+  const headRef = found
+  const mergeRef = found.endsWith('/merge') ? found : null
+
+  let base = null
+  if (mergeRef !== null) {
+    base = `${mergeRef}^1`
+  } else {
+    // Fall back to the merge base with origin/HEAD when available.
+    const headOut = await runCaptured(subprocess, {
+      argv: ['git', '-C', repoDir, 'symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD'],
+      graceMs: 10_000,
+      env: childEnv(),
+      maxStdout: 8192,
+      maxStderr: 8192,
+    })
+    if (headOut.ok) {
+      const defaultRef = headOut.stdout.text.trim()
+      const baseOut = await runCaptured(subprocess, {
+        argv: ['git', '-C', repoDir, 'merge-base', defaultRef, headRef],
+        graceMs: 10_000,
+        env: childEnv(),
+        maxStdout: 8192,
+        maxStderr: 8192,
+      })
+      if (baseOut.ok && baseOut.stdout.text.trim().length > 0) base = baseOut.stdout.text.trim()
+    }
+  }
+
+  const commitsOut = await runCaptured(subprocess, {
+    argv: ['git', '-C', repoDir, 'log', '--format=%H%x1f%an%x1f%ae%x1f%aI%x1f%s%x1f%b%x1e', base !== null ? `${base}..${headRef}` : `-50 ${headRef}`, '--no-merges'],
+    graceMs: spec.graceMs ?? READ_GRACE_MS,
+    signal: spec.signal,
+    env: childEnv(),
+    maxStdout: spec.maxStdout ?? 1048576,
+    maxStderr: 16384,
+  })
+  let diff = null
+  let diffTruncated = false
+  if (base !== null) {
+    const diffOut = await runCaptured(subprocess, {
+      argv: ['git', '-C', repoDir, 'diff', '--find-renames', base, headRef],
+      graceMs: spec.graceMs ?? READ_GRACE_MS,
+      signal: spec.signal,
+      env: childEnv(),
+      maxStdout: spec.maxDiffBytes ?? 1048576,
+      maxStderr: 16384,
+    })
+    if (diffOut.ok) {
+      diff = diffOut.stdout.text
+      diffTruncated = diffOut.stdout.truncated
+    }
+  }
+  return {
+    commits: parseCommitLog(commitsOut.ok ? commitsOut.stdout.text : ''),
+    commitsTruncated: commitsOut.stdout.truncated,
+    diff,
+    diffTruncated,
+    headRef,
+    baseRef: base,
+    notes: commitsOut.ok ? [] : [commitsOut.stderr.text.slice(0, 300)],
+  }
+}
+
+/** Read one file at a local ref with `git show` — read-only. */
+export async function readLocalFile(subprocess, repoDir, ref, path, spec = {}) {
+  const out = await runCaptured(subprocess, {
+    argv: ['git', '-C', repoDir, 'show', `${ref}:${path}`],
+    graceMs: spec.graceMs ?? READ_GRACE_MS,
+    signal: spec.signal,
+    env: childEnv(),
+    maxStdout: spec.maxStdout ?? 1048576,
+    maxStderr: 16384,
+  })
+  if (!out.ok) {
+    const err = new Error(`git show failed: ${out.stderr.text.slice(0, 300)}`)
+    err.code = 'GIT_FAILED'
+    throw err
+  }
+  return { content: out.stdout.text, truncated: out.stdout.truncated }
+}
+
+/** Read PR commits/diff from the plugin fetch cache (refs/pr/N/*). */
+export async function readCachePr(subprocess, dir, number, spec = {}) {
+  const mergeCheck = await runCaptured(subprocess, {
+    argv: ['git', '-C', dir, 'rev-parse', '--verify', '--quiet', `refs/pr/${number}/merge^{commit}`],
+    graceMs: 10_000,
+    env: childEnv(),
+    maxStdout: 4096,
+    maxStderr: 4096,
+  })
+  const hasMerge = mergeCheck.ok && mergeCheck.stdout.text.trim().length > 0
+  const headRef = `refs/pr/${number}/head`
+  const base = hasMerge ? `refs/pr/${number}/merge^1` : null
+
+  const commitsOut = await runCaptured(subprocess, {
+    argv: ['git', '-C', dir, 'log', '--format=%H%x1f%an%x1f%ae%x1f%aI%x1f%s%x1f%b%x1e', base !== null ? `${base}..${headRef}` : `-50 ${headRef}`, '--no-merges'],
+    graceMs: spec.graceMs ?? READ_GRACE_MS,
+    signal: spec.signal,
+    env: childEnv(),
+    maxStdout: spec.maxStdout ?? 1048576,
+    maxStderr: 16384,
+  })
+  let diff = null
+  let diffTruncated = false
+  if (base !== null) {
+    const diffOut = await runCaptured(subprocess, {
+      argv: ['git', '-C', dir, 'diff', '--find-renames', base, headRef],
+      graceMs: spec.graceMs ?? READ_GRACE_MS,
+      signal: spec.signal,
+      env: childEnv(),
+      maxStdout: spec.maxDiffBytes ?? 1048576,
+      maxStderr: 16384,
+    })
+    if (diffOut.ok) {
+      diff = diffOut.stdout.text
+      diffTruncated = diffOut.stdout.truncated
+    }
+  }
+  return {
+    commits: parseCommitLog(commitsOut.ok ? commitsOut.stdout.text : ''),
+    commitsTruncated: commitsOut.stdout.truncated,
+    diff,
+    diffTruncated,
+    headRef,
+    baseRef: base,
+    notes: commitsOut.ok ? [] : [commitsOut.stderr.text.slice(0, 300)],
+  }
+}
+
+/** Read one file at a ref in the plugin cache with `git show`. */
+export async function readCacheFile(subprocess, dir, ref, path, spec = {}) {
+  const out = await runCaptured(subprocess, {
+    argv: ['git', '-C', dir, 'show', `${ref}:${path}`],
+    graceMs: spec.graceMs ?? READ_GRACE_MS,
+    signal: spec.signal,
+    env: childEnv(),
+    maxStdout: spec.maxStdout ?? 1048576,
+    maxStderr: 16384,
+  })
+  if (!out.ok) {
+    const err = new Error(`git show failed: ${out.stderr.text.slice(0, 300)}`)
+    err.code = 'GIT_FAILED'
+    throw err
+  }
+  return { content: out.stdout.text, truncated: out.stdout.truncated }
+}
+
+/** Parse the %x1f/%x1e-delimited commit log into structured entries. */
+export function parseCommitLog(text) {
+  const entries = String(text ?? '').split('\x1e')
+  const out = []
+  for (const entry of entries) {
+    if (entry.trim().length === 0) continue
+    const parts = entry.split('\x1f')
+    if (parts.length < 5) continue
+    out.push({
+      sha: parts[0].trim().slice(0, 40),
+      author: parts[1].trim(),
+      email: parts[2].trim(),
+      date: parts[3].trim(),
+      message: parts.slice(4).join('\x1f').replace(/^\n+/, '').slice(0, 2000),
+    })
+  }
+  return out
+}