@vintasoftware/pr-review-canvas 0.2.0 → 0.4.0

package/src/commands.ts

@@ -7,10 +7,11 @@ import { exportCanvas } from './canvas/export.js'
 import { importCanvas } from './canvas/import.js'
 import { CANVAS_ZIP_MAX_BYTES } from './canvas/zip.js'
 import type { ErrorCode } from './contract/api.js'
-import type { GenerationContext, PrepareTarget } from './contract/generation-context.js'
+import type { GenerationContext, PrepareTargetInput } from './contract/generation-context.js'
+import type { LocalKey } from './contract/review-key.js'
 import { HARNESSES, type ReviewArtifact, ReviewArtifactSchema } from './contract/review-artifact.js'
 import { formatValidationError, type ValidationReport } from './contract/validation.js'
-import { fetchPrMeta, fetchPrRefs } from './github/pr.js'
+import { fetchPrRefs } from './git/pr-refs.js'
 import { type DoctorDeps, runDoctorChecks } from './review/doctor.js'
 import {
   CLAUDE_SKILLS_DIR,
@@ -32,7 +33,7 @@ import {
 import { applyTitleTrims, type TitleTrim } from './review/trim-caps.js'
 import { validateModelOutput } from './review/validate.js'
 import type { AppContext } from './server/context.js'
-import { AppError, toAppError } from './server/errors.js'
+import { AppError, CLI_SETUP_CODES, toAppError } from './server/errors.js'
 import { readText, writeTextAtomic } from './store/atomic-json.js'
 
 export interface CliIo {
@@ -40,7 +41,7 @@ export interface CliIo {
   stderr(line: string): void
 }
 
-/** Exit codes: 0 ok, 1 error, 2 usage, 4 gh auth or missing, 5 invalid model output. */
+/** Exit codes: 0 ok, 1 error, 2 usage, 4 gh/glab auth or missing, 5 invalid model output. */
 export const EXIT = { ok: 0, error: 1, usage: 2, gh: 4, invalid: 5 } as const
 
 export class UsageError extends Error {
@@ -63,7 +64,12 @@ export function printErrorEnvelope(io: CliIo, code: ErrorCode, message: string,
 }
 
 function isParseArgsError(err: unknown): err is Error {
-  return err instanceof Error && 'code' in err && typeof err.code === 'string' && err.code.startsWith('ERR_PARSE_ARGS')
+  return (
+    err instanceof Error &&
+    'code' in err &&
+    typeof err.code === 'string' &&
+    err.code.startsWith('ERR_PARSE_ARGS')
+  )
 }
 
 /** Prints the envelope for any failure and picks the exit code. */
@@ -89,7 +95,7 @@ export function reportFailure(io: CliIo, err: unknown): number {
   }
   const appErr = toAppError(err)
   printErrorEnvelope(io, appErr.code, appErr.message, appErr.hint)
-  return appErr.code === 'GH_UNAUTHENTICATED' || appErr.code === 'GH_MISSING' ? EXIT.gh : EXIT.error
+  return CLI_SETUP_CODES.has(appErr.code) ? EXIT.gh : EXIT.error
 }
 
 /**
@@ -140,27 +146,58 @@ function parsePrNumber(raw: string): number {
   return n
 }
 
-export function parsePrepareTarget(values: { pr?: string; base?: string; head?: string }): PrepareTarget {
+export interface PrepareFlags {
+  pr?: string | undefined
+  base?: string | undefined
+  head?: string | undefined
+  branch?: boolean | undefined
+  uncommitted?: boolean | undefined
+}
+
+const LOCAL_FLAGS = 'pass one of --pr <n>, --branch, --uncommitted, or --base <ref> --head <ref>'
+
+/** The target the flags name. `prepare` resolves a local review's base against the clone. */
+export function parsePrepareTarget(values: PrepareFlags): PrepareTargetInput {
+  const local: LocalKey | undefined =
+    values.branch === true ? 'branch' : values.uncommitted === true ? 'uncommitted' : undefined
+  if (values.branch === true && values.uncommitted === true) {
+    throw new UsageError('--branch and --uncommitted are two reviews; ask for one of them')
+  }
   if (values.pr !== undefined) {
-    if (values.base !== undefined || values.head !== undefined) {
-      throw new UsageError('pass either --pr <n> or --base <ref> --head <ref>, not both')
+    if (values.base !== undefined || values.head !== undefined || local !== undefined) {
+      throw new UsageError(LOCAL_FLAGS)
     }
     return { kind: 'pr', number: parsePrNumber(values.pr) }
   }
+  if (local !== undefined) {
+    if (values.head !== undefined) {
+      throw new UsageError(`--${local} reviews this clone, so it takes no --head`)
+    }
+    return { kind: 'local', source: local, base: values.base }
+  }
   if (values.base !== undefined && values.head !== undefined) {
     return { kind: 'refs', base: values.base, head: values.head }
   }
-  throw new UsageError('prepare needs --pr <n> or --base <ref> --head <ref>')
+  throw new UsageError(`prepare needs a target: ${LOCAL_FLAGS}`)
 }
 
 export async function runPrepare(ctx: AppContext, argv: string[], io: CliIo): Promise<number> {
   const { values } = parseArgs({
     args: argv,
-    options: { pr: { type: 'string' }, base: { type: 'string' }, head: { type: 'string' }, force: { type: 'boolean' } },
+    options: {
+      pr: { type: 'string' },
+      base: { type: 'string' },
+      head: { type: 'string' },
+      branch: { type: 'boolean' },
+      uncommitted: { type: 'boolean' },
+      force: { type: 'boolean' },
+    },
     strict: true,
   })
-  const target = parsePrepareTarget(values)
-  const result = await prepare(ctx, target, { force: values.force === true, log: phase => io.stderr(phase) })
+  const result = await prepare(ctx, parsePrepareTarget(values), {
+    force: values.force === true,
+    log: phase => io.stderr(phase),
+  })
   printJson(io, result)
   return EXIT.ok
 }
@@ -194,7 +231,9 @@ export async function runValidate(ctx: AppContext, argv: string[], io: CliIo): P
   })
   const file = positionals[0]
   if (file === undefined || positionals.length > 1) {
-    throw new UsageError('validate takes one file: pr-review validate <model.json|review.json> --canvas <dir>')
+    throw new UsageError(
+      'validate takes one file: pr-review validate <model.json|review.json> --canvas <dir>'
+    )
   }
   if (values.canvas === undefined) {
     throw new UsageError('validate needs --canvas <dir> (the directory prepare printed)')
@@ -202,7 +241,11 @@ export async function runValidate(ctx: AppContext, argv: string[], io: CliIo): P
   const context = await readContext(path.resolve(values.canvas))
   const text = await readText(path.resolve(file))
   if (text === null) {
-    throw new PublishError('NOT_FOUND', `${file} does not exist`, 'pass the model.json or review.json to check')
+    throw new PublishError(
+      'NOT_FOUND',
+      `${file} does not exist`,
+      'pass the model.json or review.json to check'
+    )
   }
   const fixed = values.fix === true ? await fixTitles(path.resolve(file), text, context) : { text, trims: [] }
   const report = await validateFile(ctx, parseModelText(fixed.text, path.basename(file)), context)
@@ -214,7 +257,9 @@ export async function runValidate(ctx: AppContext, argv: string[], io: CliIo): P
     if (trim.outcome === 'fixed') {
       io.stdout(`fixed ${trim.where}: "${trim.from}" -> "${trim.to}"`)
     } else {
-      io.stdout(`unfixable ${trim.where}: ${trim.length} visible chars, cap ${trim.cap}, ${trim.reason}; rewrite by hand`)
+      io.stdout(
+        `unfixable ${trim.where}: ${trim.length} visible chars, cap ${trim.cap}, ${trim.reason}; rewrite by hand`
+      )
     }
   }
   if (report.ok) {
@@ -277,7 +322,9 @@ export async function runPublish(ctx: AppContext, argv: string[], io: CliIo): Pr
   })
   const canvasDir = positionals[0]
   if (canvasDir === undefined || positionals.length > 1) {
-    throw new UsageError('publish takes one directory: pr-review publish <canvasDir> --agent <id> --harness <id>')
+    throw new UsageError(
+      'publish takes one directory: pr-review publish <canvasDir> --agent <id> --harness <id>'
+    )
   }
   if (values.agent === undefined || values.agent === '') {
     throw new UsageError('publish needs --agent <id>')
@@ -288,6 +335,8 @@ export async function runPublish(ctx: AppContext, argv: string[], io: CliIo): Pr
     harness: parseHarness(values.harness),
     allowStale: values['allow-stale'] === true,
   })
