@vintasoftware/pr-review-canvas 0.1.0

package/src/acpx/events.ts

@@ -0,0 +1,216 @@
+/**
+ * Turns acpx's `--format json` lines into the small event set the chat needs, and decides what
+ * may be written to the raw event log.
+ *
+ * Verified against acpx 0.13.2 in the phase 6 spike: `--format json` prints one ACP JSON-RPC
+ * message per line. `session/update` notifications carry `params.update.sessionUpdate`; the
+ * `session/prompt` result carries `stopReason`; failures arrive as a JSON-RPC error whose
+ * `data.detailCode` names the cause (`AUTH_REQUIRED` and friends).
+ */
+
+export const AGENT_ERROR_CODES = [
+  'AGENT_AUTH_REQUIRED',
+  'AGENT_PROTOCOL_INVALID',
+  'AGENT_INCOMPLETE',
+  'AGENT_TIMEOUT',
+  'AGENT_PERMISSION_DENIED',
+  'AGENT_NO_SESSION',
+  'AGENT_USAGE',
+  'AGENT_INTERRUPTED',
+  'AGENT_FAILED',
+  'AGENT_MISSING',
+] as const
+export type AgentErrorCode = (typeof AGENT_ERROR_CODES)[number]
+
+export type AgentEvent =
+  | { type: 'chunk'; text: string }
+  | { type: 'thought'; text: string }
+  | { type: 'tool'; id: string; title: string; status: string }
+  | { type: 'usage'; used: number; size: number }
+  | { type: 'plan'; entries: number }
+  | { type: 'done'; stopReason: string }
+  | { type: 'error'; code: AgentErrorCode; message: string }
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** One field by name. Reading through a helper keeps the literal-key lint rule happy. */
+function read(source: Record<string, unknown>, key: string): unknown {
+  return source[key]
+}
+
+function readString(source: Record<string, unknown>, key: string): string | undefined {
+  const value = read(source, key)
+  return typeof value === 'string' ? value : undefined
+}
+
+function readNumber(source: Record<string, unknown>, key: string): number {
+  const value = read(source, key)
+  return typeof value === 'number' ? value : 0
+}
+
+/** The text of an ACP content block, which is `{ type: 'text', text }` for everything we show. */
+function contentText(value: unknown): string {
+  if (!isRecord(value)) {
+    return ''
+  }
+  return readString(value, 'text') ?? ''
+}
+
+/**
+ * The event one acpx line means, or null for a line the chat ignores (the handshake, the command
+ * list, session titles).
+ */
+export function mapAcpxMessage(message: unknown): AgentEvent | null {
+  if (!isRecord(message)) {
+    return { type: 'error', code: 'AGENT_PROTOCOL_INVALID', message: 'the agent wrote a line that is not a message' }
+  }
+  const error = read(message, 'error')
+  if (isRecord(error)) {
+    return mapErrorObject(error)
+  }
+  const result = read(message, 'result')
+  if (isRecord(result)) {
+    const stopReason = readString(result, 'stopReason')
+    return stopReason === undefined ? null : { type: 'done', stopReason }
+  }
+  if (read(message, 'method') !== 'session/update') {
+    return null
+  }
+  const params = read(message, 'params')
+  const update = isRecord(params) ? read(params, 'update') : undefined
+  return isRecord(update) ? mapUpdate(update) : null
+}
+
+function mapUpdate(update: Record<string, unknown>): AgentEvent | null {
+  switch (read(update, 'sessionUpdate')) {
+    case 'agent_message_chunk':
+      return { type: 'chunk', text: contentText(read(update, 'content')) }
+    case 'agent_thought_chunk':
+      return { type: 'thought', text: contentText(read(update, 'content')) }
+    case 'tool_call':
+    case 'tool_call_update':
+      return {
+        type: 'tool',
+        id: readString(update, 'toolCallId') ?? '',
+        title: readString(update, 'title') ?? readString(update, 'kind') ?? 'tool',
+        status: readString(update, 'status') ?? 'pending',
+      }
+    case 'usage_update':
+      return { type: 'usage', used: readNumber(update, 'used'), size: readNumber(update, 'size') }
+    case 'plan': {
+      const entries = read(update, 'entries')
+      return { type: 'plan', entries: Array.isArray(entries) ? entries.length : 0 }
+    }
+    default:
+      return null
+  }
+}
+
+/** acpx names the cause in `data.detailCode`; the JSON-RPC code alone says only "it failed". */
+function mapErrorObject(error: Record<string, unknown>): AgentEvent {
+  const data = read(error, 'data')
+  const detail = isRecord(data) ? readString(data, 'detailCode') : undefined
+  const message = readString(error, 'message') ?? 'the agent reported an error'
+  return { type: 'error', code: detailCodeToAgentCode(detail), message }
+}
+
+export function detailCodeToAgentCode(detail: string | undefined): AgentErrorCode {
+  switch (detail) {
+    case 'AUTH_REQUIRED':
+      return 'AGENT_AUTH_REQUIRED'
+    case 'PERMISSION_DENIED':
+      return 'AGENT_PERMISSION_DENIED'
+    case 'TIMEOUT':
+      return 'AGENT_TIMEOUT'
+    case 'NO_SESSION':
+      return 'AGENT_NO_SESSION'
+    default:
+      return 'AGENT_FAILED'
+  }
+}
+
+/**
+ * What an acpx exit code means. Verified in the spike: a usage error exits 2, a failed spawn
+ * exits 1, and acpx's own `--timeout` exits 0 with no terminal event at all.
+ */
+export function exitCodeToAgentCode(code: number): AgentErrorCode | null {
+  switch (code) {
+    case 0:
+      return null
+    case 2:
+      return 'AGENT_USAGE'
+    case 3:
+      return 'AGENT_TIMEOUT'
+    case 4:
+      return 'AGENT_NO_SESSION'
+    case 5:
+      return 'AGENT_PERMISSION_DENIED'
+    case 130:
+      return 'AGENT_INTERRUPTED'
+    default:
+      return 'AGENT_FAILED'
+  }
+}
+
+export function exitCodeMessage(code: number): string {
+  switch (code) {
+    case 2:
+      return 'acpx rejected the command line'
+    case 3:
+      return 'acpx timed out waiting for the agent'
+    case 4:
+      return 'the chat session no longer exists'
+    case 5:
+      return 'the agent was denied a permission it needed'
+    case 130:
+      return 'the agent was interrupted'
+    default:
+      return `acpx exited with code ${code}`
+  }
+}
+
+/**
+ * Lines the raw event log may keep, with everything sensitive taken out.
+ *
+ * `--suppress-reads` blanks the visible tool output but leaves the file's content under
+ * `_meta.claudeCode.toolResponse`, so `_meta` is dropped everywhere. Two whole lines are dropped
+ * as well: the auth notification names the signed-in account, and acpx echoes the `session/prompt`
+ * request, whose text holds the lines the reader selected.
+ */
+export function scrubForLog(message: unknown): unknown | null {
+  if (!isRecord(message)) {
+    return null
+  }
+  const method = read(message, 'method')
+  if (method === '_auth/status_update' || method === 'session/prompt') {
+    return null
+  }
+  const params = read(message, 'params')
+  const update = isRecord(params) ? read(params, 'update') : undefined
+  if (isRecord(update)) {
+    const kind = read(update, 'sessionUpdate')
+    if (kind === 'available_commands_update') {
+      return null
+    }
+  }
+  return withoutMeta(message)
+}
+
+function withoutMeta(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(withoutMeta)
+  }
+  if (!isRecord(value)) {
+    return value
+  }
+  const out: Record<string, unknown> = {}
+  for (const [key, item] of Object.entries(value)) {
+    if (key === '_meta') {
+      continue
+    }
+    out[key] = withoutMeta(item)
+  }
+  return out
+}

