@vintasoftware/pr-review-canvas 0.3.0 → 0.5.0

package/src/server/bundle.ts

@@ -1,11 +1,23 @@
-import type { CanvasInfo, PrBundle, SharedCanvasInfo, StaleInfo } from '../contract/api.js'
+import type {
+  BundleStatus,
+  CanvasInfo,
+  Capabilities,
+  CarriedOverInfo,
+  PrBundle,
+  SharedCanvasInfo,
+  StaleInfo,
+} from '../contract/api.js'
 import type { CommentsPayload } from '../contract/comments.js'
-import { isLargePr } from '../contract/generation-context.js'
+import { isLargePr, type LocalPrepareTarget } from '../contract/generation-context.js'
 import type { FileEntry, Pr, ReviewArtifact } from '../contract/review-artifact.js'
-import { discoverSharedCanvas, discoveryFingerprint } from '../github/attachments.js'
-import { fetchComments } from '../github/comments.js'
-import { fetchPrMeta, fetchPrRefs, toPr } from '../github/pr.js'
-import { stateForHead } from '../github/review-body.js'
+import { isLocalKey, type LocalKey, type ReviewKey } from '../contract/review-key.js'
+import { describeLocalWork, resolveLocalBase } from '../git/local-target.js'
+import { fetchPrRefs } from '../git/pr-refs.js'
+import { toPr } from '../host/pr.js'
+import { lookupCanvas } from '../review/carry-over.js'
+import { marksForCanvas } from '../review/carry-marks.js'
+import { reviewedCommit, stateForCanvas } from '../review/review-body.js'
+import { discoverSharedCanvas, discoveryFingerprint } from '../host/attachments.js'
 import { buildSkillCommand } from '../review/skill-command.js'
 import type { CanvasLookup } from '../store/canvas-store.js'
 import type { AppContext } from './context.js'