+  if (result.sharing.status === 'failed')
+    io.stderr(`${result.sharing.warning} ZIP: ${result.sharing.zipPath}`)
   printJson(io, result)
   return EXIT.ok
 }
@@ -312,7 +361,11 @@ export interface InstallSkillEnv {
 export async function runInstallSkill(env: InstallSkillEnv, argv: string[], io: CliIo): Promise<number> {
   const { values } = parseArgs({
     args: argv,
-    options: { 'claude-dir': { type: 'string' }, 'codex-dir': { type: 'string' }, force: { type: 'boolean' } },
+    options: {
+      'claude-dir': { type: 'string' },
+      'codex-dir': { type: 'string' },
+      force: { type: 'boolean' },
+    },
     strict: true,
   })
   const resolve = (flag: string | undefined, fallback: string): string =>
@@ -344,8 +397,8 @@ async function resolveHead(
   if (prNumber === undefined) {
     throw new UsageError('export needs --pr <n> or --head <ref|sha>')
   }
-  const meta = await fetchPrMeta(ctx.gh, ctx.config.repo, prNumber)
-  const { headSha } = await fetchPrRefs(ctx.git, meta)
+  const meta = await ctx.config.host.fetchPrMeta(ctx.gh, ctx.config.repo, prNumber)
+  const { headSha } = await fetchPrRefs(ctx.git, ctx.config.host, meta)
   return { headSha, prNumber }
 }
 
@@ -357,9 +410,13 @@ export async function runExport(ctx: AppContext, argv: string[], io: CliIo): Pro
     strict: true,
   })
   const target = await resolveHead(ctx, values)