package/src/acpx/ndjson.ts

@@ -0,0 +1,69 @@
+/**
+ * Splits a byte stream into JSON lines. acpx writes one JSON-RPC message per line, so a line
+ * that never ends, or one too long to be a message, is a protocol failure rather than something
+ * to buffer without limit.
+ */
+
+/** A single ACP message is small; anything past this is not one. */
+export const NDJSON_LINE_MAX = 1024 * 1024
+
+export class NdjsonError extends Error {
+  readonly code = 'AGENT_PROTOCOL_INVALID'
+
+  constructor(message: string) {
+    super(message)
+    this.name = 'NdjsonError'
+  }
+}
+
+export interface NdjsonSplitter {
+  /** The messages completed by this chunk, in order. */
+  push(chunk: string): unknown[]
+  /** The last message when the stream ended without a newline. */
+  flush(): unknown[]
+}
+
+/**
+ * `JSON.parse` is one of the two places this package casts: what comes back is unknown, and the
+ * caller validates it.
+ */
+function parseLine(line: string): unknown {
+  try {
+    return JSON.parse(line) as unknown
+  } catch {
+    throw new NdjsonError(`the agent wrote a line that is not JSON (${line.length} characters)`)
+  }
+}
+
+export function createNdjsonSplitter(lineMax: number = NDJSON_LINE_MAX): NdjsonSplitter {
+  let buffer = ''
+  const take = (raw: string): unknown[] => {
+    const line = raw.trim()
+    return line === '' ? [] : [parseLine(line)]
+  }
+  return {
+    push(chunk) {
+      buffer += chunk
+      const out: unknown[] = []
+      let at = buffer.indexOf('\n')
+      while (at !== -1) {
+        const raw = buffer.slice(0, at)
+        buffer = buffer.slice(at + 1)
+        if (raw.length > lineMax) {
+          throw new NdjsonError(`the agent wrote a line of ${raw.length} characters, over the ${lineMax} limit`)
+        }
+        out.push(...take(raw))
+        at = buffer.indexOf('\n')
+      }
+      if (buffer.length > lineMax) {
+        throw new NdjsonError(`the agent wrote over ${lineMax} characters without ending the line`)
+      }
+      return out
+    },
+    flush() {
+      const rest = buffer
+      buffer = ''
+      return take(rest)
+    },
+  }
+}

