@vintasoftware/pr-review-canvas 0.2.0 → 0.4.0

package/skills/pr-review-canvas/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pr-review-canvas
 model: sonnet
-description: Generate a review canvas for a GitHub pull request (or two refs) with the pr-review tool. Runs `pr-review prepare`, writes the layered model.json the prompt asks for, and runs `pr-review publish` until the validator passes. Use when the user runs `/pr-review-canvas <pr-number>`, `/pr-review-canvas --base <ref> --head <ref>`, or asks for a review canvas for a PR.
+description: Generate a review canvas for a GitHub pull request or GitLab merge request, for the work in this clone before a pull request exists, or for two refs, with the pr-review tool. Runs `pr-review prepare`, writes the layered model.json the prompt asks for, and runs `pr-review publish` to validate and automatically share it as a compressed PR/MR comment. Use when the user runs `/pr-review-canvas <pr-number>`, `/pr-review-canvas branch`, `/pr-review-canvas uncommitted`, `/pr-review-canvas --base <ref> --head <ref>`, or asks for a review canvas for a PR or MR, for their branch, or for what they have not committed.
 ---
 
 # pr-review-canvas
@@ -11,42 +11,73 @@ points, and hand it to the `pr-review` CLI. The CLI does the deterministic work
 validation, storage); you do the reading and the writing of `model.json`. Nothing here checks out
 a branch or writes outside the canvas directory.
 
-Arguments: `<pr-number> [--force]` or `--base <ref> --head <ref> [--force]`. `--force` regenerates
-a canvas that already exists for the head commit: prepare removes the old `model.json` and any
-other leftovers from the canvas directory, keeping `derived/`, `publish.log` (the attempts history),
-and the published `review.json` + `manifest.json` (the page keeps showing the old canvas until your
-publish replaces it), so you start a fresh `model.json`. Run every `pr-review` command from the
-repository root.
+Arguments: `<pr-number> [--force]`, `branch [--base <ref>] [--force]`,
+`uncommitted [--base <ref>] [--force]`, or `--base <ref> --head <ref> [--force]`. `--force`
+regenerates a canvas that already exists for the head commit: prepare removes the old `model.json` and any other leftovers from the canvas
+directory, keeping `derived/`, `publish.log` (the attempts history), and the published
+`review.json` + `manifest.json` (the page keeps showing the old canvas until your publish replaces
+it), so you start a fresh `model.json`. Run every `pr-review` command from the repository root.
 
 ## Flow
 
 ### Model choice
 
-Claude Code defaults this skill to Sonnet. If the prepared diff changes authentication, access
-policy, or protected health information (PHI) handling, use an Opus agent for the generation and
-validation steps when available. Pass it the prepared prompt and context paths; it writes the
-same model file. Honor an explicit user model choice. Other hosts keep their selected model.
+Use a mid-tier model, such as Sonnet, by default. If the prepared diff changes authentication,
+access policy, or protected health information (PHI) handling, use a more capable model, such as
+Opus, for the generation and validation steps when available. When delegating to another agent,
+pass it the prepared prompt and context paths; it writes the same model file. Honor an explicit
+user model choice. If the host cannot select models, keep its selected model.
 Record the model that actually generated the canvas when publishing.
 
 ### 1. Prepare
 
 ```bash
 pr-review prepare --pr <n> [--force]
-# or, before a PR exists:
+# or, before a pull request exists, one of the two reviews of this clone:
+pr-review prepare --branch [--base <ref>] [--force]
+pr-review prepare --uncommitted [--base <ref>] [--force]
+# or, for any two refs:
 pr-review prepare --base <ref> --head <ref> [--force]
 ```
 