-  const result = await exportCanvas(ctx, { headSha: target.headSha, prNumber: target.prNumber, out: values.out })
+  const result = await exportCanvas(ctx, {
+    headSha: target.headSha,
+    prNumber: target.prNumber,
+    out: values.out,
+  })
   printJson(io, result)
-  io.stderr(`drag ${result.path} into the pull request description or a comment`)
+  io.stderr(`drag ${result.path} into the ${ctx.config.host.noun} description or a comment`)
   return EXIT.ok
 }
 
@@ -375,7 +432,11 @@ async function readZipFile(zipPath: string, shown: string): Promise<Uint8Array>
   } catch {
     throw new PublishError('NOT_FOUND', `${shown} does not exist`, 'pass the canvas zip to import')
   }
-  const tooLarge = new AppError('CANVAS_TOO_LARGE', `${shown} is larger than ${CANVAS_ZIP_MAX_BYTES} bytes`, 413)
+  const tooLarge = new AppError(
+    'CANVAS_TOO_LARGE',
+    `${shown} is larger than ${CANVAS_ZIP_MAX_BYTES} bytes`,
+    413
+  )
   try {
     // One byte past the cap is read, so a file of exactly the cap still fits and anything longer
     // is refused without the rest of it ever being in memory.
@@ -413,9 +474,9 @@ export async function runImport(ctx: AppContext, argv: string[], io: CliIo): Pro
   const options: Parameters<typeof importCanvas>[1] = { bytes, force: values.force === true }
   if (values.pr !== undefined) {
     const prNumber = parsePrNumber(values.pr)
-    const meta = await fetchPrMeta(ctx.gh, ctx.config.repo, prNumber)
+    const meta = await ctx.config.host.fetchPrMeta(ctx.gh, ctx.config.repo, prNumber)
     options.prNumber = prNumber
-    options.currentHeadSha = (await fetchPrRefs(ctx.git, meta)).headSha
+    options.currentHead = await fetchPrRefs(ctx.git, ctx.config.host, meta)
   }
   printJson(io, await importCanvas(ctx, options))
   return EXIT.ok

package/src/config.ts

@@ -2,6 +2,8 @@ import path from 'node:path'
 import type { Repo } from './contract/review-artifact.js'
 import { isChatAgent, type SettingsOverrides } from './contract/settings.js'
 import { type Git, GitError } from './git/git.js'
+import type { Host } from './host/host.js'
+import { type OriginRemote, parseOriginRemote } from './host/remote.js'
 import { resolveDataDir } from './store/data-dir.js'
 
 export const DEFAULT_PORT = 3010
@@ -22,6 +24,8 @@ export interface RuntimeConfig {
   commonDir: string
   dataDir: string
   repo: Repo
+  /** The forge origin points at, which owns every request or answer that differs between them. */
+  host: Host
   /** Dev only: every PR reports `ready` with this artifact re-keyed to the live head. */
   fixtureCanvasPath: string | null
   /** Chat agent and model the flags force for this run, if any. */
@@ -47,7 +51,11 @@ export async function resolveRepoRoot(git: Git): Promise<string> {
     return await git.topLevel()
   } catch (err) {
     if (err instanceof GitError) {
-      throw new ConfigError('NOT_A_REPO', 'not inside a git repository', 'run from a clone or pass --repo <dir>')
+      throw new ConfigError(
+        'NOT_A_REPO',
+        'not inside a git repository',
+        'run from a clone or pass --repo <dir>'
+      )
     }
     throw err
   }
@@ -57,32 +65,19 @@ export async function resolveCommonDir(git: Git): Promise<string> {
   return git.commonDir()
 }
 
-/** Parses the two URL forms GitHub gives out: ssh (`git@github.com:o/r.git`) and https. */
-export function parseGithubRemote(url: string): Repo | null {
-  const m =
-    /^(?:git@github\.com:|ssh:\/\/git@github\.com\/|https?:\/\/(?:[^@/]+@)?github\.com\/)([^/]+)\/([^/]+?)(?:\.git)?\/?$/.exec(
-      url.trim()
-    )
-  if (!m || m[1] === undefined || m[2] === undefined) {
-    return null
-  }
-  return { owner: m[1], name: m[2] }
-}
+export const ORIGIN_HINT =
+  'add a github.com or GitLab origin, or set PR_REVIEW_HOST=gitlab for self-hosted GitLab'
 
-export async function resolveGithubRepo(git: Git): Promise<Repo> {
+export async function resolveOrigin(git: Git, env: NodeJS.ProcessEnv = {}): Promise<OriginRemote> {
   const url = await git.remoteUrl('origin')
   if (url === null) {
-    throw new ConfigError('NO_ORIGIN', 'the repository has no "origin" remote', 'add one that points at GitHub')
+    throw new ConfigError('NO_ORIGIN', 'the repository has no "origin" remote', ORIGIN_HINT)
   }
-  const repo = parseGithubRemote(url)
-  if (repo === null) {
-    throw new ConfigError(
-      'NO_ORIGIN',
-      `origin is not a GitHub URL: ${url}`,
-      'only github.com repositories are supported'
-    )
+  const parsed = parseOriginRemote(url, env)
+  if (parsed === null) {
+    throw new ConfigError('NO_ORIGIN', `origin is not a GitHub or GitLab URL: ${url}`, ORIGIN_HINT)
   }
-  return repo
+  return parsed
 }
 
 /** `--agent` names one of the agents the chat knows; anything else is a usage error. */
@@ -90,7 +85,11 @@ export function parseChatOverrides(flags: ServeFlags): SettingsOverrides {
   const overrides: SettingsOverrides = {}
   if (flags.agent !== undefined) {
     if (!isChatAgent(flags.agent)) {
-      throw new ConfigError('BAD_REQUEST', `unknown chat agent: ${flags.agent}`, 'use --agent claude or --agent codex')
+      throw new ConfigError(
+        'BAD_REQUEST',
+        `unknown chat agent: ${flags.agent}`,
+        'use --agent claude or --agent codex'
+      )
     }
     overrides.agent = flags.agent
   }
@@ -127,7 +126,7 @@ export async function loadRuntimeConfig(
 ): Promise<RuntimeConfig> {
   const repoRoot = await resolveRepoRoot(git)
   const commonDir = await resolveCommonDir(git)
-  const repo = await resolveGithubRepo(git)
+  const { repo, host } = await resolveOrigin(git, env)
   const port = flags.port ?? parsePort(readEnv(env, 'PR_REVIEW_PORT'), DEFAULT_PORT)
   const dataDir = resolveDataDir({ override: flags.dataDir ?? readEnv(env, 'PR_REVIEW_DATA_DIR'), commonDir })
   return {
@@ -136,6 +135,7 @@ export async function loadRuntimeConfig(
     commonDir,
     dataDir,
     repo,
+    host,
     fixtureCanvasPath: flags.fixtureCanvas === undefined ? null : path.resolve(cwd, flags.fixtureCanvas),
     chatOverrides: parseChatOverrides(flags),
   }

package/src/contract/api.ts

@@ -3,6 +3,7 @@ import type { CanvasManifest } from './canvas-manifest.js'
 import type { CommentsPayload, IssueComment, ReviewComment } from './comments.js'
 import type { SharedCanvasInfoSchema } from './discovery.js'
 import type { FileEntry, Pr, ReviewArtifact } from './review-artifact.js'
+import type { LocalKey, ReviewKey } from './review-key.js'
 import type { PrState } from './state.js'
 
 export const ERROR_CODES = [
@@ -16,10 +17,14 @@ export const ERROR_CODES = [
   'GH_MISSING',
   'GH_UNAUTHENTICATED',
   'GITHUB_API_ERROR',
+  'GLAB_MISSING',
+  'GLAB_UNAUTHENTICATED',
+  'GITLAB_API_ERROR',
   'PR_NOT_FOUND',
   'CANVAS_NOT_FOUND',
   'CANVAS_INVALID',
   'CANVAS_REPO_MISMATCH',
+  'CANVAS_PR_MISMATCH',
   'CANVAS_TOO_LARGE',
   'CANVAS_STALE',
   'MODEL_INVALID',
@@ -65,6 +70,17 @@ export interface StaleInfo {
   commitsBehind?: number
 }
 
+/**
+ * A ready canvas generated for an earlier commit of the pull request whose diff is identical to
+ * the head's, so the page keeps it and says so.
+ */
+export interface CarriedOverInfo {
+  canvasHeadSha: string
+  currentHeadSha: string
+  /** How many commits the head is ahead of the canvas's commit; absent when the head does not contain it. */
+  commitsBehind?: number
+}
+
 /** The answer of `POST /import`, of `pr-review import`, and of an imported shared canvas. */
 export interface ImportResult {
   status: 'ready' | 'stale' | 'exists'
@@ -88,6 +104,15 @@ export interface SharedCanvasFetchResponse {
 /** A canvas zip found on the pull request. Shaped by the schema the discovery cache stores. */
 export type SharedCanvasInfo = z.infer<typeof SharedCanvasInfoSchema>
 
+/** The forge the server talks to, as the page and the health endpoint learn it. */
+export interface PublicHost {
+  kind: 'github' | 'gitlab'
+  /** `GitHub` or `GitLab`, for the words on the page. */
+  label: string
+  /** `https://github.com` or the GitLab instance, for links to profiles. */
+  webBase: string
+}
+
 export interface PrBundle {
   status: BundleStatus
   pr: Pr
@@ -96,8 +121,12 @@ export interface PrBundle {
   artifact?: ReviewArtifact
   canvas?: CanvasInfo
   stale?: StaleInfo
+  /** Set on a ready bundle whose canvas was generated for another commit with an identical diff. */
+  carriedOver?: CarriedOverInfo
   sharedCanvas?: SharedCanvasInfo
   skillCommand: string
+  /** Set on a local review: work that has no pull request, so the forge side of the page is off. */
+  local?: LocalKey
   comments: CommentsPayload
   state: PrState
   capabilities: Capabilities
@@ -111,7 +140,8 @@ export interface PrBundle {
 
 /** Every answer of a state route, so the page can replace its copy of the state in one step. */
 export interface StateResponse {
-  prNumber: number
+  /** The target the state belongs to: a pull request number, or `local`. */
+  prNumber: ReviewKey
   state: PrState
 }
 
@@ -172,6 +202,7 @@ export interface HealthResponse {
     agentAuth?: HealthCheck
   }
   repo: { owner: string; name: string } | null
+  host: PublicHost
   dataDir: string
   chat: ChatStatus
 }

package/src/contract/canvas-manifest.ts

@@ -23,6 +23,8 @@ export const CanvasIndexSchema = z.object({
       generatedAt: z.string(),
       source: z.enum(['local', 'import']),
       importedAt: z.string().optional(),
+      /** A snapshot of uncommitted work: it sits on no branch, so no pull request can claim it. */
+      worktree: z.boolean().optional(),
     })
   ),
 })

package/src/contract/comments.ts

@@ -79,7 +79,9 @@ export const PostCommentInputSchema = z.discriminatedUnion('kind', [
 export type PostCommentInput = z.infer<typeof PostCommentInputSchema>
 
 /** The posted comment: a review comment for inline and reply, an issue comment for PR-level. */
-export type PostCommentResult = { kind: 'review'; comment: ReviewComment } | { kind: 'issue'; comment: IssueComment }
+export type PostCommentResult =
+  | { kind: 'review'; comment: ReviewComment }
+  | { kind: 'issue'; comment: IssueComment }
 
 // The proposed-comment block a chat answer can carry. The parser lives in
 // static/js/proposed-comment.js so the browser loads the same code without a bundler.
@@ -94,3 +96,8 @@ export {
 export function emptyComments(headSha: string, fetchedAt: string): CommentsPayload {
   return { fetchedAt, headSha, reviewComments: [], issueComments: [] }
 }
+
+export interface FetchCommentsResult {
+  payload: CommentsPayload
+  warnings: string[]
+}

package/src/contract/discovery.ts

@@ -3,9 +3,12 @@ import { z } from 'zod'
 export const SharedCanvasInfoSchema = z.object({
   url: z.string(),
   name: z.string(),
-  matchesHead: z.boolean(),
+  /** The attachment's file name carries the head's sha; it says nothing about whether it is current. */
+  namesHead: z.boolean(),
   downloadable: z.boolean(),
-  reason: z.enum(['auth-required', 'not-zip', 'too-large', 'network', 'name-mismatch']).optional(),
+  reason: z
+    .enum(['auth-required', 'not-zip', 'too-large', 'network', 'name-mismatch', 'pr-mismatch'])
+    .optional(),
 })
 
 /**

package/src/contract/generation-context.ts

@@ -1,15 +1,38 @@
 import { z } from 'zod'
 import { DefaultLayerSchema, GenerationModeSchema, HighRiskRuleSchema } from '../project-config.js'
 import { DEFAULT_TEST_PATTERNS } from '../review/test-paths.js'
+import { type LocalKey, LocalKeySchema } from './review-key.js'
 import { FileEntrySchema, LIMITS, PrSchema, RepoSchema, type TextCaps } from './review-artifact.js'
 
-/** What `prepare` was asked to describe: a pull request, or two refs before a PR exists. */
+/**
+ * What `prepare` was asked to describe: a pull request, two refs, or one of the two reviews of
+ * work in this clone that has no pull request yet. A `local` target names only its base, because
+ * its head is whatever the branch or the working tree holds when the command runs.
+ */
+export const LocalPrepareTargetSchema = z.object({
+  kind: z.literal('local'),
+  base: z.string().min(1),
+  /** Which local review this is, which is also the key it is filed and served under. */
+  source: LocalKeySchema,
+})
+export type LocalPrepareTarget = z.infer<typeof LocalPrepareTargetSchema>
+
 export const PrepareTargetSchema = z.discriminatedUnion('kind', [
   z.object({ kind: z.literal('pr'), number: z.number().int().positive() }),
   z.object({ kind: z.literal('refs'), base: z.string().min(1), head: z.string().min(1) }),
+  LocalPrepareTargetSchema,
 ])
 export type PrepareTarget = z.infer<typeof PrepareTargetSchema>
 
+/**
+ * What the CLI parsed, before git has been asked anything. A local review's base may still be
+ * open here: only the clone knows which branch `origin/HEAD` points at. `prepare` resolves it and
+ * records the answer, so `publish` reads a base that cannot drift.
+ */
+export type PrepareTargetInput =
+  | Extract<PrepareTarget, { kind: 'pr' } | { kind: 'refs' }>
+  | { kind: 'local'; base?: string | undefined; source: LocalKey }
+
 const capsShape = {
   summary: z.number().int().positive(),
   layerTitle: z.number().int().positive(),
@@ -57,7 +80,9 @@ export const GenerationContextSchema = z.object({
   }),
   /** The globs that make a file a test here. Defaulted, so a context written before this
    * field existed still reads. */
-  tests: z.object({ patterns: z.array(z.string().min(1)) }).default(() => ({ patterns: [...DEFAULT_TEST_PATTERNS] })),
+  tests: z
+    .object({ patterns: z.array(z.string().min(1)) })
+    .default(() => ({ patterns: [...DEFAULT_TEST_PATTERNS] })),
   /** At most `generation.smallPrHunks` hunks: one layer unless concerns differ, fewer annotations. */
   smallPr: z.boolean(),
   /** More than 400 files or 50 000 changed lines: the prompt inlines nothing and tightens the caps. */

package/src/contract/review-artifact.ts

@@ -48,7 +48,9 @@ function mapCaps(fn: (key: keyof TextCaps) => number): TextCaps {
 }
 
 /** The project config may raise or lower a cap; the result is what the validator and the prompt use. */
-export function effectiveCaps(overrides: { [K in keyof TextCaps]?: number | undefined } | undefined): TextCaps {
+export function effectiveCaps(
+  overrides: { [K in keyof TextCaps]?: number | undefined } | undefined
+): TextCaps {
   return mapCaps(key => overrides?.[key] ?? TEXT_CAPS[key])
 }
 
@@ -162,13 +164,17 @@ function text(caps: Caps, key: keyof TextCaps): z.ZodString {
 
 function textOrEmpty(caps: Caps, key: keyof TextCaps): z.ZodString {
   const visibleCap = caps[key] / HARD_CAP_FACTOR
-  const diagrams = key === 'summary' || key === 'rationale'
-    ? ' Mermaid fences count toward the separate diagram cap, not this prose cap.'
-    : ''
-  return z.string().max(caps[key]).meta({
-    description: `At most ${visibleCap} visible characters. Link targets, backticks, and code-fence lines do not count. maxLength is only the raw Markdown ceiling.${diagrams}`,
-    'x-visibleMaxLength': visibleCap,
-  })
+  const diagrams =
+    key === 'summary' || key === 'rationale'
+      ? ' Mermaid fences count toward the separate diagram cap, not this prose cap.'
+      : ''
+  return z
+    .string()
+    .max(caps[key])
+    .meta({
+      description: `At most ${visibleCap} visible characters. Link targets, backticks, and code-fence lines do not count. maxLength is only the raw Markdown ceiling.${diagrams}`,
+      'x-visibleMaxLength': visibleCap,
+    })
 }
 
 export function testEntrySchema(caps: Caps) {

package/src/contract/review-key.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod'
+
+/**
+ * The two reviews of work that has no pull request yet. They are separate targets, so reviewing a
+ * branch does not disturb the review of what is not committed, and each keeps its own progress
+ * marks and chat threads.
+ */
+export const LOCAL_KEYS = ['branch', 'uncommitted'] as const
+
+/**
+ * Which local review: `branch` is the current branch against the base it will be opened against,
+ * uncommitted edits left out; `uncommitted` is that branch with the working tree on top.
+ */
+export type LocalKey = (typeof LOCAL_KEYS)[number]
+
+/**
+ * What a canvas, its review state, and its chat threads are filed under: a pull request or merge
+ * request number, or one of the local reviews. It is also what the URLs carry, so `/review/12`
+ * and `/review/uncommitted` are the same page over different targets.
+ */
+export type ReviewKey = number | LocalKey
+
+export const LocalKeySchema = z.enum(LOCAL_KEYS)
+export const ReviewKeySchema = z.union([LocalKeySchema, z.number().int().positive()])
+
+export function isLocalKey(key: ReviewKey): key is LocalKey {
+  return LOCAL_KEYS.some(local => local === key)
+}
+
+/** The key as it appears in a URL segment and as a directory name. */
+export function keyToString(key: ReviewKey): string {
+  return String(key)
+}
+
+/** What the page calls the target, for a title or a heading. */
+export function keyLabel(key: ReviewKey): string {
+  if (key === 'branch') {
+    return 'Branch review'
+  }
+  return key === 'uncommitted' ? 'Uncommitted work' : `#${String(key)}`
+}
+
+/** The key a URL segment names, or null when it names none of them. */
+export function parseReviewKey(raw: string): ReviewKey | null {
+  const local = LocalKeySchema.safeParse(raw)
+  if (local.success) {
+    return local.data
+  }
+  const n = Number(raw)
+  return Number.isInteger(n) && n > 0 ? n : null
+}

package/src/contract/reviews.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod'
+
+export const REVIEW_EVENTS = ['APPROVE', 'REQUEST_CHANGES'] as const
+export const ReviewEventSchema = z.enum(REVIEW_EVENTS)
+export type ReviewEvent = (typeof REVIEW_EVENTS)[number]
+
+export const PostReviewInputSchema = z.object({
+  event: ReviewEventSchema,
+  /** The dialog sends the body the user read, edited or not. */
+  body: z.string().min(1).max(65536).optional(),
+  /** The commit the dialog named. The server refuses the review when the head moved on. */
+  headSha: z
+    .string()
+    .regex(/^[0-9a-f]{40}$/)
+    .optional(),
+})
+export type PostReviewInput = z.infer<typeof PostReviewInputSchema>

package/src/contract/settings.ts

@@ -107,6 +107,8 @@ export interface SettingsResponse {
     maxRepairRounds: number
     inlineDiffMaxLines: number
     smallPrHunks: number
+    /** Whether a canvas still stands for a later head with an identical diff. */
+    keepForIdenticalDiff: boolean
     layers: number
     highRisk: number
   }