package/src/acpx/preflight.ts

@@ -0,0 +1,44 @@
+import type { AgentRunner } from './acpx.js'
+
+/** How long the acpx presence check is reused. */
+export const PREFLIGHT_TTL_MS = 10 * 60 * 1000
+
+export interface AcpxPreflight {
+  installed: boolean
+  version: string | null
+}
+
+export interface PreflightProbe {
+  get(opts?: { refresh?: boolean }): Promise<AcpxPreflight>
+}
+
+/**
+ * Is acpx on PATH? The answer barely changes while the server runs, so it is asked once and
+ * reused; the page shows a banner and hides the chat when it says no.
+ */
+export function createPreflightProbe(runner: AgentRunner, now: () => Date, ttlMs = PREFLIGHT_TTL_MS): PreflightProbe {
+  let cached: { at: number; value: AcpxPreflight } | null = null
+  let inFlight: Promise<AcpxPreflight> | null = null
+  return {
+    async get(opts = {}) {
+      const at = now().getTime()
+      if (opts.refresh !== true && cached !== null && at - cached.at < ttlMs) {
+        return cached.value
+      }
+      if (inFlight !== null) {
+        return inFlight
+      }
+      inFlight = runner
+        .acpxVersion()
+        .then(version => {
+          const value: AcpxPreflight = { installed: version !== null, version }
+          cached = { at: now().getTime(), value }
+          return value
+        })
+        .finally(() => {
+          inFlight = null
+        })
+      return inFlight
+    },
+  }
+}

package/src/canvas/export.ts

