npm - @vintasoftware/pr-review-canvas - Versions diffs - 0.1.0 - Mend

@vintasoftware/pr-review-canvas 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (157) hide show

package/LICENSE +202 -0
package/README.md +192 -0
package/bin/pr-review.mjs +5 -0
package/docs/reference.md +340 -0
package/package.json +74 -0
package/pr-review.config.example.yml +68 -0
package/prompts/chat-seed.md +64 -0
package/prompts/generation-format.md +255 -0
package/prompts/generation-strict.md +34 -0
package/prompts/generation-surfacing.md +67 -0
package/prompts/layers-default.md +13 -0
package/prompts/quality-standards.md +32 -0
package/skills/pr-review-canvas/SKILL.md +177 -0
package/src/acpx/acpx.ts +530 -0
package/src/acpx/agents.ts +85 -0
package/src/acpx/events.ts +216 -0
package/src/acpx/ndjson.ts +69 -0
package/src/acpx/preflight.ts +44 -0
package/src/canvas/export.ts +95 -0
package/src/canvas/import.ts +138 -0
package/src/canvas/name.ts +55 -0
package/src/canvas/zip.ts +123 -0
package/src/chat/chat-manager.ts +389 -0
package/src/chat/context.ts +160 -0
package/src/chat/seed.ts +71 -0
package/src/chat/threads.ts +114 -0
package/src/cli.ts +199 -0
package/src/commands.ts +424 -0
package/src/config.ts +142 -0
package/src/contract/api.ts +190 -0
package/src/contract/canvas-manifest.ts +29 -0
package/src/contract/chat.ts +76 -0
package/src/contract/comments.ts +96 -0
package/src/contract/discovery.ts +20 -0
package/src/contract/generation-context.ts +77 -0
package/src/contract/keys.ts +14 -0
package/src/contract/links.ts +5 -0
package/src/contract/mermaid-fences.ts +4 -0
package/src/contract/review-artifact.ts +324 -0
package/src/contract/settings.ts +144 -0
package/src/contract/state.ts +46 -0
package/src/contract/validation.ts +43 -0
package/src/git/diff-collector.ts +151 -0
package/src/git/git.ts +115 -0
package/src/git/lang.ts +1 -0
package/src/git/materialize.ts +79 -0
package/src/git/patch-lines.ts +60 -0
package/src/github/attachments.ts +288 -0
package/src/github/capabilities.ts +112 -0
package/src/github/comments.ts +132 -0
package/src/github/gh.ts +196 -0
package/src/github/post-comment.ts +104 -0
package/src/github/post-review.ts +44 -0
package/src/github/pr.ts +133 -0
package/src/github/review-body.ts +72 -0
package/src/github/threads.ts +63 -0
package/src/paths.ts +10 -0
package/src/project-config.ts +219 -0
package/src/prompt-files.ts +26 -0
package/src/review/diagram-nodes.ts +227 -0
package/src/review/doctor.ts +139 -0
package/src/review/glob.ts +33 -0
package/src/review/install-skill.ts +107 -0
package/src/review/normalize.ts +209 -0
package/src/review/prepare.ts +165 -0
package/src/review/prompt.ts +233 -0
package/src/review/publish.ts +209 -0
package/src/review/skill-command.ts +4 -0
package/src/review/test-paths.ts +32 -0
package/src/review/text-length.ts +15 -0
package/src/review/trim-caps.ts +114 -0
package/src/review/validate-folds.ts +110 -0
package/src/review/validate.ts +520 -0
package/src/server/app.ts +46 -0
package/src/server/bundle.ts +266 -0
package/src/server/capped-body.ts +62 -0
package/src/server/context.ts +174 -0
package/src/server/env.ts +7 -0
package/src/server/errors.ts +65 -0
package/src/server/html.ts +140 -0
package/src/server/node-server.ts +42 -0
package/src/server/routes/api.ts +256 -0
package/src/server/routes/chat-routes.ts +221 -0
package/src/server/routes/pages.ts +64 -0
package/src/server/routes/review-routes.ts +245 -0
package/src/server/routes/static.ts +114 -0
package/src/server/security.ts +104 -0
package/src/server/sse.ts +67 -0
package/src/store/atomic-json.ts +68 -0
package/src/store/canvas-store.ts +120 -0
package/src/store/data-dir.ts +29 -0
package/src/store/derived-store.ts +93 -0
package/src/store/pr-store.ts +69 -0
package/src/store/settings-store.ts +152 -0
package/src/store/state-store.ts +121 -0
package/static/js/anchors.js +141 -0
package/static/js/api.js +542 -0
package/static/js/app.js +418 -0
package/static/js/ask.js +35 -0
package/static/js/chat-context.js +137 -0
package/static/js/chat-scroll.js +114 -0
package/static/js/chat.js +843 -0
package/static/js/code-folds.js +200 -0
package/static/js/commands.js +110 -0
package/static/js/comment-link.js +37 -0
package/static/js/composer.js +241 -0
package/static/js/contract-types.d.ts +59 -0
package/static/js/deep-link.js +160 -0
package/static/js/diagram.js +582 -0
package/static/js/diff-decorations.js +204 -0
package/static/js/diff-renderer.js +860 -0
package/static/js/dom.js +145 -0
package/static/js/download.js +52 -0
package/static/js/empty-state.js +161 -0
package/static/js/errors.js +135 -0
package/static/js/fences.js +90 -0
package/static/js/header.js +134 -0
package/static/js/hunks.js +62 -0
package/static/js/import-zone.js +95 -0
package/static/js/interactions.js +952 -0
package/static/js/keyboard.js +131 -0
package/static/js/keys.js +97 -0
package/static/js/lang.js +54 -0
package/static/js/layers.js +596 -0
package/static/js/links.js +150 -0
package/static/js/markdown.js +232 -0
package/static/js/mermaid-fences.js +55 -0
package/static/js/nav.js +91 -0
package/static/js/overview.js +85 -0
package/static/js/points.js +247 -0
package/static/js/progress.js +49 -0
package/static/js/proposed-comment.js +133 -0
package/static/js/quick-questions.js +216 -0
package/static/js/regenerate.js +69 -0
package/static/js/review-session.js +257 -0
package/static/js/scroll-spy.js +66 -0
package/static/js/selection.js +193 -0
package/static/js/settings.js +206 -0
package/static/js/signoff.js +171 -0
package/static/js/skin.js +56 -0
package/static/js/store.js +35 -0
package/static/js/theme.js +56 -0
package/static/js/threads.js +78 -0
package/static/js/vendor.d.ts +15 -0
package/static/styles/base.css +223 -0
package/static/styles/chat-tools.css +130 -0
package/static/styles/chat.css +140 -0
package/static/styles/commands.css +156 -0
package/static/styles/diff.css +258 -0
package/static/styles/header.css +114 -0
package/static/styles/layout.css +123 -0
package/static/styles/panels.css +152 -0
package/static/styles/responsive.css +80 -0
package/static/styles/review-actions.css +124 -0
package/static/styles/review.css +473 -0
package/static/styles/skin-github.css +356 -0
package/static/styles.css +14 -0