@@ -13,6 +25,13 @@ import { AppError } from './errors.js'
 
 export interface BundleOptions {
   refresh: boolean
+  /**
+   * The background poller asked, rather than a reader opening or refreshing the page. A local
+   * review answers a poll from the head it last resolved: snapshotting the working tree every few
+   * seconds would stat the whole tree again and again, and every edit in between would leave
+   * another commit and another `derived/` tree behind it.
+   */
+  poll?: boolean
 }
 
 export interface DiscoveryRun {
@@ -58,15 +77,37 @@ export async function runDiscovery(
  */
 export function createPrLoader(ctx: AppContext) {
   const refreshed = new Set<number>()
+  /**
+   * The head each local review was last resolved at in this process, with the head `prepare` had
+   * on file at the time. A poll answers from it, so it can never report a status the page's own
+   * load contradicts; a later `prepare` files another head, and that is the one answer a waiting
+   * page is polling for, so it resolves again.
+   */
+  const localHeads = new Map<LocalKey, { head: Pr; preparedSha: string | null }>()
+
+  /** One local review's cached meta, which `prepare` wrote. */
+  async function localPr(key: LocalKey): Promise<Pr> {
+    const stored = await ctx.prs.readPr(key)
+    if (stored === null) {
+      throw new AppError(
+        'CANVAS_NOT_FOUND',
+        `no ${key} review has been prepared in this repository yet`,
+        404,
+        `run /pr-review-canvas ${key} to generate one`
+      )
+    }
+    return stored
+  }
 
   async function refreshPr(
     number: number
   ): Promise<{ pr: Pr; comments: CommentsPayload; warnings: string[] }> {
-    const meta = await fetchPrMeta(ctx.gh, ctx.config.repo, number)
-    const shas = await fetchPrRefs(ctx.git, meta)
-    const pr = toPr(meta, ctx.config.repo, shas)
-    await ctx.prs.writePr(pr)
-    const { payload, warnings } = await fetchComments(ctx.gh, ctx.config.repo, number, shas.headSha, ctx.now)
+    const { host, repo } = ctx.config
+    const meta = await host.fetchPrMeta(ctx.gh, repo, number)
+    const shas = await fetchPrRefs(ctx.git, host, meta)
+    const pr = toPr(meta, repo, shas)
+    await ctx.prs.writePr(number, pr)
+    const { payload, warnings } = await host.fetchComments(ctx.gh, repo, number, shas.headSha, ctx.now)
     await ctx.prs.writeComments(number, payload)
     refreshed.add(number)
     return { pr, comments: payload, warnings }
@@ -87,24 +128,56 @@ export function createPrLoader(ctx: AppContext) {
     },
     async refreshComments(number: number): Promise<{ comments: CommentsPayload; warnings: string[] }> {
       const pr = (await ctx.prs.readPr(number)) ?? (await refreshPr(number)).pr
-      const { payload, warnings } = await fetchComments(ctx.gh, ctx.config.repo, number, pr.headSha, ctx.now)
+      const { host, repo } = ctx.config
+      const { payload, warnings } = await host.fetchComments(ctx.gh, repo, number, pr.headSha, ctx.now)
       await ctx.prs.writeComments(number, payload)
       return { comments: payload, warnings }
     },
     async currentPr(number: number): Promise<Pr> {
       return (await ctx.prs.readPr(number)) ?? (await refreshPr(number)).pr
     },
+    /**
+     * The head a local review describes. Every request but a poll reads the work again, so opening
+     * or refreshing the page catches an edit made since the canvas was generated. A poll reads it
+     * again only when this process has not resolved a head yet, or when `prepare` has filed one
+     * since: the rest of the time it answers about the head the page is showing, at no cost.
+     */
+    async localHead(key: LocalKey, opts: BundleOptions): Promise<Pr> {
+      const stored = await ctx.prs.readPr(key)
+      const preparedSha = stored?.headSha ?? null
+      const seen = localHeads.get(key)
+      if (opts.poll === true && seen !== undefined && seen.preparedSha === preparedSha) {
+        return seen.head
+      }
+      const head = await currentLocalPr(ctx, key, stored)
+      localHeads.set(key, { head, preparedSha })
+      return head
+    },
+    /** The head of either kind of target, so the routes both kinds serve need no branch. */
+    async currentTarget(key: ReviewKey): Promise<Pr> {
+      return isLocalKey(key) ? localPr(key) : ((await ctx.prs.readPr(key)) ?? (await refreshPr(key)).pr)
+    },
   }
 }
 export type PrLoader = ReturnType<typeof createPrLoader>
 
-/** Whether the change set on screen is large, counted from the files the page is showing. */
-function largePrOf(files: readonly FileEntry[]): boolean {
-  return isLargePr({
-    files: files.length,
+/** The diffstat of the files the page is showing. */
+function countDiff(files: readonly FileEntry[]): {
+  additions: number
+  deletions: number
+  changedFiles: number
+} {
+  return {
     additions: files.reduce((n, f) => n + f.additions, 0),
     deletions: files.reduce((n, f) => n + f.deletions, 0),
-  })
+    changedFiles: files.length,
+  }
+}
+
+/** Whether the change set on screen is large, counted from the files the page is showing. */
+function largePrOf(files: readonly FileEntry[]): boolean {
+  const counts = countDiff(files)
+  return isLargePr({ files: counts.changedFiles, ...counts })
 }
 
 /** Dev fixture: the committed artifact presented as the canvas of the live PR head. */
@@ -116,10 +189,15 @@ export function rekeyFixture(fixture: ReviewArtifact, pr: Pr): ReviewArtifact {
  * The stored canvas and the block that describes it. Null when review.json was written by an
  * older tool version: the page then offers to generate a new one.
  */
+export interface LoadedCanvas {
+  artifact: ReviewArtifact
+  canvas: CanvasInfo
+}
+
 async function loadCanvas(
   ctx: AppContext,
   found: Extract<CanvasLookup, { headSha: string }>
-): Promise<{ artifact: ReviewArtifact; canvas: CanvasInfo } | null> {
+): Promise<LoadedCanvas | null> {
   let artifact: ReviewArtifact | null
   try {
     artifact = await ctx.canvases.readArtifact(found.headSha)
@@ -140,140 +218,275 @@ async function loadCanvas(
   return { artifact, canvas }
 }
 
-/** The diffs of one canvas: the stored ones, or freshly built when both commits are local. */
-async function readOrBuildDerived(
+/** The shape of an empty comment payload: a local review has no forge thread to read. */
+function noComments(headSha: string, now: () => Date): CommentsPayload {
+  return { fetchedAt: now().toISOString(), headSha, reviewComments: [], issueComments: [], reviews: [] }
+}
+
+/** Posting is a forge operation, and local work is on no forge. The page hides every post button. */
+export const LOCAL_CAPABILITIES: Capabilities = {
+  canComment: false,
+  tokenKind: 'none',
+  login: null,
+  reason: 'this work is not on a pull request yet, so there is nothing to comment on',
+  hint: 'open the pull request, then review it at /review/<number>',
+}
+
+/** Which diffs the page shows, and what to say when their commits are not in the clone. */
+interface ShownDiff {
+  files: FileEntry[]
+  derivable: boolean
+  warning: string | null
+}
+
+/**
+ * The diffs of the canvas on screen, which is the one `found` names rather than the target's
+ * current head: a stale canvas describes an older commit, and its own files are what the reader
+ * is looking at.
+ */
+async function shownDiff(
   ctx: AppContext,
-  headSha: string,
-  mergeBaseSha: string | undefined
-): Promise<{ files: FileEntry[] } | null> {
-  const stored = await ctx.derived.read(headSha)
-  if (stored !== null || mergeBaseSha === undefined) {
-    return stored
+  pr: Pr,
+  found: CanvasLookup,
+  loaded: LoadedCanvas | null
+): Promise<ShownDiff> {
+  const mergeBaseSha = loaded?.canvas.manifest?.mergeBaseSha ?? pr.mergeBaseSha
+  const derived = await ctx.derived.readOrBuild(reviewedCommit(found, pr), mergeBaseSha)
+  if (derived !== null) {
+    return { files: derived.files, derivable: true, warning: null }
   }
-  if (!(await ctx.derived.derivable(headSha, mergeBaseSha))) {
-    return null
+  return {
+    files: loaded?.artifact.files ?? [],
+    derivable: false,
+    warning:
+      loaded === null
+        ? 'the head or merge base is not in the local clone; diffs are not available'
+        : 'the commits behind this canvas are not in the clone; diffs are not available',
   }
-  return ctx.derived.ensure(headSha, mergeBaseSha)
 }
 
-export async function resolveBundle(
-  ctx: AppContext,
-  loader: PrLoader,
-  number: number,
-  opts: BundleOptions
-): Promise<PrBundle> {
-  const { pr, comments, warnings } = await loader.load(number, opts)
-  const allWarnings = [...ctx.projectConfig.warnings, ...warnings]
-
-  const derivable = await ctx.derived.derivable(pr.headSha, pr.mergeBaseSha)
-  let files: FileEntry[] = []
-  if (derivable) {
-    files = (await ctx.derived.ensure(pr.headSha, pr.mergeBaseSha)).files
-  } else {
-    allWarnings.push('the PR head or merge base is not in the local clone; diffs are not available')
+/**
+ * The screen a canvas lookup produces: its status, the notice a stale one carries, and the command
+ * that regenerates it. Both targets go through this, so neither can drift from the other.
+ */
+function canvasScreen(
+  key: ReviewKey,
+  pr: Pr,
+  found: CanvasLookup,
+  loaded: LoadedCanvas | null
+): {
+  status: BundleStatus
+  skillCommand: string
+  stale?: StaleInfo
+  carriedOver?: CarriedOverInfo
+  warning?: string
+} {
+  if (found.status === 'missing') {
+    return { status: 'missing', skillCommand: buildSkillCommand(key, { force: false }) }
+  }
+  // A canvas exists for this target, so regenerating always needs --force.
+  const skillCommand = buildSkillCommand(key, { force: true })
+  if (loaded === null) {
+    return {
+      status: 'missing',
+      skillCommand,
+      warning: `the canvas for ${found.headSha.slice(0, 7)} does not match the current format; regenerate it`,
+    }
+  }
+  if (found.status === 'ready') {
+    return found.carriedOver === undefined
+      ? { status: 'ready', skillCommand }
+      : { status: 'ready', skillCommand, carriedOver: found.carriedOver }
+  }
+  const stale: StaleInfo = {
+    canvasHeadSha: found.headSha,
+    currentHeadSha: pr.headSha,
+    relation: found.relation,
   }
+  if (found.relation === 'ancestor') {
+    stale.commitsBehind = found.commitsBehind
+  }
+  return { status: 'stale', skillCommand, stale }
+}
 
+/** Everything a bundle holds that does not depend on which canvas was found. */
+async function bundleBase(
+  ctx: AppContext,
+  key: ReviewKey,
+  input: {
+    pr: Pr
+    comments: CommentsPayload
+    /** A promise, so probing the forge runs alongside the chat and state reads. */
+    capabilities: Promise<Capabilities>
+    diff: ShownDiff
+    /** The commit of the canvas on screen: the marks the page shows are the ones made on it. */
+    canvasSha: string
+    /** The canvas on screen, when there is one: marks may follow the line of descent onto it. */
+    artifact: ReviewArtifact | null
+    warnings: string[]
+  }
+): Promise<Omit<PrBundle, 'status' | 'skillCommand'>> {
   const chatEnabled = ctx.projectConfig.config.chat.enabled
   const [stored, capabilities, settings, acpx] = await Promise.all([
-    ctx.state.read(number),
-    ctx.capabilities.get(),
+    ctx.state.read(key),
+    input.capabilities,
     chatEnabled ? ctx.chat.effectiveSettings() : Promise.resolve(null),
     chatEnabled ? ctx.preflight.get() : Promise.resolve({ installed: false, version: null }),
   ])
   if (chatEnabled && !acpx.installed) {
-    allWarnings.push('acpx is not on PATH, so the AI Chat pane is off; install acpx to turn it on')
+    input.warnings.push('acpx is not on PATH, so the AI Chat pane is off; install acpx to turn it on')
   }
-  // Marks made on another commit describe other code, so the page never shows them as reviewed.
-  const state = stateForHead(stored, pr.headSha)
-  const base = {
-    pr,
-    files,
-    derivable,
-    comments,
-    state,
+  // With no canvas to read, a mark counts only when it was made on this very commit. With one,
+  // marks made on a canvas it descends from follow it wherever the diff is untouched.
+  const marks =
+    input.artifact === null
+      ? { state: stateForCanvas(stored, input.canvasSha), carriedFrom: undefined }
+      : await marksForCanvas(ctx, input.artifact, input.canvasSha, stored)
+  return {
+    pr: input.pr,
+    files: input.diff.files,
+    derivable: input.diff.derivable,
+    comments: input.comments,
+    state: marks.state,
+    ...(marks.carriedFrom === undefined ? {} : { marksCarriedFrom: marks.carriedFrom }),
     capabilities,
     chat: {
       enabled: chatEnabled && acpx.installed,
       acpx: acpx.installed,
       ...(settings === null ? {} : { agent: settings.agent, model: settings.model }),
     },
-    largePr: largePrOf(files),
-    warnings: allWarnings,
+    largePr: largePrOf(input.diff.files),
+    warnings: input.warnings,
+  }
+}
+
+/**
+ * The head the local review describes right now, resolved the way `prepare` would.
+ *
+ * `source` is what decides whether the working tree is snapshotted, so an unprepared review asks
+ * for the branch tip: there is no canvas for a snapshot to be stale against yet, and that screen
+ * is the one the page polls until one exists.
+ */
+async function currentLocalPr(ctx: AppContext, key: LocalKey, stored: Pr | null): Promise<Pr> {
+  const target: LocalPrepareTarget | null = await ctx.prs.readLocalTarget(key)
+  return describeLocalWork(ctx.git, {
+    base: target?.base ?? (await resolveLocalBase(ctx.git, stored?.baseRef)),
+    source: stored === null ? 'branch' : (target?.source ?? key),
+    repo: ctx.config.repo,
+    now: ctx.now,
+  })
+}
+
+/**
+ * The bundle for `/review/branch` and `/review/uncommitted`: the same screen over work that has no
+ * pull request. There is no forge side to it, so no comments, no capabilities, no attachment
+ * discovery and no import.
+ */
+export async function resolveLocalBundle(
+  ctx: AppContext,
+  loader: PrLoader,
+  key: LocalKey,
+  opts: BundleOptions
+): Promise<PrBundle> {
+  const head = await loader.localHead(key, opts)
+  const warnings = [...ctx.projectConfig.warnings]
+
+  const found = await ctx.canvases.findForLocal(key, head.headSha)
+  const loaded = found.status === 'missing' ? null : await loadCanvas(ctx, found)
+  const diff = await shownDiff(ctx, head, found, loaded)
+  if (diff.warning !== null && loaded !== null) {
+    warnings.push(diff.warning)
+  }
+  const screen = canvasScreen(key, head, found, loaded)
+  if (screen.warning !== undefined) {
+    warnings.push(screen.warning)
   }
+  // Local work is on no forge, so the only diffstat there is is the one in the diff on screen.
+  const pr: Pr = { ...head, ...countDiff(diff.files) }
+  const base = await bundleBase(ctx, key, {
+    pr,
+    comments: noComments(pr.headSha, ctx.now),
+    capabilities: Promise.resolve(LOCAL_CAPABILITIES),
+    diff,
+    canvasSha: reviewedCommit(found, pr),
+    artifact: loaded?.artifact ?? null,
+    warnings,
+  })
+  const { warning: _screenWarning, ...screenFields } = screen
+  return { ...base, local: key, ...(loaded ?? {}), ...screenFields }
+}
+
+export async function resolveBundle(
+  ctx: AppContext,
+  loader: PrLoader,
+  number: number,
+  opts: BundleOptions
+): Promise<PrBundle> {
+  const { pr, comments, warnings: fetched } = await loader.load(number, opts)
+  const warnings = [...ctx.projectConfig.warnings, ...fetched]
+  const capabilities = ctx.capabilities.get()
 
   if (ctx.fixtureArtifact !== null) {
     const artifact = rekeyFixture(ctx.fixtureArtifact, pr)
+    const live = await shownDiff(ctx, pr, { status: 'missing' }, null)
+    if (live.warning !== null) {
+      warnings.push(live.warning)
+    }
+    warnings.push('showing the --fixture-canvas artifact (dev only)')
+    const diff = live.files.length > 0 ? live : { ...live, files: artifact.files }
+    const base = await bundleBase(ctx, number, {
+      pr,
+      comments,
+      capabilities,
+      diff,
+      canvasSha: pr.headSha,
+      artifact: null,
+      warnings,
+    })
     const canvas: CanvasInfo = { headSha: pr.headSha, source: 'fixture', manifest: null }
-    allWarnings.push('showing the --fixture-canvas artifact (dev only)')
     return {
       ...base,
       status: 'ready',
       artifact,
       canvas,
-      files: files.length > 0 ? files : artifact.files,
-      largePr: largePrOf(files.length > 0 ? files : artifact.files),
       skillCommand: buildSkillCommand(number, { force: true }),
     }
   }
 
-  let found = await ctx.canvases.findForPr(number, pr.headSha)
+  let found = await lookupCanvas(ctx, number, pr)
   let sharedCanvas: SharedCanvasInfo | null = null
-  // A canvas for this very head beats anything attached to the PR, so discovery runs only
-  // when there is none, and its import can turn a stale or missing bundle into a ready one.
-  if (found.status !== 'ready') {
+  // A canvas for this very head beats anything attached to the PR, so an ordinary load runs
+  // discovery only when there is none, a carried-over canvas included, and its import can turn a
+  // stale, missing, or carried-over bundle into one with the head's own canvas. Refresh runs it
+  // whatever was found, to pick up a newer generation at the same head.
+  if (found.status !== 'ready' || found.carriedOver !== undefined || opts.refresh) {
     const discovery = await runDiscovery(ctx, pr, comments, { refresh: opts.refresh })
     sharedCanvas = discovery.sharedCanvas
-    allWarnings.push(...discovery.warnings)
+    warnings.push(...discovery.warnings)
     if (discovery.imported) {
-      found = await ctx.canvases.findForPr(number, pr.headSha)
+      found = await lookupCanvas(ctx, number, pr)
     }
   }
-  const shared = sharedCanvas === null ? {} : { sharedCanvas }
 
-  if (found.status === 'missing') {
-    return {
-      ...base,
-      ...shared,
-      status: 'missing',
-      skillCommand: buildSkillCommand(number, { force: false }),
-    }
+  const loaded = found.status === 'missing' ? null : await loadCanvas(ctx, found)
+  const diff = await shownDiff(ctx, pr, found, loaded)
+  if (diff.warning !== null) {
+    warnings.push(diff.warning)
   }
-  const loaded = await loadCanvas(ctx, found)
-  if (loaded === null) {
-    allWarnings.push(
-      `the canvas for ${found.headSha.slice(0, 7)} does not match the current format; regenerate it`
-    )
-    return { ...base, ...shared, status: 'missing', skillCommand: buildSkillCommand(number, { force: true }) }
-  }
-  // A canvas exists for this PR, so regenerating always needs --force.
-  const skillCommand = buildSkillCommand(number, { force: true })
-  if (found.status === 'ready') {
-    return { ...base, ...shared, ...loaded, status: 'ready', skillCommand }
-  }
-  const stale: StaleInfo = {
-    canvasHeadSha: found.headSha,
-    currentHeadSha: pr.headSha,
-    relation: found.relation,
-  }
-  if (found.commitsBehind !== undefined) {
-    stale.commitsBehind = found.commitsBehind
-  }
-  // The page shows the canvas of the older commit, so the files and the diffs are that commit's.
-  // They are rebuilt when the clone has the commits, which is how a canvas imported before the
-  // fetch becomes readable once the commits arrive.
-  const staleDerived = await readOrBuildDerived(ctx, found.headSha, loaded.canvas.manifest?.mergeBaseSha)
-  // A stale canvas describes an older commit, so its own files decide both the diffs and
-  // whether the notice about large change sets belongs on the page.
-  const staleFiles = staleDerived?.files ?? loaded.artifact.files
-  return {
-    ...base,
-    ...shared,
-    ...loaded,
-    files: staleFiles,
-    largePr: largePrOf(staleFiles),
-    derivable: staleDerived !== null,
-    status: 'stale',
-    stale,
-    skillCommand,
+  const screen = canvasScreen(number, pr, found, loaded)
+  if (screen.warning !== undefined) {
+    warnings.push(screen.warning)
   }
+  const base = await bundleBase(ctx, number, {
+    pr,
+    comments,
+    capabilities,
+    diff,
+    canvasSha: reviewedCommit(found, pr),
+    artifact: loaded?.artifact ?? null,
+    warnings,
+  })
+  const shared = sharedCanvas === null ? {} : { sharedCanvas }
+  const { warning: _screenWarning, ...screenFields } = screen
+  return { ...base, ...shared, ...(loaded ?? {}), ...screenFields }
 }

package/src/server/context.ts

@@ -11,8 +11,8 @@ import { createTranscriptStore, type TranscriptStore } from '../chat/threads.js'
 import type { RuntimeConfig } from '../config.js'
 import type { ReviewArtifact } from '../contract/review-artifact.js'
 import { createGit, type Git } from '../git/git.js'
-import { type CapabilityProbe, createCapabilityProbe } from '../github/capabilities.js'
-import { createGitHubClient, type GitHubClient } from '../github/gh.js'
+import { type CapabilityProbe, createCapabilityProbe } from '../host/capabilities.js'
+import { createHostClient, type HostClient } from '../host/client.js'
 import { PACKAGE_ROOT, STATIC_DIR } from '../paths.js'
 import type { LoadedProjectConfig } from '../project-config.js'
 import { type CanvasStore, createCanvasStore } from '../store/canvas-store.js'
@@ -40,14 +40,15 @@ export interface AppContext {
   config: RuntimeConfig
   projectConfig: LoadedProjectConfig
   git: Git
-  gh: GitHubClient
+  /** The host CLI client: `gh` or `glab`, whichever `config.host` names. */
+  gh: HostClient
   /** The only outbound HTTP the tool makes: attachment downloads. Tests inject a fake. */
   fetch: typeof fetch
   canvases: CanvasStore
   derived: DerivedStore
   prs: PrStore
   state: StateStore
-  /** What this GitHub login may post here, probed once and reused for ten minutes. */
+  /** What this forge login may post here, probed once and reused for ten minutes. */
   capabilities: CapabilityProbe
   /** Personal chat settings, in `.pr-review/settings.yml`. */
   settings: SettingsStore
@@ -112,7 +113,7 @@ export interface CreateAppContextOptions {
   projectConfig: LoadedProjectConfig
   fixtureArtifact: ReviewArtifact | null
   git?: Git
-  gh?: GitHubClient
+  gh?: HostClient
   fetch?: typeof fetch
   runner?: AgentRunner
   now?: () => Date
@@ -136,7 +137,7 @@ export function createChatSet(
 ): ChatSet {
   const settings = createSettingsStore(config.dataDir)
   const preflight = createPreflightProbe(runner, now)
-  const transcripts = createTranscriptStore(number => stores.prs.prDir(number))
+  const transcripts = createTranscriptStore(key => stores.prs.prDir(key))
   return {
     settings,
     preflight,
@@ -159,7 +160,8 @@ export function createChatSet(
 export function createAppContext(opts: CreateAppContextOptions): AppContext {
   const git = opts.git ?? createGit(opts.config.repoRoot)
   const now = opts.now ?? (() => new Date())
-  const gh = opts.gh ?? createGitHubClient()
+  const { host, repo } = opts.config
+  const gh = opts.gh ?? createHostClient(host.cli)
   const stores = createStores(opts.config.dataDir, opts.config, git, now)
   return {
     config: opts.config,
@@ -167,7 +169,7 @@ export function createAppContext(opts: CreateAppContextOptions): AppContext {
     projectConfig: opts.projectConfig,
     git,
     gh,
-    capabilities: createCapabilityProbe(gh, opts.config.repo, now),
+    capabilities: createCapabilityProbe(() => host.probeCapabilities(gh, repo), now),
     fetch: opts.fetch ?? ((input, init) => globalThis.fetch(input, init)),
     ...stores,
     ...createChatSet(

package/src/server/errors.ts

@@ -3,8 +3,20 @@ import type { ContentfulStatusCode } from 'hono/utils/http-status'
 import { ConfigError } from '../config.js'
 import type { ErrorCode, ErrorEnvelope } from '../contract/api.js'
 import { GitError } from '../git/git.js'
-import { GitHubApiError } from '../github/gh.js'
-import { PrNotFoundError } from '../github/pr.js'
+import { LocalTargetError } from '../git/local-target.js'
+import { PrNotFoundError } from '../host/pr.js'
+import { CLI_INFO, type HostCli, HostCliError } from '../host/client.js'
+
+/** The codes each host CLI's failures map to. The front end and the docs name them one by one. */
+const CLI_ERROR_CODES: Record<HostCli, { missing: ErrorCode; unauthenticated: ErrorCode; api: ErrorCode }> = {
+  gh: { missing: 'GH_MISSING', unauthenticated: 'GH_UNAUTHENTICATED', api: 'GITHUB_API_ERROR' },
+  glab: { missing: 'GLAB_MISSING', unauthenticated: 'GLAB_UNAUTHENTICATED', api: 'GITLAB_API_ERROR' },
+}
+
+/** The codes that mean the host CLI itself, not the request, is the problem. */
+export const CLI_SETUP_CODES: ReadonlySet<ErrorCode> = new Set(
+  Object.values(CLI_ERROR_CODES).flatMap(c => [c.missing, c.unauthenticated])
+)
 
 export class AppError extends Error {
   readonly code: ErrorCode
@@ -53,19 +65,29 @@ export function toAppError(err: unknown): AppError {
       'check the number and that origin is the right repository'
     )
   }
-  if (err instanceof GitHubApiError) {
+  if (err instanceof HostCliError) {
+    const codes = CLI_ERROR_CODES[err.cli]
+    const info = CLI_INFO[err.cli]
     if (err.missingBinary) {
       return new AppError(
-        'GH_MISSING',
-        'the GitHub CLI (gh) is not installed',
+        codes.missing,
+        `the ${info.label} is not installed`,
         500,
-        'install it from https://cli.github.com'
+        `install it from ${info.installUrl}`
       )
     }
     if (err.unauthenticated) {
-      return new AppError('GH_UNAUTHENTICATED', 'gh is not logged in', 401, 'run `gh auth login`')
+      return new AppError(
+        codes.unauthenticated,
+        `${err.cli} is not logged in`,
+        401,
+        `run \`${info.loginCommand}\``
+      )
     }
-    return new AppError('GITHUB_API_ERROR', err.message, 502)
+    return new AppError(codes.api, err.message, 502)
+  }
+  if (err instanceof LocalTargetError) {
+    return new AppError('BAD_REQUEST', err.message, 400, err.hint)
   }
   if (err instanceof GitError) {
     return new AppError('GIT_ERROR', err.message, 500)