@vintasoftware/pr-review-canvas 0.3.0 → 0.4.0

package/src/chat/threads.ts

@@ -1,9 +1,10 @@
 // A chat thread is one acpx session plus the transcript of what was said in it. Both are named
-// after the pull request, so two repositories never share a session and a name can never point
+// after the review target, so two repositories never share a session and a name can never point
 // outside the chat directory.
 import { appendFile, mkdir, readFile } from 'node:fs/promises'
 import path from 'node:path'
 import { type ChatTurn, ChatTurnSchema } from '../contract/chat.js'
+import { keyToString, type ReviewKey } from '../contract/review-key.js'
 import type { Repo } from '../contract/review-artifact.js'
 import type { ChatThread } from '../contract/state.js'
 import { isNotFound } from '../store/atomic-json.js'
@@ -17,19 +18,19 @@ export function slug(value: string): string {
     .slice(0, 40)
 }
 
-export function threadName(repo: Repo, prNumber: number, agent: string, index: number): string {
-  return `pr-review-${slug(repo.owner)}-${slug(repo.name)}-${prNumber}-${slug(agent)}-t${index}`
+export function threadName(repo: Repo, key: ReviewKey, agent: string, index: number): string {
+  return `pr-review-${slug(repo.owner)}-${slug(repo.name)}-${keyToString(key)}-${slug(agent)}-t${index}`
 }
 
-const NAME_RE = /^pr-review-[a-z0-9-]+-(\d+)-[a-z0-9-]+-t(\d+)$/
+const NAME_RE = /^pr-review-[a-z0-9-]+-(\d+|branch|uncommitted)-[a-z0-9-]+-t(\d+)$/
 
-/** True when the name is one this tool could have made for this pull request. */
-export function isThreadNameFor(name: string, prNumber: number): boolean {
+/** True when the name is one this tool could have made for this target. */
+export function isThreadNameFor(name: string, key: ReviewKey): boolean {
   const m = NAME_RE.exec(name)
-  return m !== null && m[1] === String(prNumber)
+  return m !== null && m[1] === keyToString(key)
 }
 
-/** The next `t<k>`: one past the highest index already used on this pull request. */
+/** The next `t<k>`: one past the highest index already used on this target. */
 export function nextThreadIndex(threads: readonly ChatThread[]): number {
   let highest = 0
   for (const thread of threads) {
@@ -55,22 +56,22 @@ export function threadTitle(firstMessage: string): string {
 }
 
 export interface TranscriptStore {
-  dir(prNumber: number): string
-  file(prNumber: number, name: string): string
-  eventsFile(prNumber: number, name: string): string
-  read(prNumber: number, name: string): Promise<ChatTurn[]>
-  append(prNumber: number, name: string, turn: ChatTurn): Promise<void>
+  dir(key: ReviewKey): string
+  file(key: ReviewKey, name: string): string
+  eventsFile(key: ReviewKey, name: string): string
+  read(key: ReviewKey, name: string): Promise<ChatTurn[]>
+  append(key: ReviewKey, name: string, turn: ChatTurn): Promise<void>
   /** Appends one already-scrubbed acpx line to the raw event log. */
-  appendEvent(prNumber: number, name: string, line: string): Promise<void>
+  appendEvent(key: ReviewKey, name: string, line: string): Promise<void>
 }
 
-export function createTranscriptStore(prDir: (prNumber: number) => string): TranscriptStore {
-  const dir = (prNumber: number): string => path.join(prDir(prNumber), 'chat')
-  const named = (prNumber: number, name: string, suffix: string): string => {
-    if (!isThreadNameFor(name, prNumber)) {
-      throw new Error(`not a chat thread of pull request ${prNumber}: ${name}`)
+export function createTranscriptStore(prDir: (key: ReviewKey) => string): TranscriptStore {
+  const dir = (key: ReviewKey): string => path.join(prDir(key), 'chat')
+  const named = (key: ReviewKey, name: string, suffix: string): string => {
+    if (!isThreadNameFor(name, key)) {
+      throw new Error(`not a chat thread of ${keyToString(key)}: ${name}`)
     }
-    return path.join(dir(prNumber), `${name}${suffix}`)
+    return path.join(dir(key), `${name}${suffix}`)
   }
   const appendLine = async (file: string, line: string): Promise<void> => {
     await mkdir(path.dirname(file), { recursive: true })
@@ -78,12 +79,12 @@ export function createTranscriptStore(prDir: (prNumber: number) => string): Tran
   }
   return {
     dir,
-    file: (prNumber, name) => named(prNumber, name, '.jsonl'),
-    eventsFile: (prNumber, name) => named(prNumber, name, '.events.ndjson'),
-    async read(prNumber, name) {
+    file: (key, name) => named(key, name, '.jsonl'),
+    eventsFile: (key, name) => named(key, name, '.events.ndjson'),
+    async read(key, name) {
       let text: string
       try {
-        text = await readFile(named(prNumber, name, '.jsonl'), 'utf8')
+        text = await readFile(named(key, name, '.jsonl'), 'utf8')
       } catch (err) {
         if (isNotFound(err)) {
           return []
@@ -108,7 +109,7 @@ export function createTranscriptStore(prDir: (prNumber: number) => string): Tran
       }
       return turns
     },
-    append: (prNumber, name, turn) => appendLine(named(prNumber, name, '.jsonl'), JSON.stringify(turn)),
-    appendEvent: (prNumber, name, line) => appendLine(named(prNumber, name, '.events.ndjson'), line),
+    append: (key, name, turn) => appendLine(named(key, name, '.jsonl'), JSON.stringify(turn)),
+    appendEvent: (key, name, line) => appendLine(named(key, name, '.events.ndjson'), line),
   }
 }

package/src/cli.ts

@@ -18,7 +18,7 @@ import {
 import { ConfigError, loadRuntimeConfig, parsePort, readEnv, resolveRepoRoot } from './config.js'
 import { type ReviewArtifact, ReviewArtifactSchema } from './contract/review-artifact.js'
 import { createGit } from './git/git.js'
-import { createGitHubClient } from './github/gh.js'
+import { createHostClient } from './host/client.js'
 import { loadProjectConfig } from './project-config.js'
 import { checkSkill } from './review/doctor.js'
 import { type AppContext, createAppContext, readPackageVersion } from './server/context.js'
@@ -41,7 +41,12 @@ const USAGE = `usage: pr-review <command> [flags]
 
   serve [--port 3010] [--repo <dir>] [--data-dir <dir>] [--fixture-canvas <review.json>]
         [--agent claude|codex] [--model <id>]   (chat only; wins over .pr-review/settings.yml)
-  prepare (--pr <n> | --base <ref> --head <ref>) [--force] [--repo <dir>] [--data-dir <dir>]
+  prepare (--pr <n> | --branch | --uncommitted | --base <ref> --head <ref>) [--force]
+          [--base <ref>] [--repo <dir>] [--data-dir <dir>]
+                   (--branch reviews the current branch against the default branch, and
+                    --uncommitted reviews it with the working tree's edits and new files on top.
+                    Both are for work with no PR yet, take --base <ref> to compare against
+                    another branch, and show at /review/branch and /review/uncommitted.)
   validate <model.json|review.json> --canvas <dir> [--human] [--fix] [--repo <dir>] [--data-dir <dir>]
                    (--fix trims over-cap titles in place and reports each one)
   publish <canvasDir> --agent <id> [--model <id>] --harness claude-code|codex|other [--allow-stale]
@@ -52,7 +57,7 @@ const USAGE = `usage: pr-review <command> [flags]
   doctor [--all-checks] [--repo <dir>] [--data-dir <dir>]
 
 Every command prints one JSON line on success and { "error": { code, message, hint } } on failure.
-Exit codes: 0 ok, 1 error, 2 usage, 4 gh missing or not logged in, 5 invalid model output.
+Exit codes: 0 ok, 1 error, 2 usage, 4 gh/glab missing or not logged in, 5 invalid model output.
 `
 
 const io: CliIo = {
@@ -125,15 +130,15 @@ async function serve(argv: string[]): Promise<number> {
   return EXIT.ok
 }
 
-/** doctor builds no AppContext: it has to answer even when the repo or `gh` is the problem. */
+/** doctor builds no AppContext: it has to answer even when the repo or host CLI is the problem. */
 async function doctorCommand(argv: string[]): Promise<number> {
   const { repo, dataDir, rest } = splitCommonFlags(argv)
   const cwd = process.cwd()
-  const git = createGit(repo === undefined ? cwd : path.resolve(cwd, repo))
   return runDoctor(
     {
-      git,
-      gh: createGitHubClient(),
+      git: createGit(repo === undefined ? cwd : path.resolve(cwd, repo)),
+      env: process.env,
+      client: host => createHostClient(host.cli),
       version: readPackageVersion(),
       acpxVersion: () => createAgentRunner().acpxVersion(),
       dataDirOverride: dataDir ?? readEnv(process.env, 'PR_REVIEW_DATA_DIR'),

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 {
@@ -94,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
 }
 
 /**
@@ -145,17 +146,39 @@ 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> {
@@ -165,12 +188,16 @@ export async function runPrepare(ctx: AppContext, argv: string[], io: CliIo): Pr
       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
 }
@@ -308,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
 }
@@ -368,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 }
 }
 
@@ -387,7 +416,7 @@ export async function runExport(ctx: AppContext, argv: string[], io: CliIo): Pro
     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
 }
 
@@ -445,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. */
@@ -61,36 +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. */
@@ -139,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 {
@@ -148,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

@@ -96,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(),

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
   }