@vintasoftware/pr-review-canvas 0.2.0 → 0.4.0

package/src/server/errors.ts

@@ -1,9 +1,22 @@
+import { inspect } from 'node:util'
 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
@@ -12,7 +25,13 @@ export class AppError extends Error {
   /** What a rejected file got wrong, one line each. Never the file's content. */
   readonly issues: string[] | undefined
 
-  constructor(code: ErrorCode, message: string, status: ContentfulStatusCode, hint?: string, issues?: string[]) {
+  constructor(
+    code: ErrorCode,
+    message: string,
+    status: ContentfulStatusCode,
+    hint?: string,
+    issues?: string[]
+  ) {
     super(message)
     this.name = 'AppError'
     this.code = code
@@ -39,21 +58,36 @@ export function toAppError(err: unknown): AppError {
     return err
   }
   if (err instanceof PrNotFoundError) {
-    return new AppError('PR_NOT_FOUND', err.message, 404, 'check the number and that origin is the right repository')
+    return new AppError(
+      'PR_NOT_FOUND',
+      err.message,
+      404,
+      '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)
@@ -63,3 +97,15 @@ export function toAppError(err: unknown): AppError {
   }
   return new AppError('INTERNAL', err instanceof Error ? err.message : String(err), 500)
 }
+
+/** Keep the original error and its causes in the server log, before response mapping loses the stack. */
+export function logRequestError(
+  log: (line: string) => void,
+  request: { method: string; path: string },
+  err: unknown
+): void {
+  const mapped = toAppError(err)
+  if (mapped.status >= 500) {
+    log(`[serve] ${request.method} ${request.path} ${mapped.status} ${mapped.code}\n${inspect(err)}`)
+  }
+}

package/src/server/html.ts

@@ -1,7 +1,9 @@
 import { html, raw } from 'hono/html'
 import type { HtmlEscapedString } from 'hono/utils/html'
 import type { ErrorEnvelope, HomeData } from '../contract/api.js'
+import { keyLabel, keyToString, type LocalKey, type ReviewKey } from '../contract/review-key.js'
 import type { Appearance } from '../contract/settings.js'
+import { type Host, publicHost } from '../host/host.js'
 
 type Html = HtmlEscapedString | Promise<HtmlEscapedString>
 
@@ -68,50 +70,72 @@ ${opts.app ? html`<script type="module" src="/static/js/app.js"></script>` : ''}
 }
 
 export function reviewPage(
-  bootstrap: { prNumber: number; owner: string; repo: string; version: string },
+  page: { prNumber: ReviewKey; owner: string; repo: string; version: string; host: Host },
   nonce: string,
   appearance: Appearance
 ): Html {
+  const bootstrap = { ...page, host: publicHost(page.host) }
+  const key = keyToString(bootstrap.prNumber)
+  const what =
+    typeof bootstrap.prNumber === 'number' ? `${page.host.nounShort} #${key}` : keyLabel(bootstrap.prNumber)
   return pageShell({
-    title: `PR #${bootstrap.prNumber} · ${bootstrap.owner}/${bootstrap.repo} · review canvas`,
+    title: `${what} · ${bootstrap.owner}/${bootstrap.repo} · review canvas`,
     bootstrap,
     nonce,
     appearance,
     app: true,
     body: html`<a class="skip" href="#main">Skip to content</a>
-<pr-app class="page" data-pr="${String(bootstrap.prNumber)}"><div class="loading">Loading PR #${String(bootstrap.prNumber)}…</div></pr-app>`,
+<pr-app class="page" data-pr="${key}"><div class="loading">Loading ${what}…</div></pr-app>`,
   })
 }
 
 export function homePage(
-  data: HomeData & { owner: string; repo: string; version: string; port: number },
+  data: HomeData & {
+    owner: string
+    repo: string
+    version: string
+    port: number
+    host: Host
+    /** The local reviews prepared here, so the home page can link straight to them. */
+    localReviews: readonly LocalKey[]
+  },
   nonce: string,
   appearance: Appearance
 ): Html {
+  const { noun, nounShort, label } = data.host
   return pageShell({
     title: 'PR review canvas',
-    bootstrap: { owner: data.owner, repo: data.repo, version: data.version },
+    bootstrap: { owner: data.owner, repo: data.repo, version: data.version, host: publicHost(data.host) },
     nonce,
     appearance,
     app: false,
     body: html`<div class="page">
 <header class="hdr">
-<div class="hdr-bar"><div class="brand"><span class="box">PR review canvas</span><span class="mono muted">localhost:${String(data.port)}</span></div>
+<div class="hdr-bar"><div class="brand"><span class="brand-wordmark"><img class="brand-icon" src="/static/brand.svg" width="32" height="32" alt="">PR review canvas</span><span class="mono muted">localhost:${String(data.port)}</span></div>
 <div class="hdr-actions"><a class="cmd" href="/api/health">health</a></div></div>
 <div class="stripe" aria-hidden="true"></div>
 <div class="hdr-title"><div class="title"><h1>${data.owner}/${data.repo}</h1></div>
-<p class="meta"><span>Open a pull request by number. Diffs come from your local clone; the canvas from a published review.</span></p></div>
+<p class="meta"><span>Open a ${noun} by number. Diffs come from your local clone; the canvas from a published review.</span></p></div>
 </header>
 <main id="main" class="home">
-<section class="panel"><div class="panel-h"><h2>Open a pull request</h2></div>
+<section class="panel"><div class="panel-h"><h2>Open a ${noun}</h2></div>
 <form class="body home-form" method="get" action="/review">
-<label>PR number <input name="n" type="number" min="1" required inputmode="numeric"></label>
+<label>${nounShort} number <input name="n" type="number" min="1" required inputmode="numeric"></label>
 <button class="cmd fill" type="submit">open</button>
 </form></section>
+<section class="panel"><div class="panel-h"><h2>Before the ${noun}</h2></div>
+<div class="body">${
+      data.localReviews.length === 0
+        ? html`<p class="muted">Nothing reviewed here yet. Run <code>/pr-review-canvas branch</code> to read the current branch against the default one, or <code>/pr-review-canvas uncommitted</code> to read it with your working-tree edits on top, before opening a ${noun}.</p>`
+        : html`<ul class="plain">${data.localReviews.map(
+            key =>
+              html`<li><a href="/review/${key}">${keyLabel(key)}</a> <span class="muted">/review/${key}</span></li>`
+          )}</ul>`
+    }</div></section>
 <section class="panel"><div class="panel-h"><h2>Recent</h2></div>
 ${
   data.recentPrs.length === 0
-    ? html`<div class="body muted">No pull requests opened yet.</div>`
+    ? html`<div class="body muted">No ${noun}s opened yet.</div>`
     : html`<ul class="plain body">${data.recentPrs.map(
         p =>
           html`<li><a href="/review/${String(p.number)}"><span class="mono num">#${String(p.number)}</span> ${p.title}</a></li>`
@@ -119,7 +143,7 @@ ${
 }
 </section>
 </main>
-<footer><span>pr-review ${data.version}</span><span>localhost only · nothing leaves this machine except GitHub posts you confirm</span></footer>
+<footer><span>pr-review ${data.version}</span><span>localhost only · nothing leaves this machine except ${label} posts you confirm</span></footer>
 </div>`,
   })
 }
@@ -132,7 +156,7 @@ export function errorPage(error: ErrorEnvelope['error'], nonce: string, appearan
     appearance,
     app: false,
     body: html`<div class="page"><header class="hdr">
-<div class="hdr-bar"><div class="brand"><span class="box">PR review canvas</span></div><div class="hdr-actions"><a class="cmd" href="/">home</a></div></div>
+<div class="hdr-bar"><div class="brand"><span class="brand-wordmark"><img class="brand-icon" src="/static/brand.svg" width="32" height="32" alt="">PR review canvas</span></div><div class="hdr-actions"><a class="cmd" href="/">home</a></div></div>
 <div class="stripe" aria-hidden="true"></div></header>
 <main id="main" class="home"><section class="panel error-card"><div class="panel-h"><h2><span class="mono">${error.code}</span></h2></div>
 <div class="body"><p>${error.message}</p>${error.hint ? html`<p class="muted">${error.hint}</p>` : ''}</div></section></main></div>`,

package/src/server/node-server.ts

@@ -4,9 +4,11 @@ import type { AppContext } from './context.js'
 
 /** Binds 127.0.0.1 only. The Host allowlist in security.ts covers the rest. */
 export function startServer(ctx: AppContext, log: (line: string) => void): { close: () => void } {
-  const app = createApp(ctx)
+  const app = createApp({ ...ctx, log })
   const server = serve({ fetch: app.fetch, port: ctx.config.port, hostname: '127.0.0.1' }, info => {
-    log(`pr-review ${ctx.version} · http://localhost:${info.port}/ · ${ctx.config.repo.owner}/${ctx.config.repo.name}`)
+    log(
+      `pr-review ${ctx.version} · http://localhost:${info.port}/ · ${ctx.config.repo.owner}/${ctx.config.repo.name}`
+    )
     log(`data dir ${ctx.config.dataDir}`)
     if (ctx.fixtureArtifact !== null) {
       log(`fixture canvas ${ctx.config.fixtureCanvasPath ?? ''} (dev only): every PR reports ready`)

package/src/server/routes/api.ts

@@ -3,23 +3,51 @@ import { z } from 'zod'
 import { buildCanvasZipFor } from '../../canvas/export.js'
 import { importCanvas } from '../../canvas/import.js'
 import { CANVAS_ZIP_MAX_BYTES } from '../../canvas/zip.js'
-import type { ContextResponse, HealthResponse, PatchesResponse, SharedCanvasFetchResponse } from '../../contract/api.js'
+import type {
+  ContextResponse,
+  HealthResponse,
+  PatchesResponse,
+  SharedCanvasFetchResponse,
+} from '../../contract/api.js'
+import { isLocalKey, parseReviewKey, type ReviewKey } from '../../contract/review-key.js'
 import { AppearanceInputSchema, type AppearanceResponse } from '../../contract/settings.js'
-import { createPrLoader, resolveBundle, runDiscovery } from '../bundle.js'
+import { publicHost } from '../../host/host.js'
+import { lookupCanvas } from '../../review/carry-over.js'
+import { createPrLoader, resolveBundle, resolveLocalBundle, runDiscovery } from '../bundle.js'
 import { BodyTooLargeError, readCappedBody } from '../capped-body.js'
 import type { AppContext } from '../context.js'
 import { AppError } from '../errors.js'
 import { chatRoutes } from './chat-routes.js'
 import { reviewRoutes } from './review-routes.js'
 
-export const PrNumberSchema = z.coerce.number().int().positive()
+/** The target a route's `:n` names: a pull request number, or `local` for work with no PR yet. */
+export function parseTargetKey(raw: string): ReviewKey {
+  const key = parseReviewKey(raw)
+  if (key === null) {
+    throw new AppError(
+      'BAD_REQUEST',
+      `not a review target: ${raw}`,
+      400,
+      'use a PR number, `branch`, or `uncommitted`'
+    )
+  }
+  return key
+}
 
-export function parsePrNumber(raw: string): number {
-  const parsed = PrNumberSchema.safeParse(raw)
-  if (!parsed.success) {
-    throw new AppError('BAD_REQUEST', `not a pull request number: ${raw}`, 400)
+/**
+ * The pull request behind a key, for the routes that talk to the forge. Local work has none, and
+ * saying so is better than letting the call fail somewhere inside the host client.
+ */
+export function requirePrNumber(key: ReviewKey, what: string): number {
+  if (isLocalKey(key)) {
+    throw new AppError(
+      'BAD_REQUEST',
+      `${what} needs a pull request, and this canvas describes work that has none yet`,
+      400,
+      'open the pull request, then review it at /review/<number>'
+    )
   }
-  return parsed.data
+  return key
 }
 
 const ContextQuerySchema = z.object({
@@ -69,12 +97,14 @@ function parseHeadShaQuery(raw: string | undefined): string | undefined {
 async function currentCanvasSha(
   ctx: AppContext,
   loader: ReturnType<typeof createPrLoader>,
-  number: number
+  key: ReviewKey
 ): Promise<string> {
-  const pr = await loader.currentPr(number)
-  const found = await ctx.canvases.findForPr(number, pr.headSha)
+  const pr = await loader.currentTarget(key)
+  const found = isLocalKey(key)
+    ? await ctx.canvases.findForLocal(key, pr.headSha)
+    : await lookupCanvas(ctx, key, pr)
   if (found.status === 'missing') {
-    throw new AppError('CANVAS_NOT_FOUND', `no canvas for pull request ${number}`, 404, 'generate one first')
+    throw new AppError('CANVAS_NOT_FOUND', `no canvas for ${String(key)}`, 404, 'generate one first')
   }
   return found.headSha
 }
@@ -87,7 +117,10 @@ export function apiRoutes(ctx: AppContext): Hono {
 
   // How the page is painted. It lives in the same settings file the chat settings do, but on its
   // own route, because a repository with chat off still has a page to paint.
-  const appearanceOf = (settings: { skin: AppearanceResponse['skin']; theme: AppearanceResponse['theme'] }) => ({
+  const appearanceOf = (settings: {
+    skin: AppearanceResponse['skin']
+    theme: AppearanceResponse['theme']
+  }) => ({
     skin: settings.skin,
     theme: settings.theme,
   })
@@ -148,6 +181,7 @@ export function apiRoutes(ctx: AppContext): Hono {
           : {}),
       },
       repo: ctx.config.repo,
+      host: publicHost(ctx.config.host),
       dataDir: ctx.config.dataDir,
       chat: {
         enabled: chatEnabled,
@@ -159,15 +193,24 @@ export function apiRoutes(ctx: AppContext): Hono {
   })
 
   api.get('/prs/:n', async c => {
-    const number = parsePrNumber(c.req.param('n'))
-    const bundle = await resolveBundle(ctx, loader, number, { refresh: c.req.query('refresh') === '1' })
+    const key = parseTargetKey(c.req.param('n'))
+    const opts = { refresh: c.req.query('refresh') === '1', poll: c.req.query('poll') === '1' }
+    const bundle = isLocalKey(key)
+      ? await resolveLocalBundle(ctx, loader, key, opts)
+      : await resolveBundle(ctx, loader, key, opts)
     return c.json(bundle)
   })
 
   api.get('/prs/:n/patches', async c => {
-    const number = parsePrNumber(c.req.param('n'))
-    const headSha = parseHeadShaQuery(c.req.query('headSha')) ?? (await loader.currentPr(number)).headSha
-    const derived = await ctx.derived.read(headSha)
+    const key = parseTargetKey(c.req.param('n'))
+    const pr = await loader.currentTarget(key)
+    const headSha = parseHeadShaQuery(c.req.query('headSha')) ?? pr.headSha
+    // Only the target's own head has a merge base to build from; any other sha the page names is
+    // an older canvas, whose diffs were written when that canvas was drawn.
+    const derived = await ctx.derived.readOrBuild(
+      headSha,
+      headSha === pr.headSha ? pr.mergeBaseSha : undefined
+    )
     if (derived === null) {
       throw new AppError(
         'NOT_FOUND',
@@ -181,13 +224,13 @@ export function apiRoutes(ctx: AppContext): Hono {
   })
 
   api.get('/prs/:n/comments', async c => {
-    const number = parsePrNumber(c.req.param('n'))
+    const number = requirePrNumber(parseTargetKey(c.req.param('n')), 'reading comments')
     const { comments } = await loader.refreshComments(number)
     return c.json(comments)
   })
 
   api.get('/prs/:n/context', async c => {
-    const number = parsePrNumber(c.req.param('n'))
+    const key = parseTargetKey(c.req.param('n'))
     const parsed = ContextQuerySchema.safeParse(c.req.query())
     if (!parsed.success) {
       throw new AppError('BAD_REQUEST', 'context needs path, side (new|old), from, to', 400)
@@ -196,20 +239,34 @@ export function apiRoutes(ctx: AppContext): Hono {
     if (q.to < q.from || q.to - q.from + 1 > CONTEXT_MAX_LINES) {
       throw new AppError('BAD_REQUEST', `request between 1 and ${CONTEXT_MAX_LINES} lines`, 400)
     }
-    const pr = await loader.currentPr(number)
-    const lines = await ctx.derived.readLines(pr.headSha, q.side === 'new' ? 'head' : 'base', q.path, q.from, q.to)
+    const pr = await loader.currentTarget(key)
+    const lines = await ctx.derived.readLines(
+      pr.headSha,
+      q.side === 'new' ? 'head' : 'base',
+      q.path,
+      q.from,
+      q.to
+    )
     if (lines === null) {
       throw new AppError('NOT_FOUND', `${q.path} is not materialized for this head`, 404)
     }
-    const body: ContextResponse = { path: q.path, side: q.side, from: q.from, to: q.from + lines.length - 1, lines }
+    const body: ContextResponse = {
+      path: q.path,
+      side: q.side,
+      from: q.from,
+      to: q.from + lines.length - 1,
+      lines,
+    }
     return c.json(body)
   })
 
   api.get('/prs/:n/export', async c => {
-    const number = parsePrNumber(c.req.param('n'))
+    const key = parseTargetKey(c.req.param('n'))
     const requested = parseHeadShaQuery(c.req.query('headSha'))
-    const headSha = requested ?? (await currentCanvasSha(ctx, loader, number))
-    const zip = await buildCanvasZipFor(ctx, headSha, number)
+    const headSha = requested ?? (await currentCanvasSha(ctx, loader, key))
+    // A local canvas is exported without a number, which is what makes it importable on the
+    // pull request once that exists.
+    const zip = await buildCanvasZipFor(ctx, headSha, isLocalKey(key) ? undefined : key)
     // The name is built from the repo slug, the PR number, and the sha, so it holds no user text.
     return new Response(new Blob([zip.bytes]), {
       headers: {
@@ -220,29 +277,33 @@ export function apiRoutes(ctx: AppContext): Hono {
   })
 
   api.post('/prs/:n/import', async c => {
-    const number = parsePrNumber(c.req.param('n'))
+    const number = requirePrNumber(parseTargetKey(c.req.param('n')), 'importing a shared canvas')
     const { file, force } = await readUpload(c.req.raw)
     if (!(file instanceof File)) {
       throw new AppError('BAD_REQUEST', 'send the zip as the multipart field `file`', 400)
     }
     if (file.size > CANVAS_ZIP_MAX_BYTES) {
-      throw new AppError('CANVAS_TOO_LARGE', `the canvas zip is larger than ${CANVAS_ZIP_MAX_BYTES} bytes`, 413)
+      throw new AppError(
+        'CANVAS_TOO_LARGE',
+        `the canvas zip is larger than ${CANVAS_ZIP_MAX_BYTES} bytes`,
+        413
+      )
     }
     const result = await importCanvas(ctx, {
       bytes: new Uint8Array(await file.arrayBuffer()),
       prNumber: number,
-      currentHeadSha: (await loader.currentPr(number)).headSha,
+      currentHead: await loader.currentPr(number),
       force: force === '1',
     })
     return c.json(result)
   })
 
   api.post('/prs/:n/shared-canvas/fetch', async c => {
-    const number = parsePrNumber(c.req.param('n'))
+    const number = requirePrNumber(parseTargetKey(c.req.param('n')), 'looking for a shared canvas')
     // Looking again means looking at the pull request as it is now, not at the cached copy.
     const { pr, comments } = await loader.load(number, { refresh: true })
     const discovery = await runDiscovery(ctx, pr, comments, { refresh: true })
-    const found = await ctx.canvases.findForPr(number, pr.headSha)
+    const found = await lookupCanvas(ctx, number, pr)
     const body: SharedCanvasFetchResponse = {
       imported: discovery.imported,
       status: found.status,