+The skill word maps to the flag: `/pr-review-canvas branch` runs `prepare --branch`, and
+`/pr-review-canvas uncommitted` runs `prepare --uncommitted`.
+
+Both compare against the default branch, which prepare reads from `origin/HEAD` unless `--base`
+names another one. They differ in what the head holds:
+
+- `--branch` is the tip of the current branch. Whatever is in the working tree is left out.
+- `--uncommitted` is the working tree itself: prepare snapshots the edits and the untracked files
+  into a commit of its own, without touching anything the user has staged. With a clean tree it is
+  the branch tip, and the canvas is the same one `--branch` would build.
+
+They are separate reviews with separate pages, progress and chat threads, so preparing one leaves
+the other alone. Pick the one the user asked for; when they only say "review my work", ask which,
+unless the words already decide it ("before I commit" is `uncommitted`, "before I open the PR" with
+everything committed is `branch`).
+
+The JSON carries an extra `local` object with the review's name, the base that was resolved, the
+branch the head is on, and whether uncommitted work is in it. Tell the user all four: a review of
+the wrong base, or of a tree that has moved, is worth catching early.
+
 Progress goes to stderr. The last stdout line is JSON:
 
 ```json
-{ "canvasDir": "...", "headSha": "...", "mergeBaseSha": "...", "promptPath": "...", "contextPath": "...", "status": "prepared" }
+{
+    "canvasDir": "...",
+    "headSha": "...",
+    "mergeBaseSha": "...",
+    "promptPath": "...",
+    "contextPath": "...",
+    "status": "prepared"
+}
 ```
 
 - `status: "exists"` means a canvas already exists for this head. Stop and tell the user:
   "canvas already exists for <headSha>; run with --force to regenerate".
 - A line of the form `{ "error": { "code", "message", "hint" } }` means prepare failed. Report the
   code, message, and hint verbatim and stop. `pr-review doctor` names which of git, origin,
-  `gh`, the data dir, and the skill install is missing.
+  `gh` or `glab`, the data dir, and the skill install is missing.
 
 ### 2. Read the task
 
@@ -96,7 +127,15 @@ pr-review publish <canvasDir> --agent <your agent id> --model <model id if you k
   anywhere else.
 
 On success the last line is `{ "status": "published", "headSha", "reviewJsonPath", "attempts",
-"reviewUrl" }` (`reviewUrl` is absent for a `--base/--head` run).
+"reviewUrl", "sharing" }` (`reviewUrl` is absent only for a `--base/--head` run; a local run
+points at `/review/branch` or `/review/uncommitted`).
+For PR/MR runs, publish automatically creates or updates your canvas comment using the host CLI login.
+Always inspect `sharing.status`: local validation success does not mean remote sharing succeeded.
+
+For a local run there is nothing to share: `sharing.status` is `"local"`. Report `reviewUrl` and
+tell the user to start `pr-review serve` to read the canvas. If publish prints `CANVAS_STALE`, the
+branch or the working tree changed while you worked; offer to prepare again rather than passing
+`--allow-stale`, because the canvas would then describe code the user has already changed.
 
 On failure the command prints one line per problem, then an error line, and exits 5:
 
@@ -113,35 +152,33 @@ verbatim. Do not weaken the content to pass: shorten text, move hunks, fix links
 If publish prints `CANVAS_STALE`, the branch moved while you worked. Tell the user and offer to run
 prepare again; pass `--allow-stale` only when the user asks for the canvas of the old commit.
 
-### 6. Export the zip
+### 6. Report the sharing result
 
-```bash
-pr-review export --head <headSha> [--pr <n>]
-```
-
-Pass `--pr <n>` when the run had a PR number, so the file name and the manifest carry it. The
-command prints one JSON line with the absolute `path` of the zip.
+For a PR/MR run, report the local `reviewUrl` (start it with `pr-review serve`) and inspect `sharing`:
 
-### 7. Finish
+- `status: "shared"`: link to `sharing.url` and say the canvas was shared automatically.
+- `status: "failed"`: clearly warn that automatic sharing failed, quote `sharing.warning`, and
+  give the absolute `sharing.zipPath`. Tell the user to open the PR/MR, edit its description,
+  drag the ZIP into the editor, wait for upload to finish, and save. Replace any older canvas
+  attachment link. Include these instructions in your final response; the local canvas is ready,
+  but reviewers still need the upload. Do not regenerate the model to repair a sharing failure.
 
-For a PR run, report the `reviewUrl` from publish, the absolute zip path from export, and a link
-to the GitHub PR from the prepared context. End with upload instructions:
+For a local run, `sharing.status` is `"local"` and there is nothing to share. Give the user
+`reviewUrl` (`http://localhost:<port>/review/branch` or `.../review/uncommitted`) and tell them to
+start `pr-review serve` if it is not running. Say which base was compared and whether uncommitted
+work was included, both from the `local` object prepare printed.
 
-> The canvas is ready at <reviewUrl> (start the server with `pr-review serve` if it is not running).
-> ZIP: <path>
-> If you're happy with the produced canvas, open <PR URL>, edit the PR description, drag the ZIP
-> into the editor, wait for the upload to finish, and save.
+For a `--base/--head` run, `sharing.status` is `"local"` too, but the canvas has no page of its
+own. Report the stored commit and export it:
 