@@ -0,0 +1,95 @@
+// Building the zip a human attaches to the pull request. The bytes are built once and either
+// written to a file (CLI) or streamed to the browser (the header's export command).
+import { mkdir, stat, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import type { CanvasManifest } from '../contract/canvas-manifest.js'
+import type { AppContext } from '../server/context.js'
+import { AppError } from '../server/errors.js'
+import { buildCanvasZipName } from './name.js'
+import { buildCanvasZip } from './zip.js'
+
+export interface CanvasZip {
+  name: string
+  bytes: Uint8Array<ArrayBuffer>
+  headSha: string
+  prNumber?: number
+}
+
+/**
+ * The zip for one stored canvas. `prNumber` stamps a canvas exported before the pull request
+ * existed, so the file name and the manifest name the PR.
+ */
+export async function buildCanvasZipFor(
+  ctx: AppContext,
+  headSha: string,
+  prNumber?: number | undefined
+): Promise<CanvasZip> {
+  const artifact = await ctx.canvases.readArtifact(headSha)
+  const stored = await ctx.canvases.readManifest(headSha)
+  if (artifact === null || stored === null) {
+    throw new AppError(
+      'CANVAS_NOT_FOUND',
+      `no canvas for ${headSha.slice(0, 7)}`,
+      404,
+      'generate one with the pr-review-canvas skill, or pass a head that has one'
+    )
+  }
+  const number = prNumber ?? stored.prNumber
+  const manifest: CanvasManifest = number === undefined ? stored : { ...stored, prNumber: number }
+  const zip: CanvasZip = {
+    name: buildCanvasZipName({ repo: manifest.repo, headSha, prNumber: number }),
+    bytes: buildCanvasZip(manifest, artifact),
+    headSha,
+  }
+  if (number !== undefined) {
+    zip.prNumber = number
+  }
+  return zip
+}
+
+export interface ExportResult {
+  status: 'exported'
+  path: string
+  name: string
+  headSha: string
+  prNumber?: number
+}
+
+async function isDirectory(target: string): Promise<boolean> {
+  try {
+    return (await stat(target)).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/** `--out` names a file when it ends in `.zip` or is not an existing directory. */
+export async function resolveOutPath(out: string | undefined, defaultDir: string, name: string): Promise<string> {
+  if (out === undefined) {
+    return path.join(defaultDir, name)
+  }
+  const resolved = path.resolve(out)
+  if (resolved.toLowerCase().endsWith('.zip')) {
+    return resolved
+  }
+  return (await isDirectory(resolved)) ? path.join(resolved, name) : resolved
+}
+
+export function defaultExportDir(ctx: AppContext): string {
+  return path.join(ctx.config.dataDir, 'exports')
+}
+
+export async function exportCanvas(
+  ctx: AppContext,
+  opts: { headSha: string; prNumber?: number | undefined; out?: string | undefined }
+): Promise<ExportResult> {
+  const zip = await buildCanvasZipFor(ctx, opts.headSha, opts.prNumber)
+  const file = await resolveOutPath(opts.out, defaultExportDir(ctx), zip.name)
+  await mkdir(path.dirname(file), { recursive: true })
+  await writeFile(file, zip.bytes)
+  const result: ExportResult = { status: 'exported', path: file, name: zip.name, headSha: zip.headSha }
+  if (zip.prNumber !== undefined) {
+    result.prNumber = zip.prNumber
+  }
+  return result
+}

package/src/canvas/import.ts

@@ -0,0 +1,138 @@
+// One import path for the three ways a canvas arrives: the drop zone, `pr-review import`, and a
+// zip discovered on the pull request. Everything is checked here, so no caller can skip a step.
+import type { CanvasRelation, ImportResult } from '../contract/api.js'
+import type { CanvasManifest } from '../contract/canvas-manifest.js'
+import type { ReviewArtifact } from '../contract/review-artifact.js'
+import type { AppContext } from '../server/context.js'
+import { AppError } from '../server/errors.js'
+import { CanvasZipError, readCanvasZip } from './zip.js'
+
+export interface ImportOptions {
+  bytes: Uint8Array
+  /** The pull request the canvas is imported for; recorded on the canvas. */
+  prNumber?: number | undefined
+  /** The head the page is looking at. Absent means the canvas is taken as the current one. */
+  currentHeadSha?: string | undefined
+  /** Accepts a canvas exported from another repository. */
+  force?: boolean | undefined
+}
+
+function sameRepo(a: { owner: string; name: string }, b: { owner: string; name: string }): boolean {
+  return a.owner.toLowerCase() === b.owner.toLowerCase() && a.name.toLowerCase() === b.name.toLowerCase()
+}
+
+/** The zip error as the HTTP envelope the routes and the CLI both report. */
+export function toAppErrorFromZip(err: CanvasZipError): AppError {
+  if (err.code === 'CANVAS_TOO_LARGE') {
+    return new AppError('CANVAS_TOO_LARGE', err.message, 413, 'a review canvas is a few hundred kilobytes')
+  }
+  return new AppError('CANVAS_INVALID', err.message, 400, err.issues[0], err.issues)
+}
+
+/**
+ * Fetches the head commit when the clone does not have it, so an imported canvas can show its
+ * diffs. A clone that cannot reach the commit reports `derivable: false` instead of failing.
+ */
+async function ensureDerived(
+  ctx: AppContext,
+  headSha: string,
+  mergeBaseSha: string,
+  warnings: string[]
+): Promise<boolean> {
+  if (!(await ctx.derived.derivable(headSha, mergeBaseSha))) {
+    try {
+      await ctx.git.fetch('origin', [headSha, mergeBaseSha])
+    } catch {
+      // Servers may refuse a fetch by sha; the next check reports the canvas as not derivable.
+    }
+  }
+  if (!(await ctx.derived.derivable(headSha, mergeBaseSha))) {
+    warnings.push(`${headSha.slice(0, 7)} is not in this clone, so the diffs are not available`)
+    return false
+  }
+  try {
+    await ctx.derived.ensure(headSha, mergeBaseSha)
+    return true
+  } catch (err) {
+    warnings.push(`the diffs for ${headSha.slice(0, 7)} could not be rebuilt: ${errorText(err)}`)
+    return false
+  }
+}
+
+function errorText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
+async function relateToHead(
+  ctx: AppContext,
+  headSha: string,
+  currentHeadSha: string
+): Promise<{ relation: CanvasRelation; commitsBehind?: number }> {
+  if (!(await ctx.git.isAncestor(headSha, currentHeadSha))) {
+    return { relation: 'unrelated' }
+  }
+  return { relation: 'ancestor', commitsBehind: await ctx.git.countCommitsBetween(headSha, currentHeadSha) }
+}
+
+/**
+ * Validates the zip, stores it under its head sha, and says how it relates to the PR head. A
+ * canvas already on disk is kept unless the incoming one was generated later.
+ */
+export async function importCanvas(ctx: AppContext, opts: ImportOptions): Promise<ImportResult> {
+  let contents: { manifest: CanvasManifest; artifact: ReviewArtifact }
+  try {
+    contents = readCanvasZip(opts.bytes)
+  } catch (err) {
+    throw err instanceof CanvasZipError ? toAppErrorFromZip(err) : err
+  }
+  const { manifest, artifact } = contents
+  const warnings: string[] = []
+  if (!sameRepo(manifest.repo, ctx.config.repo)) {
+    const from = `${manifest.repo.owner}/${manifest.repo.name}`
+    if (opts.force !== true) {
+      throw new AppError(
+        'CANVAS_REPO_MISMATCH',
+        `this canvas was exported from ${from}, and origin here is ${ctx.config.repo.owner}/${ctx.config.repo.name}`,
+        400,
+        'import it with --force to use it anyway'
+      )
+    }
+    warnings.push(`imported a canvas exported from ${from}`)
+  }
+
+  const headSha = manifest.headSha
+  const currentHeadSha = opts.currentHeadSha ?? headSha
+  const index = await ctx.canvases.readIndex()
+  const stored = index.canvases[headSha]
+  const keepStored = stored !== undefined && stored.generatedAt >= artifact.generatedAt
+  if (!keepStored) {
+    const importedAt = ctx.now().toISOString()
+    await ctx.canvases.write(headSha, { ...artifact, source: 'import', importedAt }, manifest, opts.prNumber)
+  } else if (opts.prNumber !== undefined) {
+    await ctx.canvases.attachPrNumber(headSha, opts.prNumber)
+  }
+
+  // On `exists` the stored canvas stays, so its own merge base decides what derived/ holds.
+  const storedManifest = keepStored ? await ctx.canvases.readManifest(headSha) : null
+  const mergeBaseSha = storedManifest?.mergeBaseSha ?? manifest.mergeBaseSha
+  const derivable = await ensureDerived(ctx, headSha, mergeBaseSha, warnings)
+  if (keepStored) {
+    return { status: 'exists', headSha, currentHeadSha, derivable, warnings }
+  }
+  if (headSha === currentHeadSha) {
+    return { status: 'ready', headSha, currentHeadSha, derivable, warnings }
+  }
+  const related = await relateToHead(ctx, headSha, currentHeadSha)
+  const result: ImportResult = {
+    status: 'stale',
+    headSha,
+    currentHeadSha,
+    relation: related.relation,
+    derivable,
+    warnings,
+  }
+  if (related.commitsBehind !== undefined) {
+    result.commitsBehind = related.commitsBehind
+  }
+  return result
+}

package/src/canvas/name.ts

@@ -0,0 +1,55 @@
+// The zip file name carries the repo, the PR number when there is one, and the head sha, so a
+// file attached to a pull request can be recognised before it is downloaded.
+import type { Repo } from '../contract/review-artifact.js'
+
+export interface ParsedCanvasName {
+  prNumber?: number
+  sha7: string
+}
+
+export const CANVAS_NAME_PREFIX = 'pr-review-canvas'
+
+/** Owner and repo names may hold characters a file name should not; runs of them become one dash. */
+function slugPart(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+}
+
+export function repoSlug(repo: Repo): string {
+  return `${slugPart(repo.owner)}-${slugPart(repo.name)}`
+}
+
+export interface BuildNameOptions {
+  repo: Repo
+  headSha: string
+  prNumber?: number | undefined
+}
+
+/** `pr-review-canvas-<owner>-<repo>-pr<n>-<sha7>.zip`, without `-pr<n>` before the PR exists. */
+export function buildCanvasZipName(opts: BuildNameOptions): string {
+  const pr = opts.prNumber === undefined ? '' : `-pr${opts.prNumber}`
+  return `${CANVAS_NAME_PREFIX}-${repoSlug(opts.repo)}${pr}-${opts.headSha.slice(0, 7)}.zip`
+}
+
+const TAIL_RE = /^(?:pr(\d+)-)?([0-9a-f]{7})\.zip$/
+
+/**
+ * Reads a file name as a canvas zip for `repo`. A name for another repository, or one that does
+ * not follow the grammar, returns null: discovery uses this to skip attachments that are not ours.
+ */
+export function parseCanvasZipName(filename: string, repo: Repo): ParsedCanvasName | null {
+  const prefix = `${CANVAS_NAME_PREFIX}-${repoSlug(repo)}-`
+  const lower = filename.toLowerCase()
+  if (!lower.startsWith(prefix)) {
+    return null
+  }
+  const m = TAIL_RE.exec(lower.slice(prefix.length))
+  const sha7 = m?.[2]
+  if (sha7 === undefined) {
+    return null
+  }
+  const pr = m?.[1]
+  return pr === undefined ? { sha7 } : { prNumber: Number(pr), sha7 }
+}