@xiaoming_z/dsh-git 0.0.0-stage → 0.3.0

package/index.js

@@ -0,0 +1,1320 @@
+/**
+ * `@xiaoming_z/dsh-git` — Host half of the DSH git panel.
+ *
+ * `status` / `log` / `diff` / `branches` / `review` for reads, and `stage` /
+ * `unstage` / `hunks` / `commit` / `checkout` / `pull` / `push` for writes, all
+ * over a plain prefix route on `ctx.webServer`. Going through the webserver
+ * route table instead of a Typert Remote is what keeps this package buildable
+ * outside the DSH monorepo: Remotes need descriptor codegen at build time, a
+ * route needs nothing but the `webServer` service.
+ *
+ * The route accepts an absolute repository path per request and refuses
+ * anything outside `allowedRoots`, because the webserver binds loopback with no
+ * authentication of its own. Writes additionally require the `x-dsh-git`
+ * header, since this prefix sits outside the `/api` browser-trust fence.
+ *
+ * @module @xiaoming_z/dsh-git
+ */
+import { execFile } from 'node:child_process'
+import { watch } from 'node:fs'
+import { realpath, stat } from 'node:fs/promises'
+import { join, resolve, sep } from 'node:path'
+
+/** Cordis plugin name. */
+export const name = 'dsh-git'
+/** Services this plugin resolves before its body runs. */
+export const inject = ['webServer']
+
+/** Prefix the whole route table hangs off. */
+const ROUTE_PREFIX = '/git-api'
+/** Git stdout can be large (a big diff); generous but bounded. */
+const MAX_BUFFER = 32 * 1024 * 1024
+/** Every git child gets a hard deadline so a wedged repo cannot pin the host. */
+const GIT_TIMEOUT_MS = 15_000
+/** Network commands get a longer one: a first fetch of a large repo is slow. */
+const GIT_NETWORK_TIMEOUT_MS = 180_000
+/** Cap on the git output echoed back for a network command. */
+const MAX_NETWORK_OUTPUT = 8 * 1024
+
+/**
+ * How a pull reconciles a diverged branch.
+ *
+ * Enumerated rather than passed through: the value reaches git's argv, and an
+ * open-ended string would be an option-injection hole. `ff-only` is the default
+ * because it is the only one that cannot rewrite history or invent a merge
+ * commit behind the user's back.
+ */
+const PULL_STRATEGIES = {
+  'ff-only': ['--ff-only'],
+  merge: ['--no-rebase'],
+  rebase: ['--rebase'],
+}
+/** Coalesce the burst of `.git` writes one git operation produces. */
+const WATCH_DEBOUNCE_MS = 120
+/** Newest-first commit page size when the caller does not ask for one. */
+const DEFAULT_LOG_LIMIT = 200
+/** Hard cap on one log page: the browser renders these, so it must stay finite. */
+const MAX_LOG_LIMIT = 2_000
+
+/** Field separator for the log pretty-format. */
+const FS = '\u001f'
+/** Record separator for the log pretty-format. */
+const RS = '\u001e'
+
+/**
+ * Run one git command in a repository.
+ * @param cwd - the repository working tree.
+ * @param args - git arguments, already split.
+ * @param options - `input` feeds stdin (for `git apply`); `allowExitCodes` lists
+ *   non-zero exits that mean success for the caller.
+ * @returns stdout on success.
+ */
+function git(cwd, args, options = {}) {
+  const { input, allowExitCodes = [], timeoutMs = GIT_TIMEOUT_MS } = options
+  return new Promise((resolvePromise, reject) => {
+    const child = execFile(
+      'git',
+      // git quotes non-ASCII paths as octal escapes by default
+      // (`"a/\345\256\211..."`), which makes every diff header for a CJK
+      // filename unreadable. Only output quoting is affected.
+      ['-c', 'core.quotePath=false', ...args],
+      {
+        cwd,
+        maxBuffer: MAX_BUFFER,
+        timeout: timeoutMs,
+        windowsHide: true,
+        // Without a TTY a credential prompt cannot be answered, and git would
+        // sit there until the timeout kills it. Refusing immediately turns a
+        // hang into a message the panel can show.
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+      },
+      (error, stdout, stderr) => {
+        if (error !== null) {
+          // Some commands signal a normal outcome with a non-zero exit:
+          // `diff --no-index` exits 1 when the inputs differ, which is the
+          // expected case for an untracked file.
+          if (typeof error.code === 'number' && allowExitCodes.includes(error.code)) {
+            resolvePromise(stdout)
+            return
+          }
+          // git does not agree with itself on which stream carries a
+          // diagnostic: `merge` conflicts land on stdout, `commit` with an
+          // empty index prints "nothing to commit" on stdout, while a bad
+          // revision goes to stderr. Check both before falling back to the
+          // useless "Command failed" text.
+          const detail = String(stderr ?? '').trim() || String(stdout ?? '').trim() || error.message
+          reject(new Error(detail))
+          return
+        }
+        resolvePromise(stdout)
+      },
+    )
+    if (input !== undefined) {
+      // If git exits before reading (a bad patch, an unknown option), the write
+      // fails with EPIPE; the exit callback owns the diagnosis.
+      child.stdin.on('error', () => {})
+      child.stdin.end(input)
+    }
+  })
+}
+
+/** Cap on a synthesised diff for an untracked file. */
+const MAX_UNTRACKED_DIFF_BYTES = 400 * 1024
+
+/**
+ * Split a unified diff into its file header and its hunks.
+ *
+ * `git apply` needs a patch assembled from a subset of hunks with the file
+ * header intact — exactly the split `git add -p` performs internally. Skipping
+ * an earlier hunk does not invalidate a later one's line numbers, because the
+ * index those numbers refer to is left untouched by the skipped hunk.
+ * @param text - a unified diff.
+ * @returns the header lines and one string per `@@` hunk.
+ */
+export function splitHunks(text) {
+  const header = []
+  const hunks = []
+  let current = null
+  for (const line of text.split('\n')) {
+    if (line.startsWith('@@')) {
+      if (current !== null) hunks.push(current.join('\n'))
+      current = [line]
+      continue
+    }
+    if (current === null) header.push(line)
+    else current.push(line)
+  }
+  if (current !== null) hunks.push(current.join('\n'))
+  // The final `split('\n')` element is an empty string when the diff ends with
+  // a newline; drop trailing newlines so reassembly adds exactly one.
+  return { header, hunks: hunks.map((hunk) => hunk.replace(/\n+$/, '')) }
+}
+
+/**
+ * Parse `git diff --numstat -z`.
+ *
+ * Records are `added\tdeleted\tpath` terminated by NUL. A rename emits an empty
+ * path field and then the two paths as their own NUL-separated fields; a binary
+ * file reports `-` for both counts. Fields are split on the FIRST TWO tabs
+ * rather than `split('\t')` because a path may itself contain a tab.
+ * @param raw - the command's raw stdout.
+ * @returns one entry per changed path.
+ */
+export function parseNumstat(raw) {
+  const files = []
+  const fields = raw.split('\0')
+  for (let i = 0; i < fields.length; i += 1) {
+    const record = fields[i]
+    if (record === '') continue
+    const first = record.indexOf('\t')
+    const second = first === -1 ? -1 : record.indexOf('\t', first + 1)
+    if (second === -1) continue
+    const added = record.slice(0, first)
+    const deleted = record.slice(first + 1, second)
+    let path = record.slice(second + 1)
+    let origPath = null
+    if (path === '') {
+      origPath = fields[i + 1] ?? null
+      path = fields[i + 2] ?? ''
+      i += 2
+    }
+    if (path === '') continue
+    files.push({
+      path,
+      origPath,
+      added: added === '-' ? null : Number(added),
+      deleted: deleted === '-' ? null : Number(deleted),
+      binary: added === '-',
+    })
+  }
+  return files
+}
+
+/**
+ * Parse `git diff --name-status -z` into a map keyed by the resulting path.
+ *
+ * Status and paths are all NUL-separated here (not tab), and a rename/copy
+ * carries two paths, so the record length depends on the status letter.
+ * @param raw - the command's raw stdout.
+ * @returns status by resulting path.
+ */
+export function parseNameStatus(raw) {
+  const byPath = new Map()
+  const fields = raw.split('\0')
+  for (let i = 0; i < fields.length; i += 1) {
+    const status = fields[i]
+    if (status === '') continue
+    if (status[0] === 'R' || status[0] === 'C') {
+      const from = fields[i + 1] ?? ''
+      const to = fields[i + 2] ?? ''
+      if (to !== '') byPath.set(to, { status: status[0], score: status.slice(1), origPath: from })
+      i += 2
+    } else {
+      const path = fields[i + 1] ?? ''
+      if (path !== '') byPath.set(path, { status: status[0], score: null, origPath: null })
+      i += 1
+    }
+  }
+  return byPath
+}
+
+/**
+ * Parse `git status --porcelain=v2 --branch -z`.
+ *
+ * Record shapes (the path field is last and may contain spaces, so it is
+ * re-joined rather than indexed):
+ *   `1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>`            ordinary change
+ *   `2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path>` rename/copy
+ *   `u <XY> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>`   unmerged
+ *   `? <path>`                                                untracked
+ *
+ * With `-z`, records are NUL-separated and a type-`2` record is followed by one
+ * extra NUL-separated field holding the original path.
+ *
+ * @param raw - the command's raw stdout.
+ * @returns the branch header plus files grouped by index/worktree position.
+ */
+export function parseStatusV2(raw) {
+  const branch = {
+    head: null,
+    oid: null,
+    upstream: null,
+    ahead: 0,
+    behind: 0,
+    detached: false,
+    initial: false,
+  }
+  const staged = []
+  const unstaged = []
+  const untracked = []
+  const conflicted = []
+  const fields = raw.split('\0')
+
+  for (let i = 0; i < fields.length; i += 1) {
+    const line = fields[i]
+    if (line === '') continue
+
+    if (line.startsWith('# ')) {
+      const [key, ...rest] = line.slice(2).split(' ')
+      const value = rest.join(' ')
+      if (key === 'branch.oid') {
+        branch.oid = value === '(initial)' ? null : value
+        branch.initial = value === '(initial)'
+      } else if (key === 'branch.head') {
+        branch.detached = value === '(detached)'
+        branch.head = branch.detached ? null : value
+      } else if (key === 'branch.upstream') {
+        branch.upstream = value
+      } else if (key === 'branch.ab') {
+        const [, ahead, behind] = /^\+(\d+) -(\d+)$/.exec(value) ?? []
+        branch.ahead = Number(ahead ?? 0)
+        branch.behind = Number(behind ?? 0)
+      }
+      continue
+    }
+
+    const kind = line[0]
+    if (kind === '?') {
+      // Untracked entries carry the same field set as every other kind. An
+      // absent `origPath` used to reach the browser as `undefined`, where a
+      // `!== null` guard happily rendered the literal text "undefined".
+      untracked.push({ path: line.slice(2), index: '?', worktree: '?', origPath: null })
+      continue
+    }
+    if (kind !== '1' && kind !== '2' && kind !== 'u') continue
+
+    const parts = line.split(' ')
+    // Where the path starts depends on the record kind (see the shapes above).
+    const pathStart = kind === '1' ? 8 : kind === '2' ? 9 : 10
+    const xy = parts[1] ?? '..'
+    const x = xy[0]
+    const y = xy[1]
+    const entry = {
+      path: parts.slice(pathStart).join(' '),
+      index: x,
+      worktree: y,
+      origPath: null,
+    }
+    if (kind === '2') {
+      entry.origPath = fields[i + 1] ?? null
+      i += 1
+    }
+
+    if (kind === 'u') {
+      conflicted.push(entry)
+      continue
+    }
+    if (x !== '.' && x !== ' ') staged.push(entry)
+    if (y !== '.' && y !== ' ') unstaged.push(entry)
+  }
+
+  return { branch, staged, unstaged, untracked, conflicted }
+}
+
+/**
+ * Parse the `%x1f`/`%x1e`-delimited log produced by {@link GitService.log}.
+ * @param raw - the command's raw stdout.
+ * @returns commits newest-first.
+ */
+export function parseLog(raw) {
+  const commits = []
+  for (const chunk of raw.split(RS)) {
+    // `format:` separates entries with a newline, so every record but the first
+    // arrives with a leading one. Only leading newlines are stripped: the
+    // subject is the last field and may legitimately end in spaces.
+    const record = chunk.replace(/^[\r\n]+/, '')
+    if (record === '') continue
+    const [hash, parents, authorName, authorEmail, authoredAt, ...subject] = record.split(FS)
+    commits.push({
+      hash,
+      parents: parents === '' ? [] : parents.split(' ').filter(Boolean),
+      author: authorName,
+      email: authorEmail,
+      // Seconds since epoch is what git prints; the browser wants milliseconds.
+      at: Number(authoredAt) * 1000,
+      // The subject is last so an embedded separator cannot shift the fields.
+      subject: subject.join(FS),
+    })
+  }
+  return commits
+}
+
+/**
+ * Answer one request as JSON.
+ * @param res - the node response.
+ * @param status - HTTP status code.
+ * @param payload - JSON-serializable body.
+ */
+function send(res, status, payload) {
+  const body = JSON.stringify(payload)
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(body),
+  })
+  res.end(body)
+}
+
+/** Header a write request must carry; see {@link assertNotCrossSite}. */
+const WRITE_HEADER = 'x-dsh-git'
+
+/** Cap on a request body. A commit message is the only body this API accepts. */
+const MAX_BODY_BYTES = 64 * 1024
+
+/**
+ * Read and parse a JSON request body.
+ * @param req - the node request.
+ * @returns the parsed object, or `{}` for an empty body.
+ */
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = []
+    let size = 0
+    req.on('data', (chunk) => {
+      size += chunk.length
+      if (size > MAX_BODY_BYTES) {
+        reject(new Error(`request body exceeds ${MAX_BODY_BYTES} bytes`))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => {
+      const raw = Buffer.concat(chunks).toString('utf8').trim()
+      if (raw === '') {
+        resolve({})
+        return
+      }
+      try {
+        const parsed = JSON.parse(raw)
+        resolve(parsed !== null && typeof parsed === 'object' ? parsed : {})
+      } catch {
+        reject(new Error('request body is not valid JSON'))
+      }
+    })
+    req.on('error', reject)
+  })
+}
+
+/**
+ * Validate a revision the browser wants git to act on.
+ *
+ * A ref goes straight into argv, so a leading `-` would be read as an option —
+ * `git checkout -f` instead of checking out a branch named `-f`. Reads tolerate
+ * a bad ref by falling back to HEAD; writes must refuse loudly instead.
+ * @param value - the caller's ref.
+ * @param label - field name for the error message.
+ * @returns the ref.
+ */
+function requireRef(value, label) {
+  if (typeof value !== 'string' || value.trim() === '') throw new Error(`${label} must not be empty`)
+  if (value.startsWith('-')) throw new Error(`${label} must not start with "-": ${JSON.stringify(value)}`)
+  return value
+}
+
+/**
+ * Resolve the caller's declared action list.
+ * @param value - the request's `files` field.
+ * @returns a non-empty array of pathspecs.
+ */
+function requireFiles(value) {
+  if (!Array.isArray(value) || value.length === 0) throw new Error('files must be a non-empty array')
+  for (const file of value) {
+    if (typeof file !== 'string' || file === '') throw new Error('every entry in files must be a non-empty string')
+  }
+  return value
+}
+
+/**
+ * Reject a write that did not come from the panel.
+ *
+ * The webserver binds loopback and adds no authentication of its own, and this
+ * route table is deliberately *outside* the `/api` browser-trust fence — which
+ * is what lets a plugin own it. That combination means a write endpoint is
+ * reachable by any page the user has open. Requiring a custom header is the
+ * defence: a cross-origin form or `fetch` cannot set one without triggering a
+ * CORS preflight, and this server answers no preflight and sends no CORS
+ * headers, so the browser blocks the request before it arrives.
+ * @param req - the node request.
+ */
+function assertNotCrossSite(req) {
+  if (req.headers[WRITE_HEADER] === undefined) {
+    throw new Error(`refusing a write without the ${WRITE_HEADER} header (cross-site protection)`)
+  }
+}
+
+/**
+ * Parse `git show --name-status` into a commit header plus its changed files.
+ * @param raw - the command's raw stdout.
+ * @returns the commit and its files, or null when nothing parsed.
+ */
+export function parseCommitFiles(raw) {
+  const [header, ...lines] = raw.split('\n')
+  const [hash, author, authoredAt, ...subject] = header.split(FS)
+  if (hash === undefined || hash === '') return null
+  const files = []
+  for (const line of lines) {
+    if (line.trim() === '') continue
+    const [status, ...rest] = line.split('\t')
+    if (status === undefined || rest.length === 0) continue
+    // A rename/copy line carries both paths; the others carry one. Only R/C
+    // carry a trailing similarity score — a merge's combined status ("MM")
+    // would otherwise be misread as one.
+    const scored = status[0] === 'R' || status[0] === 'C'
+    files.push({
+      status: status[0],
+      score: scored && status.length > 1 ? status.slice(1) : null,
+      path: rest[rest.length - 1],
+      origPath: rest.length > 1 ? rest[0] : null,
+    })
+  }
+  return {
+    commit: { hash, author, at: Number(authoredAt) * 1000, subject: subject.join(FS) },
+    files,
+  }
+}
+
+/**
+ * Per-repository git state: a small read cache plus the `.git` watcher that
+ * invalidates it.
+ *
+ * This is the seam that makes the panel feel like an IDE rather than a form
+ * submit: the browser never waits on a cold `git status`, and any git operation
+ * taken outside the panel (a shell commit, an IDE checkout) drops the cache
+ * instead of leaving a stale tree on screen.
+ */
+class GitService {
+  #allowedRoots
+  #allowAny
+  #defaultRoot
+  #canonicalRoots = null
+  #cache = new Map()
+  #watchers = new Map()
+  #timers = new Map()
+
+  #knownWorkspaces
+
+  /**
+   * @param config - the row's config from `cordis.patch.yml`.
+   * @param knownWorkspaces - returns directories the harness itself considers
+   *   workspaces; they are trusted in addition to `allowedRoots`.
+   */
+  constructor(config = {}, knownWorkspaces = () => []) {
+    const roots = Array.isArray(config.allowedRoots) ? config.allowedRoots : [process.cwd()]
+    this.#allowAny = roots.includes('*')
+    this.#allowedRoots = roots.filter((root) => root !== '*').map((root) => resolve(root))
+    this.#defaultRoot = typeof config.defaultRoot === 'string' ? resolve(config.defaultRoot) : process.cwd()
+    this.#knownWorkspaces = knownWorkspaces
+  }
+
+  /**
+   * Canonicalize the allowlist once, lazily.
+   *
+   * The request path is canonicalized with `realpath` before the prefix check,
+   * so the allowlist must be canonicalized the same way or the two never
+   * compare equal: on macOS `/tmp` and `/var` are symlinks into `/private`, and
+   * a project reached through a symlinked directory has the same problem.
+   * Canonicalizing lazily (rather than in the constructor) keeps `apply()`
+   * synchronous and tolerates a configured root that does not exist yet.
+   * @returns the canonical allowlist.
+   */
+  async #canonicalAllowlist() {
+    if (this.#canonicalRoots === null) {
+      this.#canonicalRoots = (async () => {
+        const roots = []
+        for (const root of this.#allowedRoots) {
+          // A root that cannot be canonicalized is kept as-is, so a typo in the
+          // config matches nothing rather than throwing at every request.
+          roots.push(await realpath(root).catch(() => root))
+        }
+        return roots
+      })()
+    }
+    return await this.#canonicalRoots
+  }
+
+  /**
+   * Canonicalize the registered workspace roots.
+   *
+   * Not memoized: a workspace can be added or removed while the panel is open,
+   * and the list is short enough that re-canonicalizing per request is cheap.
+   * @returns the canonical workspace paths.
+   */
+  async #canonicalWorkspaces() {
+    let paths
+    try {
+      paths = this.#knownWorkspaces()
+    } catch {
+      return []
+    }
+    if (!Array.isArray(paths)) return []
+    const roots = []
+    for (const path of paths) {
+      if (typeof path !== 'string' || path === '') continue
+      roots.push(await realpath(path).catch(() => null))
+    }
+    return roots.filter((root) => root !== null)
+  }
+
+  /**
+   * Canonicalize and vet a caller-supplied repository path.
+   * @param input - the `root` query parameter, or undefined to use the default.
+   * @returns the canonical repository root.
+   */
+  async resolveRoot(input) {
+    const candidate = typeof input === 'string' && input.trim() !== '' ? resolve(input) : this.#defaultRoot
+    const real = await realpath(candidate)
+    if (!(await stat(real)).isDirectory()) throw new Error(`${real} is not a directory`)
+    if (!this.#allowAny) {
+      const allowed = await this.#canonicalAllowlist()
+      // Directories the harness already treats as workspaces are trusted too.
+      // That is what makes the panel follow the session's repository without
+      // widening `allowedRoots` to every path on the machine: the user opted
+      // into these by opening them.
+      const workspaces = await this.#canonicalWorkspaces()
+      const ok = (root) => real === root || real.startsWith(root + sep)
+      if (!allowed.some(ok) && !workspaces.some(ok)) {
+        throw new Error(
+          `refusing to inspect ${real}: outside allowedRoots and not a known workspace ` +
+            '(add it to the row config, or use "*")',
+        )
+      }
+    }
+    try {
+      await stat(join(real, '.git'))
+    } catch {
+      throw new Error(`${real} is not a git working tree`)
+    }
+    // The watcher is set up in the background: a repository that cannot be
+    // watched still works, it just refreshes on demand instead of on change.
+    void this.#watch(real)
+    return real
+  }
+
+  /**
+   * The working tree's status, cached until the watcher invalidates it.
+   * @param root - canonical repository root.
+   * @returns parsed porcelain-v2 status.
+   */
+  async status(root) {
+    return await this.#cached(`${root}\u0000status`, async () =>
+      parseStatusV2(await git(root, ['status', '--porcelain=v2', '--branch', '--untracked-files=all', '-z'])),
+    )
+  }
+
+  /**
+   * A page of commits, newest-first, in topological order so the client's lane
+   * assignment does not have to cope with a parent arriving after its child.
+   * @param root - canonical repository root.
+   * @param limit - requested page size, clamped to [1, MAX_LOG_LIMIT].
+   * @param ref - optional branch/ref to walk instead of HEAD.
+   * @returns parsed commits.
+   */
+  async log(root, limit, ref) {
+    const size = Math.min(Math.max(1, Number(limit) || DEFAULT_LOG_LIMIT), MAX_LOG_LIMIT)
+    // A ref is passed as a revision argument, so a leading `-` would be read as
+    // an option. Reject it rather than letting a caller reach git's flag space.
+    const revision = typeof ref === 'string' && ref !== '' && !ref.startsWith('-') ? ref : undefined
+    return await this.#cached(`${root}\u0000log\u0000${size}\u0000${revision ?? ''}`, async () =>
+      parseLog(
+        await git(root, [
+          'log',
+          `--max-count=${size}`,
+          '--topo-order',
+          `--pretty=format:%H${FS}%P${FS}%an${FS}%ae${FS}%at${FS}%s${RS}`,
+          ...(revision === undefined ? [] : [revision]),
+        ]),
+      ),
+    )
+  }
+
+  /**
+   * A unified diff. Deliberately uncached: it is the pane the user is actively
+   * editing against, and a stale diff is worse than a second git call.
+   * @param root - canonical repository root.
+   * @param file - optional pathspec.
+   * @param staged - diff the index against HEAD instead of the worktree.
+   * @param untracked - synthesise an all-added diff for an untracked file.
+   * @param since - diff one path against this marker instead of the index.
+   * @returns raw unified diff text.
+   */
+  async diff(root, file, staged, untracked, since) {
+    if (since !== undefined && since !== null && since !== '') {
+      const marker = requireRef(since, 'since')
+      const args = ['diff', '--no-color', '--no-ext-diff', marker]
+      if (typeof file === 'string' && file !== '') args.push('--', file)
+      return await git(root, args)
+    }
+    if (untracked === true) return await this.#untrackedDiff(root, file)
+    const args = ['diff', '--no-color', '--no-ext-diff']
+    if (staged === true) args.push('--cached')
+    if (typeof file === 'string' && file !== '') args.push('--', file)
+    return await git(root, args)
+  }
+
+  /**
+   * An untracked file has no diff against the index, so one is synthesised by
+   * diffing it against the null device. `--no-index` exits 1 whenever the
+   * inputs differ, which is the normal case here and is accepted.
+   * @param root - canonical repository root.
+   * @param file - path relative to the repository root.
+   * @returns the synthesised diff, truncated when the file is very large.
+   */
+  async #untrackedDiff(root, file) {
+    if (typeof file !== 'string' || file === '') throw new Error('untracked diff needs a file path')
+    // The path arrives from the browser, so it is confined to the repository
+    // before it reaches git at all.
+    const absolute = resolve(root, file)
+    if (absolute !== root && !absolute.startsWith(root + sep)) {
+      throw new Error(`${file} is outside the repository`)
+    }
+    const info = await stat(absolute).catch(() => null)
+    if (info === null || !info.isFile()) throw new Error(`${file} does not exist or is not a regular file`)
+    const nullDevice = process.platform === 'win32' ? 'NUL' : '/dev/null'
+    const text = await git(root, ['diff', '--no-color', '--no-ext-diff', '--no-index', '--', nullDevice, file], {
+      allowExitCodes: [1],
+    })
+    if (Buffer.byteLength(text) <= MAX_UNTRACKED_DIFF_BYTES) return text
+    return `${text.slice(0, MAX_UNTRACKED_DIFF_BYTES)}\n… diff truncated: the file is too large to show in full\n`
+  }
+
+  /**
+   * Stage (or unstage) a chosen subset of a file's hunks.
+   *
+   * The patch is rebuilt from the file header plus the selected hunks and piped
+   * to `git apply --cached`, which is how `git add -p` / `git reset -p` work.
+   * @param root - canonical repository root.
+   * @param file - path relative to the repository root.
+   * @param indices - zero-based hunk indices, in diff order.
+   * @param staged - true unstages the selected hunks from the index.
+   */
+  async applyHunks(root, file, indices, staged) {
+    const text = await this.diff(root, file, staged === true, false)
+    const { header, hunks } = splitHunks(text)
+    if (hunks.length === 0) throw new Error('this file has no hunks to apply')
+    const picked = []
+    for (const index of Array.isArray(indices) ? indices : []) {
+      if (!Number.isInteger(index) || index < 0 || index >= hunks.length) {
+        throw new Error(`hunk index out of range: ${JSON.stringify(index)} (this file has ${hunks.length})`)
+      }
+      picked.push(hunks[index])
+    }
+    if (picked.length === 0) throw new Error('no hunks selected')
+    const patch = `${[...header, ...picked].join('\n')}\n`
+    const args = ['apply', '--cached', '--whitespace=nowarn', '--recount']
+    if (staged === true) args.push('--reverse')
+    args.push('-')
+    await git(root, args, { input: patch })
+    this.invalidate(root)
+  }
+
+  /**
+   * Local and remote branches, split for the panel's branch tree.
+   * @param root - canonical repository root.
+   * @returns `{local, remote}`; a remote entry carries its remote and branch name.
+   */
+  async branches(root) {
+    return await this.#cached(`${root}\u0000branches`, async () => {
+      // `git branch --format` supports only `%(field)` placeholders — the
+      // `%x1f` escape is a pretty-format feature and would come through
+      // literally here. A literal TAB is the safe separator instead:
+      // check-ref-format forbids every ASCII control character in a refname.
+      const raw = await git(root, [
+        'branch',
+        '--all',
+        `--format=%(HEAD)\t%(refname)\t%(refname:short)\t%(upstream:short)\t%(objectname:short)`,
+      ])
+      const local = []
+      const remote = []
+      for (const line of raw.split('\n')) {
+        if (line === '') continue
+        const [head, refname, short, upstream, oid] = line.split('\t')
+        if (refname.startsWith('refs/heads/')) {
+          local.push({ name: short, current: head.trim() === '*', upstream: upstream === '' ? null : upstream, oid })
+        } else if (refname.startsWith('refs/remotes/')) {
+          // Derive everything from the full refname, never from
+          // `%(refname:short)`: for the symbolic `refs/remotes/origin/HEAD`
+          // git shortens to plain `origin`, so a short-name check would let it
+          // through as a bogus branch named after the remote.
+          if (refname.endsWith('/HEAD')) continue
+          const rest = refname.slice('refs/remotes/'.length)
+          const slash = rest.indexOf('/')
+          remote.push({
+            name: rest,
+            remote: slash === -1 ? '' : rest.slice(0, slash),
+            branch: slash === -1 ? rest : rest.slice(slash + 1),
+            oid,
+          })
+        }
+      }
+      return { local, remote, head: local.find((branch) => branch.current)?.name ?? null }
+    })
+  }
+
+  /**
+   * One commit's header plus the files it touched.
+   * @param root - canonical repository root.
+   * @param hash - the commit to inspect.
+   * @returns the parsed commit detail, or null when the hash resolves to nothing.
+   */
+  async commitDetail(root, hash) {
+    return await this.#cached(`${root}\u0000commit\u0000${hash}`, async () => {
+      const raw = await git(root, [
+        'show',
+        '--name-status',
+        '--no-color',
+        '--format=%H' + FS + '%an' + FS + '%at' + FS + '%s',
+        hash,
+      ])
+      return parseCommitFiles(raw)
+    })
+  }
+
+  /**
+   * The patch a single commit applied, optionally limited to one path.
+   * @param root - canonical repository root.
+   * @param hash - the commit to show.
+   * @param file - optional pathspec.
+   * @returns raw unified diff text.
+   */
+  async show(root, hash, file) {
+    const args = ['show', '--no-color', '--no-ext-diff', '--format=', hash]
+    if (typeof file === 'string' && file !== '') args.push('--', file)
+    return await git(root, args)
+  }
+
+  /**
+   * Stage paths.
+   * @param root - canonical repository root.
+   * @param files - pathspecs to stage.
+   */
+  async stage(root, files) {
+    // `-A` so a staged deletion is recorded too, which plain `git add` handles
+    // only from git 2.x with `--all` explicitly.
+    await git(root, ['add', '-A', '--', ...files])
+    this.invalidate(root)
+  }
+
+  /**
+   * Unstage paths, leaving the worktree untouched.
+   * @param root - canonical repository root.
+   * @param files - pathspecs to unstage.
+   */
+  async unstage(root, files) {
+    // `reset` rather than `restore --staged`: it also drops a newly added file
+    // out of the index, which `restore` refuses because the path is not in HEAD.
+    await git(root, ['reset', '-q', 'HEAD', '--', ...files])
+    this.invalidate(root)
+  }
+
+  /**
+   * Commit what is staged.
+   * @param root - canonical repository root.
+   * @param message - the commit message.
+   * @returns the new commit's short hash.
+   */
+  async createCommit(root, message) {
+    await git(root, ['commit', '-m', message])
+    this.invalidate(root)
+    return (await git(root, ['rev-parse', '--short', 'HEAD'])).trim()
+  }
+
+  /**
+   * Check out a ref, optionally creating a branch first.
+   *
+   * A branch name is validated by git itself (`check-ref-format --branch`)
+   * rather than by a hand-rolled pattern: the rules are long, they have changed
+   * between versions, and git is the authority on them.
+   * @param root - canonical repository root.
+   * @param ref - the branch or commit-ish to check out, or the start point.
+   * @param create - when given, create this branch at `ref` and switch to it.
+   */
+  async checkout(root, ref, create) {
+    const target = requireRef(ref, 'ref')
+    if (create === undefined || create === null || create === '') {
+      await git(root, ['checkout', target])
+    } else {
+      const name = requireRef(create, 'branch name')
+      // Non-zero exit means git rejected the name; its own stderr is the message.
+      await git(root, ['check-ref-format', '--branch', name])
+      await git(root, ['checkout', '-b', name, target])
+    }
+    this.invalidate(root)
+  }
+
+  /**
+   * Fetch and integrate the current branch's upstream.
+   *
+   * Reports whether HEAD actually moved rather than parsing git's message: the
+   * wording is localized and has changed between versions, while the two hashes
+   * are unambiguous.
+   * @param root - canonical repository root.
+   * @param strategy - one of {@link PULL_STRATEGIES}.
+   * @returns `{changed, before, after, output}`.
+   */
+  async pull(root, strategy) {
+    const args = PULL_STRATEGIES[strategy]
+    if (args === undefined) {
+      throw new Error(
+        `unknown pull strategy ${JSON.stringify(strategy)} (expected one of ${Object.keys(PULL_STRATEGIES).join(', ')})`,
+      )
+    }
+    const head = async () =>
+      await git(root, ['rev-parse', 'HEAD'], { allowExitCodes: [128] })
+        .then((value) => value.trim())
+        .catch(() => '')
+    const before = await head()
+    const output = await git(root, ['pull', ...args], { timeoutMs: GIT_NETWORK_TIMEOUT_MS })
+    const after = await head()
+    this.invalidate(root)
+    return {
+      changed: before !== after,
+      before: before.slice(0, 7),
+      after: after.slice(0, 7),
+      output:
+        output.length > MAX_NETWORK_OUTPUT ? `${output.slice(0, MAX_NETWORK_OUTPUT)}\n… output truncated` : output,
+    }
+  }
+
+  /**
+   * Everything that changed since a marker commit, committed or not.
+   *
+   * The marker is compared against the WORKING TREE rather than HEAD, so an
+   * agent that left changes uncommitted is not hidden by a review view that
+   * only looks at history.
+   * @param root - canonical repository root.
+   * @param since - the marker commit-ish.
+   * @returns commits since the marker, per-file stats, and totals.
+   */
+  async review(root, since) {
+    const marker = requireRef(since, 'since')
+    // A rebase can delete the marker commit; resolving first turns that into a
+    // clear error instead of an empty-looking review.
+    await git(root, ['rev-parse', '--verify', `${marker}^{commit}`])
+    const [logRaw, nameRaw, numRaw, headRaw] = await Promise.all([
+      git(root, [
+        'log',
+        '--topo-order',
+        '--max-count=500',
+        `--pretty=format:%H${FS}%P${FS}%an${FS}%ae${FS}%at${FS}%s${RS}`,
+        `${marker}..HEAD`,
+      ]),
+      git(root, ['diff', '--name-status', '-z', '--find-renames', marker]),
+      git(root, ['diff', '--numstat', '-z', '--find-renames', marker]),
+      git(root, ['rev-parse', '--short', 'HEAD']),
+    ])
+    const statuses = parseNameStatus(nameRaw)
+    const files = parseNumstat(numRaw).map((entry) => ({
+      ...entry,
+      status: statuses.get(entry.path)?.status ?? null,
+    }))
+    const totals = files.reduce(
+      (sum, file) => ({
+        files: sum.files + 1,
+        added: sum.added + (file.added ?? 0),
+        deleted: sum.deleted + (file.deleted ?? 0),
+        binary: sum.binary + (file.binary ? 1 : 0),
+      }),
+      { files: 0, added: 0, deleted: 0, binary: 0 },
+    )
+    return { marker, head: headRaw.trim(), commits: parseLog(logRaw), files, totals }
+  }
+
+  /**
+   * Push the current branch, publishing it first when it has no upstream.
+   *
+   * Reports the upstream's hash before and after rather than parsing git's
+   * wording, for the same reason as {@link pull}: messages are localized while
+   * a hash is not. Before the first push of a branch there is no upstream at
+   * all, which reads as an empty "before" and therefore as a change.
+   * @param root - canonical repository root.
+   * @param setUpstream - create/point the upstream as part of the push.
+   * @returns `{branch, remote, published, changed, before, after, output}`.
+   */
+  async push(root, setUpstream) {
+    const branch = (await git(root, ['rev-parse', '--abbrev-ref', 'HEAD'])).trim()
+    if (branch === 'HEAD') throw new Error('cannot push: HEAD is detached')
+    const args = ['push']
+    let remote = null
+    if (setUpstream === true) {
+      remote = await this.#publishRemote(root)
+      args.push('--set-upstream', remote, branch)
+    }
+    const before = await this.#upstreamHash(root)
+    const output = await git(root, args, { timeoutMs: GIT_NETWORK_TIMEOUT_MS })
+    const after = await this.#upstreamHash(root)
+    this.invalidate(root)
+    return {
+      branch,
+      remote,
+      published: setUpstream === true,
+      changed: before !== after,
+      before: before.slice(0, 7),
+      after: after.slice(0, 7),
+      output:
+        output.length > MAX_NETWORK_OUTPUT
+          ? `${output.slice(0, MAX_NETWORK_OUTPUT)}\n… output truncated`
+          : output,
+    }
+  }
+
+  /**
+   * The hash the branch's upstream points at, or an empty string when the
+   * branch has no upstream yet.
+   * @param root - canonical repository root.
+   * @returns the hash, or ''.
+   */
+  async #upstreamHash(root) {
+    try {
+      return (await git(root, ['rev-parse', '@{upstream}'])).trim()
+    } catch {
+      return ''
+    }
+  }
+
+  /**
+   * Choose the remote to publish a branch to.
+   *
+   * `origin` is the overwhelming convention, and a single remote is
+   * unambiguous. Anything else is refused instead of guessed: pushing to the
+   * wrong remote is not something to discover afterwards.
+   * @param root - canonical repository root.
+   * @returns the remote name.
+   */
+  async #publishRemote(root) {
+    const remotes = (await git(root, ['remote']))
+      .split('\n')
+      .map((name) => name.trim())
+      .filter((name) => name !== '')
+    if (remotes.includes('origin')) return 'origin'
+    if (remotes.length === 1) return remotes[0]
+    if (remotes.length === 0) throw new Error('no remote to publish to')
+    throw new Error(`several remotes and none is "origin"; publish from a terminal (${remotes.join(', ')})`)
+  }
+
+  /**
+   * Drop every cached entry for one repository.
+   *
+   * Public because a write through this API must not wait for the filesystem
+   * watcher's debounce to expire: the panel refreshes immediately after its own
+   * mutation and would otherwise read the state it just replaced.
+   * @param root - canonical repository root.
+   */
+  invalidate(root) {
+    this.#invalidate(root)
+  }
+
+  /**
+   * Read-through cache keyed by root and query shape.
+   * @param key - cache key.
+   * @param produce - the git call to run on a miss.
+   * @returns the cached or freshly produced value.
+   */
+  async #cached(key, produce) {
+    const hit = this.#cache.get(key)
+    if (hit !== undefined) return hit
+    const value = await produce()
+    this.#cache.set(key, value)
+    return value
+  }
+
+  /**
+   * Drop every cached entry for one repository.
+   * @param root - canonical repository root.
+   */
+  #invalidate(root) {
+    const prefix = `${root}\u0000`
+    for (const key of [...this.#cache.keys()]) {
+      if (key.startsWith(prefix)) this.#cache.delete(key)
+    }
+  }
+
+  /**
+   * Where a repository keeps its git directory.
+   *
+   * `<root>/.git` is a directory in a plain repository, but it is a FILE in a
+   * linked worktree (`git worktree add`) and in a submodule — a one-line
+   * pointer to the real directory (`…/.git/worktrees/<name>`). Watching that
+   * file means watching a file that never changes: a checkout in the worktree
+   * rewrites `<gitdir>/HEAD`, far away, and the cache would keep serving the
+   * old branch forever.
+   *
+   * git itself knows the answer, and knows it for every layout —
+   * `--separate-git-dir`, `core.worktree`, submodules, worktrees.
+   * @param root - canonical repository root.
+   * @returns the git directory, or the conventional path when git cannot say.
+   */
+  async #gitDir(root) {
+    try {
+      const out = await git(root, ['rev-parse', '--absolute-git-dir'])
+      const dir = out.trim()
+      if (dir !== '') return dir
+    } catch {
+      /* older git, or an exotic layout: fall back to the conventional path */
+    }
+    return join(root, '.git')
+  }
+
+  /**
+   * Attach a best-effort watcher to a repository's git directory.
+   *
+   * Non-recursive on purpose: `HEAD`, `index` and the mtime of `refs` all sit
+   * at this level, which is what a commit or checkout touches. Failing to
+   * watch is not fatal — it degrades the panel to refresh-on-demand, which is
+   * why the catch is silent.
+   * @param root - canonical repository root.
+   */
+  async #watch(root) {
+    if (this.#watchers.has(root)) return
+    try {
+      const dir = await this.#gitDir(root)
+      this.#watchers.set(
+        root,
+        watch(dir, { persistent: false }, () => this.#scheduleInvalidate(root)),
+      )
+    } catch {
+      /* not watchable (permissions, exotic filesystem): fall back to manual refresh */
+    }
+  }
+
+  /**
+   * Debounce the write burst one git operation emits.
+   * @param root - canonical repository root.
+   */
+  #scheduleInvalidate(root) {
+    const pending = this.#timers.get(root)
+    if (pending !== undefined) clearTimeout(pending)
+    this.#timers.set(
+      root,
+      setTimeout(() => {
+        this.#timers.delete(root)
+        this.#invalidate(root)
+      }, WATCH_DEBOUNCE_MS),
+    )
+  }
+
+  /** Release every watcher, timer and cache entry. */
+  dispose() {
+    for (const timer of this.#timers.values()) clearTimeout(timer)
+    this.#timers.clear()
+    for (const watcher of this.#watchers.values()) {
+      try {
+        watcher.close()
+      } catch {
+        /* already closed */
+      }
+    }
+    this.#watchers.clear()
+    this.#cache.clear()
+  }
+}
+
+/**
+ * Dispatch one request under {@link ROUTE_PREFIX}.
+ * @param ctx - the plugin context, for logging.
+ * @param service - the git state holder.
+ * @param req - the node request.
+ * @param res - the node response.
+ */
+async function handle(ctx, service, req, res) {
+  const method = req.method ?? 'GET'
+  if (method !== 'GET' && method !== 'POST') {
+    send(res, 405, { ok: false, error: `method ${method} not allowed` })
+    return
+  }
+
+  let url
+  try {
+    url = new URL(req.url ?? '/', 'http://localhost')
+  } catch {
+    send(res, 400, { ok: false, error: 'malformed request url' })
+    return
+  }
+
+  const route = url.pathname.slice(ROUTE_PREFIX.length) || '/'
+  const params = url.searchParams
+
+  try {
+    if (method === 'GET') {
+      switch (route) {
+        case '/health':
+          send(res, 200, { ok: true, data: { service: name, pid: process.pid, writes: true } })
+          return
+
+        case '/status': {
+          const root = await service.resolveRoot(params.get('root') ?? undefined)
+          send(res, 200, { ok: true, data: { root, ...(await service.status(root)) } })
+          return
+        }
+
+        case '/log': {
+          const root = await service.resolveRoot(params.get('root') ?? undefined)
+          const commits = await service.log(root, params.get('limit'), params.get('ref') ?? undefined)
+          send(res, 200, { ok: true, data: { root, ref: params.get('ref') ?? null, commits } })
+          return
+        }
+
+        case '/diff': {
+          const root = await service.resolveRoot(params.get('root') ?? undefined)
+          const staged = params.get('staged') === '1'
+          const untracked = params.get('untracked') === '1'
+          const since = params.get('since')
+          const text = await service.diff(root, params.get('file'), staged, untracked, since)
+          send(res, 200, {
+            ok: true,
+            data: { root, file: params.get('file'), staged, untracked, since: since ?? null, text },
+          })
+          return
+        }
+
+        case '/branches': {
+          const root = await service.resolveRoot(params.get('root') ?? undefined)
+          send(res, 200, { ok: true, data: { root, ...(await service.branches(root)) } })
+          return
+        }
+
+        case '/review': {
+          const root = await service.resolveRoot(params.get('root') ?? undefined)
+          const since = params.get('since')
+          if (since === null || since === '') throw new Error('review needs a since marker')
+          send(res, 200, { ok: true, data: { root, ...(await service.review(root, since)) } })
+          return
+        }
+
+        case '/commit': {
+          const root = await service.resolveRoot(params.get('root') ?? undefined)
+          const detail = await service.commitDetail(root, params.get('hash') ?? 'HEAD')
+          if (detail === null) {
+            send(res, 404, { ok: false, error: `no commit ${JSON.stringify(params.get('hash'))}` })
+            return
+          }
+          send(res, 200, { ok: true, data: { root, ...detail } })
+          return
+        }
+
+        case '/show': {
+          const root = await service.resolveRoot(params.get('root') ?? undefined)
+          const text = await service.show(root, params.get('hash') ?? 'HEAD', params.get('file'))
+          send(res, 200, { ok: true, data: { root, text } })
+          return
+        }
+
+        default:
+          send(res, 404, { ok: false, error: `unknown git-api route ${JSON.stringify(route)}` })
+          return
+      }
+    }
+
+    // ── writes ────────────────────────────────────────────────────────────────
+    // Every write is refused without the custom header, so a page the user has
+    // open cannot drive git through this loopback route table.
+    assertNotCrossSite(req)
+    const body = await readJsonBody(req)
+
+    switch (route) {
+      case '/stage': {
+        const root = await service.resolveRoot(typeof body.root === 'string' ? body.root : undefined)
+        const files = requireFiles(body.files)
+        await service.stage(root, files)
+        send(res, 200, { ok: true, data: { root, staged: files } })
+        return
+      }
+
+      case '/unstage': {
+        const root = await service.resolveRoot(typeof body.root === 'string' ? body.root : undefined)
+        const files = requireFiles(body.files)
+        await service.unstage(root, files)
+        send(res, 200, { ok: true, data: { root, unstaged: files } })
+        return
+      }
+
+      case '/checkout': {
+        const root = await service.resolveRoot(typeof body.root === 'string' ? body.root : undefined)
+        const ref = requireRef(body.ref, 'ref')
+        const create = body.create === undefined || body.create === null ? undefined : body.create
+        await service.checkout(root, ref, create)
+        send(res, 200, { ok: true, data: { root, ref, create: create ?? null } })
+        return
+      }
+
+      case '/pull': {
+        const root = await service.resolveRoot(typeof body.root === 'string' ? body.root : undefined)
+        const strategy = body.strategy === undefined || body.strategy === null ? 'ff-only' : body.strategy
+        const result = await service.pull(root, strategy)
+        send(res, 200, { ok: true, data: { root, strategy, ...result } })
+        return
+      }
+
+      case '/push': {
+        const root = await service.resolveRoot(typeof body.root === 'string' ? body.root : undefined)
+        const setUpstream = body.setUpstream === true
+        const result = await service.push(root, setUpstream)
+        send(res, 200, { ok: true, data: { root, ...result } })
+        return
+      }
+
+      case '/hunks': {
+        const root = await service.resolveRoot(typeof body.root === 'string' ? body.root : undefined)
+        const file = typeof body.file === 'string' ? body.file : ''
+        if (file === '') throw new Error('hunks needs a file')
+        const staged = body.staged === true
+        await service.applyHunks(root, file, body.hunks, staged)
+        send(res, 200, { ok: true, data: { root, file, staged, hunks: body.hunks } })
+        return
+      }
+
+      case '/commit': {
+        const root = await service.resolveRoot(typeof body.root === 'string' ? body.root : undefined)
+        const message = typeof body.message === 'string' ? body.message.trim() : ''
+        if (message === '') throw new Error('commit message must not be empty')
+        const hash = await service.createCommit(root, message)
+        send(res, 200, { ok: true, data: { root, hash } })
+        return
+      }
+
+      default:
+        send(res, 404, { ok: false, error: `unknown git-api write route ${JSON.stringify(route)}` })
+        return
+    }
+  } catch (error) {
+    // Caller-caused problems (bad path, not a repo, outside allowedRoots, an
+    // empty message, a rejected cross-site write) are 400s with the git
+    // diagnostic attached; the panel shows that text verbatim.
+    const message = error instanceof Error ? error.message : String(error)
+    ctx.logger?.warn?.(`dsh-git: ${method} ${route} failed: ${message}`)
+    send(res, 400, { ok: false, error: message })
+  }
+}
+
+/**
+ * Plugin body: mount one prefix route over a {@link GitService}.
+ * @param ctx - the plugin context.
+ * @param config - the row's config from `cordis.patch.yml`.
+ */
+export function apply(ctx, config) {
+  // Resolved lazily and defensively: the workspace registry is optional, and a
+  // deployment without it simply falls back to `allowedRoots`.
+  const knownWorkspaces = () => {
+    // Registered as `workspaceRegistry` — that is how
+    // `dsh-api-workspace-controller` reaches it. Deliberately no fallback to a
+    // guessed second name: an unverified alias would make it ambiguous which
+    // one is actually in play when the allowlist behaves unexpectedly.
+    const registry = ctx.get?.('workspaceRegistry')
+    if (registry === undefined || registry === null || typeof registry.list !== 'function') return []
+    return registry.list().map((workspace) => workspace?.path)
+  }
+  const service = new GitService(config ?? {}, knownWorkspaces)
+  ctx.effect(() => () => service.dispose(), 'dsh-git: service lifetime')
+  ctx.effect(
+    () =>
+      ctx.webServer.register({
+        kind: 'prefix',
+        path: ROUTE_PREFIX,
+        handler: (req, res) => {
+          void handle(ctx, service, req, res)
+        },
+      }),
+    'dsh-git: route table',
+  )
+  ctx.logger?.info?.(`dsh-git: mounted ${ROUTE_PREFIX}`)
+}