-For an update, tell the user to replace the old canvas attachment link with the new one.
-Include these instructions in the final response without asking a question or waiting for a reply.
-
-Uploading and saving the description are manual browser steps. Do not create a release or claim
-the ZIP was uploaded. GitHub's `gh --attach` supports images and video, but not ZIP files
-([supported types](https://github.com/cli/cli/blob/trunk/internal/attachments/userasset.go)).
+```bash
+pr-review export --head <headSha>
+```
 
-For a `--base/--head` run, say the canvas is stored for `<headSha>`, that the zip has no PR number
-yet, and that `pr-review export --pr <n>` re-exports it once the pull request exists. Include the
-manual upload instructions for when the PR is ready.
+Give the returned absolute ZIP path. Once a PR exists, `pr-review export --head <headSha> --pr <n>`
+stamps its number for manual upload, or rerun this skill for the PR number with `--force` to share
+automatically. A canvas of a working-tree snapshot cannot be carried to a pull request this way:
+its commit is on no branch, so generate a fresh one for the PR.
 
 ## Rules the validator enforces (and models tend to break)
 
@@ -172,6 +209,6 @@ manual upload instructions for when the PR is ready.
 ## Updating a shared canvas
 
 After new commits, run this skill again for the PR number. Add `--force` to regenerate a canvas
-for the same commit. Export the new zip and ask the user to replace the attachment in their PR
-description. Reviewers click **refresh** to load it. A canvas for a different
+for the same commit. Publish updates your canvas comment; follow the sharing-result instructions
+above if it fails. Reviewers click **refresh** to load it. A canvas for a different
 PR head shows **Canvas is outdated**; an older canvas remains readable with posting disabled.

package/src/acpx/acpx.ts

@@ -231,7 +231,11 @@ export function createAgentRunner(opts: CreateAgentRunnerOptions = {}): AgentRun
         // The cancel call gets its own timeout, and SIGKILL when it elapses: a cancel that hangs
         // must neither hold the kill back nor stay behind as a process of its own.
         agentArgs =>
-          execQuiet(bin, agentArgs, { cwd: options.cwd, timeoutSec: CANCEL_TIMEOUT_SEC, killSignal: 'SIGKILL' }),
+          execQuiet(bin, agentArgs, {
+            cwd: options.cwd,
+            timeoutSec: CANCEL_TIMEOUT_SEC,
+            killSignal: 'SIGKILL',
+          }),
         slackMs,
         cancelGraceMs
       )
@@ -268,7 +272,12 @@ export function createAgentRunner(opts: CreateAgentRunnerOptions = {}): AgentRun
         }
       }
       if (!ended) {
-        return { ok: false, text: '', code: 'AGENT_INCOMPLETE', message: 'the agent stopped before finishing' }
+        return {
+          ok: false,
+          text: '',
+          code: 'AGENT_INCOMPLETE',
+          message: 'the agent stopped before finishing',
+        }
       }
       return text === ''
         ? { ok: false, text: '', code: 'AGENT_INCOMPLETE', message: 'the agent replied nothing' }
@@ -516,11 +525,19 @@ function startRun(
     const exit = code ?? 1
     const mapped = exitCodeToAgentCode(exit)
     if (mapped !== null) {
-      finish({ type: 'error', code: mapped, message: stderr.trim() === '' ? exitCodeMessage(exit) : stderr.trim() })
+      finish({
+        type: 'error',
+        code: mapped,
+        message: stderr.trim() === '' ? exitCodeMessage(exit) : stderr.trim(),
+      })
       return
     }
     // acpx 0.13.2 exits 0 when its own --timeout elapses, without a terminal event.
-    finish({ type: 'error', code: 'AGENT_INCOMPLETE', message: 'the agent stopped before finishing its answer' })
+    finish({
+      type: 'error',
+      code: 'AGENT_INCOMPLETE',
+      message: 'the agent stopped before finishing its answer',
+    })
   })
 
   child.stdin?.on('error', () => undefined)

package/src/acpx/events.ts