package/src/server/html.ts ADDED Viewed

@@ -0,0 +1,140 @@
+import { html, raw } from 'hono/html'
+import type { HtmlEscapedString } from 'hono/utils/html'
+import type { ErrorEnvelope, HomeData } from '../contract/api.js'
+import type { Appearance } from '../contract/settings.js'
+type Html = HtmlEscapedString | Promise<HtmlEscapedString>
+/** Bare names the browser modules import; the server maps them to `/vendor/*` files. */
+export const IMPORT_MAP = {
+  imports: {
+    diff: '/vendor/diff/index.js',
+    marked: '/vendor/marked.js',
+    dompurify: '/vendor/purify.js',
+    hljs: '/vendor/highlight.js',
+    mermaid: '/vendor/mermaid/mermaid.esm.min.mjs',
+  },
+} as const
+/**
+ * Names the page must not preload: mermaid is imported by `diagram.js` only when a screen holds a
+ * diagram, and most screens hold none.
+ */
+export const LAZY_IMPORTS: readonly string[] = ['mermaid']
+/** JSON that is safe inside a <script> element: no `<`, `>`, `&`, or line separators. */
+export function jsonForScript(value: unknown): string {
+  return JSON.stringify(value)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029')
+}
+export interface PageOptions {
+  title: string
+  bootstrap: unknown
+  body: Html
+  /** Load the app module. Off for the plain pages (home, error). */
+  app: boolean
+  /** The nonce of this response's Content-Security-Policy; the inline scripts carry it. */
+  nonce: string
+  /** How this page is painted, from the settings file or this request's `?skin` and `?theme`. */
+  appearance: Appearance
+}
+export function pageShell(opts: PageOptions): Html {
+  const preload = Object.entries(IMPORT_MAP.imports)
+    .filter(([name]) => !LAZY_IMPORTS.includes(name))
+    .map(([, href]) => href)
+  return html`<!doctype html>
+<html lang="en" data-skin="${opts.appearance.skin}" data-theme="${opts.appearance.theme}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${opts.title}</title>
+<link rel="stylesheet" href="/static/styles.css">
+<script type="importmap" nonce="${opts.nonce}">${raw(jsonForScript(IMPORT_MAP))}</script>
+${opts.app ? preload.map(href => html`<link rel="modulepreload" href="${href}">`) : ''}
+${opts.app ? html`<link rel="modulepreload" href="/static/js/app.js">` : ''}
+<script id="bootstrap" type="application/json" nonce="${opts.nonce}">${raw(jsonForScript(opts.bootstrap))}</script>
+</head>
+<body>
+${opts.body}
+${opts.app ? html`<script type="module" src="/static/js/app.js"></script>` : ''}
+</body>
+</html>`
+}
+export function reviewPage(
+  bootstrap: { prNumber: number; owner: string; repo: string; version: string },
+  nonce: string,
+  appearance: Appearance
+): Html {
+  return pageShell({
+    title: `PR #${bootstrap.prNumber} · ${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>`,
+  })
+}
+export function homePage(
+  data: HomeData & { owner: string; repo: string; version: string; port: number },
+  nonce: string,
+  appearance: Appearance
+): Html {
+  return pageShell({
+    title: 'PR review canvas',
+    bootstrap: { owner: data.owner, repo: data.repo, version: data.version },
+    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-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>
+</header>
+<main id="main" class="home">
+<section class="panel"><div class="panel-h"><h2>Open a pull request</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>
+<button class="cmd fill" type="submit">open</button>
+</form></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`<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>`
+      )}</ul>`
+}
+</section>
+</main>
+<footer><span>pr-review ${data.version}</span><span>localhost only · nothing leaves this machine except GitHub posts you confirm</span></footer>
+</div>`,
+  })
+}
+export function errorPage(error: ErrorEnvelope['error'], nonce: string, appearance: Appearance): Html {
+  return pageShell({
+    title: `Error · ${error.code}`,
+    bootstrap: { error },
+    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></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 ADDED Viewed

@@ -0,0 +1,42 @@
+import { serve } from '@hono/node-server'
+import { createApp } from './app.js'
+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 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(`data dir ${ctx.config.dataDir}`)
+    if (ctx.fixtureArtifact !== null) {
+      log(`fixture canvas ${ctx.config.fixtureCanvasPath ?? ''} (dev only): every PR reports ready`)
+    }
+    for (const w of ctx.projectConfig.warnings) {
+      log(`warning: ${w}`)
+    }
+  })
+  let closed = false
+  const close = (): void => {
+    if (closed) {
+      return
+    }
+    closed = true
+    // A browser holds its keep-alive socket open, and `close()` alone waits for it, so Ctrl-C
+    // would look like a hung process. Dropping the sockets ends the wait. HTTP/2 servers have no
+    // such method, and this one never is one.
+    if ('closeAllConnections' in server && typeof server.closeAllConnections === 'function') {
+      server.closeAllConnections()
+    }
+    server.close()
+    process.off('SIGINT', onSignal)
+    process.off('SIGTERM', onSignal)
+  }
+  const onSignal = (): void => {
+    close()
+    log('stopped')
+    process.exit(0)
+  }
+  process.once('SIGINT', onSignal)
+  process.once('SIGTERM', onSignal)
+  return { close }
+}