@@ -64,7 +64,11 @@ function contentText(value: unknown): string {
  */
 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' }
+    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)) {

package/src/acpx/ndjson.ts

@@ -50,7 +50,9 @@ export function createNdjsonSplitter(lineMax: number = NDJSON_LINE_MAX): NdjsonS
         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`)
+          throw new NdjsonError(
+            `the agent wrote a line of ${raw.length} characters, over the ${lineMax} limit`
+          )
         }
         out.push(...take(raw))
         at = buffer.indexOf('\n')

package/src/acpx/preflight.ts

@@ -16,7 +16,11 @@ export interface PreflightProbe {
  * 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 {
+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 {

package/src/canvas/comment.ts

@@ -0,0 +1,24 @@
+import type { CanvasZip } from './export.js'
+
+export const CANVAS_COMMENT_MARKER = '<!-- pr-review-canvas:v1\n'
+
+/** The ZIP stays in the raw comment body; the rendered comment gives reviewer instructions. */
+export function buildCanvasComment(zip: CanvasZip, limit: number): string {
+  const body = `PR Review Canvas for commit ${zip.headSha}.\n\nRun \`pr-review serve\` and open #${zip.prNumber}. If already reviewing, click **refresh**.\n\n${CANVAS_COMMENT_MARKER}${zip.name}\n${Buffer.from(zip.bytes).toString('base64')}\n-->`
+  if (body.length > limit) {
+    throw new Error(
+      `the compressed canvas comment needs ${body.length} characters; the host limit is ${limit}`
+    )
+  }
+  return body
+}
+
+/** Only the versioned envelope is decoded. ZIP contents are checked by the normal importer. */
+export function readCanvasComment(body: string): { name: string; bytes: Uint8Array } | null {
+  const match = /<!-- pr-review-canvas:v1\n([A-Za-z0-9._-]+\.zip)\n([A-Za-z0-9+/]+={0,2})\n-->/.exec(body)
+  if (match === null) return null
+  const name = match[1]!
+  const encoded = match[2]!
+  if (encoded.length > 1_000_000 || encoded.length % 4 !== 0) return null
+  return { name, bytes: Buffer.from(encoded, 'base64') }
+}

package/src/canvas/export.ts

@@ -37,7 +37,12 @@ export async function buildCanvasZipFor(
   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, generatedAt: manifest.generatedAt }),
+    name: buildCanvasZipName({
+      repo: manifest.repo,
+      headSha,
+      prNumber: number,
+      generatedAt: manifest.generatedAt,
+    }),
     bytes: buildCanvasZip(manifest, artifact),
     headSha,
   }
@@ -64,7 +69,11 @@ async function isDirectory(target: string): Promise<boolean> {
 }
 
 /** `--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> {
+export async function resolveOutPath(
+  out: string | undefined,
+  defaultDir: string,
+  name: string
+): Promise<string> {
   if (out === undefined) {
     return path.join(defaultDir, name)
   }

package/src/canvas/import.ts

@@ -1,18 +1,20 @@
 // 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 DiffedCommit, standsForHead } from '../review/carry-over.js'
 import type { AppContext } from '../server/context.js'
 import { AppError } from '../server/errors.js'
-import { CanvasZipError, readCanvasZip } from './zip.js'
+import { type CanvasZipContents, 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
+  /**
+   * The head the page is looking at, with the merge base its diff runs from. Absent means the
+   * canvas is taken as the current one.
+   */
+  currentHead?: DiffedCommit | undefined
   /** Accepts a canvas exported from another repository. */
   force?: boolean | undefined
 }
@@ -79,13 +81,13 @@ async function relateToHead(
  * 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 }
+  let contents: CanvasZipContents
   try {
     contents = readCanvasZip(opts.bytes)
   } catch (err) {
     throw err instanceof CanvasZipError ? toAppErrorFromZip(err) : err
   }
-  const { manifest, artifact } = contents
+  const { manifest, artifact, prNumber: canvasPr } = contents
   const warnings: string[] = []
   if (!sameRepo(manifest.repo, ctx.config.repo)) {
     const from = `${manifest.repo.owner}/${manifest.repo.name}`
@@ -100,8 +102,21 @@ export async function importCanvas(ctx: AppContext, opts: ImportOptions): Promis
     warnings.push(`imported a canvas exported from ${from}`)
   }
 
+  // The wrong zip attached to a pull request is the common mistake, and the head check below does
+  // not catch it: two open pull requests have unrelated heads either way. This is the one check
+  // --force cannot lift: the canvas in this zip may only be stored under the pull request it
+  // names, so forcing could only write an index entry that contradicts the zip it came from.
+  if (opts.prNumber !== undefined && canvasPr !== undefined && canvasPr !== opts.prNumber) {
+    throw new AppError(
+      'CANVAS_PR_MISMATCH',
+      `this canvas was exported for #${canvasPr}, and it is being imported for #${opts.prNumber}`,
+      400,
+      `import it without --pr to store it under #${canvasPr}, or generate a canvas for #${opts.prNumber}`
+    )
+  }
+
   const headSha = manifest.headSha
-  const currentHeadSha = opts.currentHeadSha ?? headSha
+  const currentHeadSha = opts.currentHead?.headSha ?? headSha
   const index = await ctx.canvases.readIndex()
   const stored = index.canvases[headSha]
   const keepStored = stored !== undefined && stored.generatedAt >= artifact.generatedAt
@@ -119,7 +134,13 @@ export async function importCanvas(ctx: AppContext, opts: ImportOptions): Promis
   if (keepStored) {
     return { status: 'exists', headSha, currentHeadSha, derivable, warnings }
   }
-  if (headSha === currentHeadSha) {
+  // The same rule the page reads: a canvas of another commit is current when the head's diff is
+  // identical to the one it was generated from, so the CLI never calls stale what the page shows
+  // as carried over.
+  if (
+    opts.currentHead === undefined ||
+    (await standsForHead(ctx, opts.currentHead, { headSha, mergeBaseSha }))
+  ) {
     return { status: 'ready', headSha, currentHeadSha, derivable, warnings }
   }
   const related = await relateToHead(ctx, headSha, currentHeadSha)

package/src/canvas/name.ts

@@ -33,6 +33,7 @@ export function buildCanvasZipName(opts: BuildNameOptions): string {
   return `${target}-${timestamp}-${opts.headSha.slice(0, 8)}-${repoSlug(opts.repo)}-canvas.zip`
 }
 
+/** The strict form of the grammar the drop zone applies to a picked file (`validateCanvasFilename`). */
 const NAME_RE = /^(?:pr-([1-9]\d*)|ref)-\d{8}t\d{6}z-([0-9a-f]{8})$/
 
 /**

package/src/canvas/zip.ts

@@ -14,6 +14,12 @@ export const ZIP_MAGIC = [0x50, 0x4b, 0x03, 0x04] as const
 export interface CanvasZipContents {
   manifest: CanvasManifest
   artifact: ReviewArtifact
+  /**
+   * The pull request the canvas was made for, once for every reader: the two entries are proved to
+   * agree below, and the two ways of holding "no pull request" are settled into one. A canvas
+   * generated before the pull request existed names none, and joins the PR that imports it.
+   */
+  prNumber?: number
 }
 
 /** A zip that cannot be read as a canvas. `issues` names the problems, never the file's content. */
@@ -66,7 +72,10 @@ function decode(entry: Uint8Array | undefined, name: string, issues: string[]):
  */
 export function readCanvasZip(bytes: Uint8Array): CanvasZipContents {
   if (bytes.length > CANVAS_ZIP_MAX_BYTES) {
-    throw new CanvasZipError('CANVAS_TOO_LARGE', `the canvas zip is larger than ${CANVAS_ZIP_MAX_BYTES} bytes`)
+    throw new CanvasZipError(
+      'CANVAS_TOO_LARGE',
+      `the canvas zip is larger than ${CANVAS_ZIP_MAX_BYTES} bytes`
+    )
   }
   if (!hasZipMagic(bytes)) {
     throw new CanvasZipError('CANVAS_INVALID', 'this file is not a zip', [
@@ -119,5 +128,19 @@ export function readCanvasZip(bytes: Uint8Array): CanvasZipContents {
       `${REVIEW_ENTRY} is for ${artifact.data.pr.headSha.slice(0, 7)} while ${MANIFEST_ENTRY} says ${manifest.data.headSha.slice(0, 7)}`,
     ])
   }
-  return { manifest: manifest.data, artifact: artifact.data }
+  // A canvas generated before the pull request existed carries no number in review.json, and the
+  // export stamps one on the manifest; only two numbers that are both there must agree.
+  const artifactPr = artifact.data.pr.number
+  const manifestPr = manifest.data.prNumber
+  if (artifactPr !== null && manifestPr !== undefined && artifactPr !== manifestPr) {
+    throw new CanvasZipError('CANVAS_INVALID', 'the zip is not a review canvas', [
+      `${REVIEW_ENTRY} is for #${artifactPr} while ${MANIFEST_ENTRY} says #${manifestPr}`,
+    ])
+  }
+  const contents: CanvasZipContents = { manifest: manifest.data, artifact: artifact.data }
+  const prNumber = manifestPr ?? artifactPr
+  if (prNumber !== null) {
+    contents.prNumber = prNumber
+  }
+  return contents
 }