package/src/server/routes/api.ts ADDED Viewed

@@ -0,0 +1,256 @@
+import { Hono } from 'hono'
+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 { AppearanceInputSchema, type AppearanceResponse } from '../../contract/settings.js'
+import { createPrLoader, resolveBundle, 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()
+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)
+  }
+  return parsed.data
+}
+const ContextQuerySchema = z.object({
+  path: z.string().min(1),
+  side: z.enum(['new', 'old']),
+  from: z.coerce.number().int().positive(),
+  to: z.coerce.number().int().positive(),
+})
+export const CONTEXT_MAX_LINES = 500
+const SHA_RE = /^[0-9a-f]{40}$/
+/** The multipart envelope of a 20 MB zip, with room for the field headers. */
+export const MAX_UPLOAD_BYTES = CANVAS_ZIP_MAX_BYTES + 64 * 1024
+/**
+ * The multipart form of an upload, read under the cap first. Parsing is done on the bytes we
+ * already hold, so a request that never declares its length cannot buffer without limit.
+ */
+async function readUpload(request: Request): Promise<{ file: unknown; force: unknown }> {
+  let body: Uint8Array<ArrayBuffer>
+  try {
+    body = await readCappedBody(request, MAX_UPLOAD_BYTES)
+  } catch (err) {
+    if (err instanceof BodyTooLargeError) {
+      throw new AppError('CANVAS_TOO_LARGE', 'the upload is larger than the canvas size limit', 413)
+    }
+    throw err
+  }
+  const contentType = request.headers.get('content-type')
+  if (contentType === null || !contentType.startsWith('multipart/form-data')) {
+    throw new AppError('BAD_REQUEST', 'send the zip as multipart/form-data', 400)
+  }
+  const form = await new Response(new Blob([body]), { headers: { 'content-type': contentType } }).formData()
+  return { file: form.get('file'), force: form.get('force') }
+}
+function parseHeadShaQuery(raw: string | undefined): string | undefined {
+  if (raw !== undefined && !SHA_RE.test(raw)) {
+    throw new AppError('BAD_REQUEST', 'headSha must be a 40-character lowercase hex sha', 400)
+  }
+  return raw
+}
+/** The canvas the page is showing: the one for the head, else the stale one it fell back to. */
+async function currentCanvasSha(
+  ctx: AppContext,
+  loader: ReturnType<typeof createPrLoader>,
+  number: number
+): Promise<string> {
+  const pr = await loader.currentPr(number)
+  const found = await ctx.canvases.findForPr(number, pr.headSha)
+  if (found.status === 'missing') {
+    throw new AppError('CANVAS_NOT_FOUND', `no canvas for pull request ${number}`, 404, 'generate one first')
+  }
+  return found.headSha
+}
+export function apiRoutes(ctx: AppContext): Hono {
+  const api = new Hono()
+  const loader = createPrLoader(ctx)
+  api.route('/', reviewRoutes(ctx, loader))
+  api.route('/', chatRoutes(ctx, loader))
+  // 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'] }) => ({
+    skin: settings.skin,
+    theme: settings.theme,
+  })
+  api.get('/appearance', async c => {
+    const body: AppearanceResponse = appearanceOf(await ctx.settings.read())
+    return c.json(body)
+  })
+  api.put('/appearance', async c => {
+    const expected = 'send a JSON body: { "skin": "github", "theme": "dark" }'
+    let raw: unknown
+    try {
+      raw = await c.req.raw.json()
+    } catch {
+      throw new AppError('BAD_REQUEST', expected, 400)
+    }
+    const parsed = AppearanceInputSchema.safeParse(raw)
+    if (!parsed.success) {
+      throw new AppError('BAD_REQUEST', expected, 400, parsed.error.issues[0]?.message)
+    }
+    const body: AppearanceResponse = appearanceOf(await ctx.settings.write(parsed.data))
+    return c.json(body)
+  })
+  api.get('/health', async c => {
+    const chatEnabled = ctx.projectConfig.config.chat.enabled
+    const [gitCheck, ghStatus, acpx, agents] = await Promise.all([
+      ctx.git
+        .topLevel()
+        .then(() => ({ ok: true }))
+        .catch((err: unknown) => ({ ok: false, detail: err instanceof Error ? err.message : String(err) })),
+      ctx.gh.authStatus(),
+      chatEnabled ? ctx.preflight.get() : Promise.resolve({ installed: false, version: null }),
+      chatEnabled ? ctx.agents.list() : Promise.resolve(null),
+    ])
+    const settings = chatEnabled ? await ctx.chat.effectiveSettings() : null
+    const active = settings === null ? null : (agents?.agents.find(a => a.id === settings.agent) ?? null)
+    const body: HealthResponse = {
+      ok: gitCheck.ok && ghStatus.installed && ghStatus.authenticated,
+      version: ctx.version,
+      checks: {
+        git: gitCheck,
+        origin: { ok: true, detail: `${ctx.config.repo.owner}/${ctx.config.repo.name}` },
+        gh: ghStatus.installed ? { ok: true } : { ok: false, detail: ghStatus.detail },
+        ghAuth: ghStatus.authenticated ? { ok: true } : { ok: false, detail: ghStatus.detail },
+        ...(chatEnabled
+          ? {
+              acpx: acpx.installed
+                ? { ok: true, detail: acpx.version ?? '' }
+                : { ok: false, detail: 'acpx is not on PATH' },
+              agentInstalled: {
+                ok: active?.installed === true,
+                ...(active?.reason === undefined ? {} : { detail: active.reason }),
+              },
+              agentAuth: { ok: active?.authenticated === true },
+            }
+          : {}),
+      },
+      repo: ctx.config.repo,
+      dataDir: ctx.config.dataDir,
+      chat: {
+        enabled: chatEnabled,
+        acpx: acpx.installed,
+        ...(settings === null ? {} : { agent: settings.agent, model: settings.model }),
+      },
+    }
+    return c.json(body)
+  })
+  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' })
+    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)
+    if (derived === null) {
+      throw new AppError(
+        'NOT_FOUND',
+        'diffs for this head are not available locally',
+        404,
+        'fetch the PR head and reload'
+      )
+    }
+    const body: PatchesResponse = { headSha, patches: derived.patches }
+    return c.json(body)
+  })
+  api.get('/prs/:n/comments', async c => {
+    const number = parsePrNumber(c.req.param('n'))
+    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 parsed = ContextQuerySchema.safeParse(c.req.query())
+    if (!parsed.success) {
+      throw new AppError('BAD_REQUEST', 'context needs path, side (new|old), from, to', 400)
+    }
+    const q = parsed.data
+    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)
+    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 }
+    return c.json(body)
+  })
+  api.get('/prs/:n/export', async c => {
+    const number = parsePrNumber(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)
+    // 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: {
+        'content-type': 'application/zip',
+        'content-disposition': `attachment; filename="${zip.name}"`,
+      },
+    })
+  })
+  api.post('/prs/:n/import', async c => {
+    const number = parsePrNumber(c.req.param('n'))
+    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)
+    }
+    const result = await importCanvas(ctx, {
+      bytes: new Uint8Array(await file.arrayBuffer()),
+      prNumber: number,
+      currentHeadSha: (await loader.currentPr(number)).headSha,
+      force: force === '1',
+    })
+    return c.json(result)
+  })
+  api.post('/prs/:n/shared-canvas/fetch', async c => {
+    const number = parsePrNumber(c.req.param('n'))
+    // 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 body: SharedCanvasFetchResponse = {
+      imported: discovery.imported,
+      status: found.status,
+      sharedCanvas: discovery.sharedCanvas,
+      warnings: discovery.warnings,
+    }
+    return c.json(body)
+  })
+  return api
+}

package/src/server/routes/chat-routes.ts ADDED Viewed

@@ -0,0 +1,221 @@
+// The AI Chat pane's routes and the personal settings behind it. Every route here answers 404
+// when the project config turns chat off, so a repository that does not want an agent in the
+// loop has no agent surface at all.
+import { Hono, type MiddlewareHandler } from 'hono'
+import { ChatBusyError } from '../../chat/chat-manager.js'
+import { ChatContextError } from '../../chat/context.js'
+import { isThreadNameFor } from '../../chat/threads.js'
+import type { ChatEvent, ChatHistoryResponse } from '../../contract/chat.js'
+import { ChatSendSchema } from '../../contract/chat.js'
+import type { Pr, ReviewArtifact } from '../../contract/review-artifact.js'
+import type { SettingsResponse } from '../../contract/settings.js'
+import { isChatAgent, SettingsInputSchema } from '../../contract/settings.js'
+import type { PrLoader } from '../bundle.js'
+import type { AppContext } from '../context.js'
+import { AppError } from '../errors.js'
+import { SSE_HEADERS, sseStream } from '../sse.js'
+import { parsePrNumber } from './api.js'
+async function readJsonBody<T>(
+  request: Request,
+  schema: {
+    safeParse: (raw: unknown) => { success: boolean; data?: T; error?: { issues: Array<{ message: string }> } }
+  },
+  expected: string
+): Promise<T> {
+  let raw: unknown
+  try {
+    raw = await request.json()
+  } catch {
+    throw new AppError('BAD_REQUEST', `send a JSON body: ${expected}`, 400)
+  }
+  const parsed = schema.safeParse(raw)
+  if (!parsed.success || parsed.data === undefined) {
+    throw new AppError('BAD_REQUEST', `send a JSON body: ${expected}`, 400, parsed.error?.issues[0]?.message)
+  }
+  return parsed.data
+}
+function settingsResponse(ctx: AppContext, settings: SettingsResponse['settings']): SettingsResponse {
+  const project = ctx.projectConfig.config
+  return {
+    settings,
+    overrides: ctx.config.chatOverrides,
+    file: ctx.settings.file,
+    project: {
+      file: ctx.projectConfig.source,
+      chatEnabled: project.chat.enabled,
+      rulebook: project.rulebook ?? null,
+      maxRepairRounds: project.generation.maxRepairRounds,
+      inlineDiffMaxLines: project.generation.inlineDiffMaxLines,
+      smallPrHunks: project.generation.smallPrHunks,
+      layers: project.layers.length,
+      highRisk: project.highRisk.length,
+    },
+  }
+}
+/** The canvas the chat talks about: the one written for the pull request's current head. */
+async function artifactForChat(ctx: AppContext, number: number, pr: Pr): Promise<ReviewArtifact> {
+  if (ctx.fixtureArtifact !== null) {
+    return { ...ctx.fixtureArtifact, pr }
+  }
+  const found = await ctx.canvases.findForPr(number, pr.headSha)
+  const artifact = found.status === 'ready' ? await ctx.canvases.readArtifact(found.headSha) : null
+  if (artifact === null) {
+    throw new AppError(
+      'CANVAS_NOT_FOUND',
+      'there is no canvas for this commit, so the chat has nothing to talk about',
+      404,
+      'generate a canvas for the current head first'
+    )
+  }
+  return artifact
+}
+/** Every path this file serves, so the chat-disabled check covers all of them and nothing else. */
+export const CHAT_ROUTE_PATTERNS = ['/settings', '/settings/*', '/prs/:n/chat', '/prs/:n/chat/*'] as const
+export function chatRoutes(ctx: AppContext, loader: PrLoader): Hono {
+  const api = new Hono()
+  // With chat off, none of these routes exist. The patterns are listed rather than `*`: this
+  // app is mounted at the API root, so a blanket middleware would answer for every route.
+  const requireChat: MiddlewareHandler = async (_c, next) => {
+    if (!ctx.projectConfig.config.chat.enabled) {
+      throw new AppError(
+        'NOT_FOUND',
+        'chat is turned off for this repository',
+        404,
+        'set chat.enabled in pr-review.config.yml'
+      )
+    }
+    await next()
+  }
+  for (const pattern of CHAT_ROUTE_PATTERNS) {
+    api.use(pattern, requireChat)
+  }
+  api.get('/settings', async c => {
+    await ctx.settings.ensureFile()
+    return c.json(settingsResponse(ctx, await ctx.settings.read()))
+  })
+  api.put('/settings', async c => {
+    const input = await readJsonBody(c.req.raw, SettingsInputSchema, '{ "agent": "claude", "model": null }')
+    return c.json(settingsResponse(ctx, await ctx.settings.write(input)))
+  })
+  api.get('/settings/agents', async c => c.json(await ctx.agents.list({ refresh: c.req.query('refresh') === '1' })))
+  api.post('/settings/agents/:id/probe', async c => {
+    const id = c.req.param('id')
+    if (!isChatAgent(id)) {
+      throw new AppError('BAD_REQUEST', `not an agent this tool knows: ${id}`, 400)
+    }
+    return c.json(await ctx.agents.probe(id, { refresh: c.req.query('refresh') === '1' }))
+  })
+  api.get('/prs/:n/chat/threads', async c => c.json(await ctx.chat.threads(parsePrNumber(c.req.param('n')))))
+  api.post('/prs/:n/chat/threads', async c => {
+    const number = parsePrNumber(c.req.param('n'))
+    const thread = await ctx.chat.createThread(number)
+    return c.json({ thread, ...(await ctx.chat.threads(number)) }, 201)
+  })
+  api.get('/prs/:n/chat/threads/:name/history', async c => {
+    const number = parsePrNumber(c.req.param('n'))
+    const name = c.req.param('name')
+    if (!isThreadNameFor(name, number)) {
+      throw new AppError('NOT_FOUND', `no chat thread named ${name} on this pull request`, 404)
+    }
+    const body: ChatHistoryResponse = { name, turns: await ctx.transcripts.read(number, name) }
+    return c.json(body)
+  })
+  api.post('/prs/:n/chat/cancel', async c => {
+    const number = parsePrNumber(c.req.param('n'))
+    return c.json({ cancelled: await ctx.chat.cancel(number) })
+  })
+  api.post('/prs/:n/chat', async c => {
+    const number = parsePrNumber(c.req.param('n'))
+    const input = await readJsonBody(c.req.raw, ChatSendSchema, '{ "message": "…", "context": { "kind": "pr" } }')
+    const pr = await loader.currentPr(number)
+    const artifact = await artifactForChat(ctx, number, pr)
+    const derived = await ctx.derived.read(pr.headSha)
+    if (derived === null) {
+      throw new AppError(
+        'NOT_FOUND',
+        'the diff of this head is not available locally, so the chat cannot quote it',
+        404,
+        'fetch the PR head and reload'
+      )
+    }
+    const events = ctx.chat.send(
+      {
+        prNumber: number,
+        headSha: pr.headSha,
+        artifact,
+        files: derived.files,
+        patches: derived.patches,
+        derivedDir: ctx.derived.derivedDir(pr.headSha),
+        readLines: (side, filePath, from, to) => ctx.derived.readLines(pr.headSha, side, filePath, from, to),
+      },
+      { message: input.message, context: input.context, thread: input.thread }
+    )
+    // The first event comes back before the response starts, so a refusal is a JSON envelope
+    // with a status rather than an error frame inside a 200.
+    const iterator = events[Symbol.asyncIterator]()
+    let first: IteratorResult<ChatEvent>
+    try {
+      first = await iterator.next()
+    } catch (err) {
+      throw toChatError(err)
+    }
+    // A browser that goes away stops the agent; the turn is nobody's answer any more.
+    return new Response(
+      sseStream(replayFrom(first, iterator), undefined, () => {
+        void ctx.chat.cancel(number)
+      }),
+      { headers: SSE_HEADERS }
+    )
+  })
+  return api
+}
+/**
+ * The turn as a stream again, after its first event was read to see whether the route can answer
+ * with a stream at all. A turn that ended on that first read is an empty stream.
+ */
+export function replayFrom(first: IteratorResult<ChatEvent>, rest: AsyncIterator<ChatEvent>): AsyncIterable<ChatEvent> {
+  let sent = first.done === true
+  return {
+    [Symbol.asyncIterator]: () => ({
+      next: () => {
+        if (sent) {
+          return rest.next()
+        }
+        sent = true
+        return Promise.resolve({ done: false, value: first.value })
+      },
+      return: async () => {
+        await rest.return?.(undefined)
+        return { done: true, value: undefined }
+      },
+    }),
+  }
+}
+/** The status a refused turn answers with: busy, a context that does not resolve, or a failure. */
+export function toChatError(err: unknown): AppError {
+  if (err instanceof ChatBusyError) {
+    return new AppError('CHAT_BUSY', err.message, 409, 'stop the running answer, or wait for it to finish')
+  }
+  if (err instanceof ChatContextError) {
+    return new AppError('BAD_REQUEST', err.message, 400)
+  }
+  return err instanceof AppError ? err : new AppError('INTERNAL', err instanceof Error ? err.message : String(err), 500)
+}