@dev.fast/whiteboard 0.3.3 → 0.3.4-preview.20261019.125

package/src/review-api/mcp.ts

@@ -29,17 +29,9 @@ import { type ToolFailure, toolFailure } from "./tool-failure.js";
 const RELOAD_TOOLS =
   "Whiteboard is running now, but this session listed Whiteboard's tools before it started, so you may see only session_get_instructions. Before authoring, reload the `whiteboard` MCP server's tools (reconnect it in your agent, or start a new agent session). If you can already see tools such as session_create, carry on.";
 
-function mcpAuthoringGuidance(context: {
-  scratchpadAvailable: boolean;
-  traceEnabled: boolean;
-}): string {
+function mcpAuthoringGuidance(context: { traceEnabled: boolean }): string {
   return [
     "Whiteboard explains code in documents the user reads in Whiteboard Desktop. Call session_get_instructions before creating or editing a Whiteboard and follow it. Read session_capabilities before authoring; session_create opens the new review in Desktop when it is available, so call session_open only for an existing review, and generate software maps only when softwareMapEnabled is true. When the user asks for a Whiteboard or to use Whiteboard (for example to review a branch, a change or a pull request, or to explain a system in Whiteboard), author a Whiteboard with the default topic.",
-    ...(context.scratchpadAvailable
-      ? [
-          'When the user asks in conversation to be shown how code works or wants a diagram, without asking for a Whiteboard, call session_capabilities; if it reports scratchpadEnabled and desktopAvailable, draw on the Whiteboard scratchpad rather than answering only in chat, starting with session_get_instructions({topic:"scratchpad"}).',
-        ]
-      : []),
     ...(context.traceEnabled
       ? [
           'For why code exists, what an agent was thinking, or whether an agent solved something before, call session_get_instructions({topic:"trace-archaeology"}).',
@@ -66,7 +58,7 @@ export async function serveReviewMcp(
   environmentAgent?: ReviewSessionAgent,
 ) {
   const instructionsTool = {
-    ...authoringTools(false, traceEnabled).find(
+    ...authoringTools(traceEnabled).find(
       (tool) => tool.name === "review_get_instructions",
     )!,
     name: "session_get_instructions",
@@ -135,7 +127,7 @@ export async function serveReviewMcp(
           // guidance on the discovery tool instead, including before Desktop starts.
           description:
             name === instructionsTool.name
-              ? `${mcpAuthoringGuidance({ scratchpadAvailable: true, traceEnabled })}\n\n${description}`
+              ? `${mcpAuthoringGuidance({ traceEnabled })}\n\n${description}`
               : description,
           inputSchema,
         }),

package/src/review-api/onboarding.ts

@@ -462,7 +462,7 @@ export function registerOnboardingRoutes(
       agent: input.agent,
       ...host.historyHooks({
         id,
-        reviewId,
+        anchor: { board: reviewId },
         agent: input.agent,
         version: created.version,
         head,

package/src/review-api/profile.ts

@@ -4,8 +4,11 @@ import { DatabaseSync } from "node:sqlite";
 
 import { withFileLock } from "@dev.fast/trace-core";
 
+import { CheckoutGroups } from "./checkout-groups.js";
 import { openLocalReviewStore } from "./local-data.js";
+import { groupCheckoutsAhead } from "./store-migrations.js";
 import { initializeReviewStoreSchema } from "./store-schema.js";
+import { projectOfCheckout } from "./store.js";
 
 const lockOptions = {
   retryMs: 50,
@@ -16,7 +19,7 @@ const lockOptions = {
 
 export async function openReviewProfile(
   home: string,
-  options: { manageWorkspaces: boolean },
+  options: { manageWorkspaces: boolean; pullRequestStates?: boolean },
 ) {
   await mkdir(home, { recursive: true, mode: 0o700 });
 
@@ -30,7 +33,12 @@ export async function openReviewProfile(
       ])
         await importHeadlessStore(home, source);
 
-      return openLocalReviewStore(path.join(home, "review-api.db"), options);
+      const database = path.join(home, "review-api.db");
+
+      return openLocalReviewStore(database, {
+        ...options,
+        checkoutOwners: await groupCheckoutsAhead(database),
+      });
     },
   );
 
@@ -89,7 +97,7 @@ async function importHeadlessStore(home: string, source: string) {
               `Cannot merge ${source}: the shared store already contains one of its review IDs. Both databases are unchanged.`,
             );
           database.exec(`
-          INSERT INTO repositories SELECT s.* FROM headless.repositories s WHERE NOT EXISTS (SELECT 1 FROM repositories t WHERE t.path=s.path);
+          INSERT INTO repositories(id,path,name) SELECT s.id,s.path,s.name FROM headless.repositories s WHERE NOT EXISTS (SELECT 1 FROM repositories t WHERE t.path=s.path);
           CREATE TEMP TABLE repository_ids AS SELECT s.id old_id,t.id new_id FROM headless.repositories s JOIN repositories t ON s.path=t.path;
         `);
 
@@ -114,13 +122,36 @@ async function importHeadlessStore(home: string, source: string) {
               `Cannot merge ${source}: a resource ID has different content. Both databases are unchanged.`,
             );
 
+          if (
+            database
+              .prepare(
+                "SELECT 1 FROM pragma_table_info('reviews') WHERE name='project_id'",
+              )
+              .get()
+          ) {
+            // A store with projects: file each board under its repository's,
+            // grouping the checkouts once for all of them.
+            const groups = new CheckoutGroups(database);
+
+            for (const { new_id: repositoryId } of database
+              .prepare("SELECT new_id FROM repository_ids")
+              .all())
+              projectOfCheckout(database, String(repositoryId), groups);
+            database.exec(`INSERT INTO reviews(id,version,next_id,project_id) SELECT s.id,s.version,s.next_id,p.project_id
+              FROM headless.reviews s JOIN headless.versions v ON v.review_id=s.id AND v.version=s.version
+              JOIN repository_ids r ON json_extract(v.snapshot,'$.pins.repositoryId')=r.old_id
+              JOIN repositories p ON p.id=r.new_id;`);
+          } else
+            database.exec(
+              "INSERT INTO reviews(id,version,next_id) SELECT id,version,next_id FROM headless.reviews;",
+            );
           database.exec(`
           INSERT OR IGNORE INTO resources SELECT s.id,r.new_id,s.kind,s.mime_type,s.data FROM headless.resources s JOIN repository_ids r ON s.repository_id=r.old_id;
-          INSERT INTO reviews SELECT * FROM headless.reviews;
-          INSERT INTO versions SELECT s.review_id,s.version,
+          INSERT INTO versions(review_id,version,snapshot,thread_id,author_kind) SELECT s.review_id,s.version,
             CASE WHEN json_type(s.snapshot,'$.target')='object'
               THEN json_set(s.snapshot,'$.pins.repositoryId',r.new_id,'$.target.repositoryId',r.new_id)
-              ELSE json_set(s.snapshot,'$.pins.repositoryId',r.new_id) END
+              ELSE json_set(s.snapshot,'$.pins.repositoryId',r.new_id) END,
+            NULL, NULL
             FROM headless.versions s JOIN repository_ids r ON json_extract(s.snapshot,'$.pins.repositoryId')=r.old_id;
           INSERT INTO review_attention SELECT * FROM headless.review_attention;
         `);

package/src/review-api/public-tools.ts

@@ -1,4 +1,5 @@
 import { type JsonValue, isJsonObject, isStringValue } from "@dev.fast/json";
+import { boardTitle } from "@dev.fast/review-protocol";
 
 import {
   type AuthoringTool,
@@ -78,7 +79,13 @@ export function publicResult(value: JsonValue): JsonValue {
 
       return [
         name,
-        key === "review" || key === "reviews" ? publicResult(item) : item,
+        key === "review" || key === "reviews"
+          ? publicResult(item)
+          : // A board's title as every surface shows it: an empty one is
+            // "Untitled".
+            key === "title" && "reviewId" in value && isStringValue(item)
+            ? boardTitle(item)
+            : item,
       ];
     }),
   );
@@ -98,5 +105,20 @@ export async function callPublicTool(
   if (sessionId !== undefined) fields.reviewId = sessionId;
   const result = await callAuthoringTool(client, tool, fields, signal);
 
-  return result instanceof ToolText ? result : publicResult(result);
+  return result instanceof ToolText
+    ? result
+    : withoutRepositoryIds(publicResult(result));
+}
+
+/** Agents never see repository ids. */
+function withoutRepositoryIds(value: JsonValue): JsonValue {
+  if (Array.isArray(value)) return value.map(withoutRepositoryIds);
+
+  if (!isJsonObject(value)) return value;
+
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([key]) => key !== "repositoryId")
+      .map(([key, item]) => [key, withoutRepositoryIds(item)]),
+  );
 }

package/src/review-api/pull-request.ts

@@ -1,18 +1,29 @@
 import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
-
-import type { LocalVcsKind } from "@dev.fast/local-vcs";
+import { promisify } from "node:util";
+
+import {
+  type LocalVcsKind,
+  type VcsArg,
+  renderVcsArgs,
+  runVcs,
+} from "@dev.fast/local-vcs";
+import type { PullRequestState } from "@dev.fast/review-protocol";
 import { errorMessage } from "@dev.fast/trace-core";
 
 import { ReviewInputError } from "./document.js";
 
-/** Runs one subprocess and resolves its stdout; rejects on failure or timeout. */
+/** Runs one subprocess and resolves its stdout; rejects on failure or
+ * timeout. git, jj and gh go through the VCS runner; Azure DevOps's az (by
+ * way of cmd.exe on Windows) gets its operands checked the same way. */
 export type RunCommand = (
-  file: string,
-  args: string[],
+  file: "git" | "jj" | "gh" | "az" | "cmd.exe",
+  args: VcsArg[],
   options: { cwd?: string; timeoutMs: number },
 ) => Promise<string>;
 
+const execFileAsync = promisify(execFile);
+
 export interface PullRequestDeps {
   run: RunCommand;
   fetch: typeof fetch;
@@ -31,6 +42,7 @@ export interface PullRequestRecord {
   headBranch?: string;
   /** GitHub's base commit, frozen at the PR's last update. */
   baseRefOid?: string;
+  state?: PullRequestState;
 }
 
 const FETCH_TIMEOUT_MS = 120_000;
@@ -38,35 +50,38 @@ const FETCH_TIMEOUT_MS = 120_000;
 const LOCAL_TIMEOUT_MS = 30_000;
 
 export const defaultPullRequestDeps: PullRequestDeps = {
-  run: (file, args, options) =>
-    new Promise((resolve, reject) => {
-      execFile(
-        file,
-        args,
-        {
-          cwd: options.cwd,
-          timeout: options.timeoutMs,
-          maxBuffer: 16 * 1024 * 1024,
-          // Never wait on a credential or confirmation prompt nobody can see.
-          env: {
-            ...process.env,
-            GIT_TERMINAL_PROMPT: "0",
-            GH_PROMPT_DISABLED: "1",
-            GIT_SSH_COMMAND:
-              process.env.GIT_SSH_COMMAND ?? "ssh -o BatchMode=yes",
-          },
-        },
-        (error, stdout, stderr) => {
-          if (!error) return resolve(stdout);
-
-          const reason = error.killed
-            ? `timed out after ${options.timeoutMs / 1000}s`
-            : String(stderr).trim() || error.message;
-
-          reject(new Error(`${file} ${args[0]}: ${reason}`));
-        },
-      );
-    }),
+  run: async (file, args, options) => {
+    const spawnOptions = {
+      cwd: options.cwd,
+      timeout: options.timeoutMs,
+      maxBuffer: 16 * 1024 * 1024,
+      // Never wait on ssh asking for a passphrase nobody can see.
+      env: {
+        ...process.env,
+        GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND ?? "ssh -o BatchMode=yes",
+      },
+    };
+
+    try {
+      return (
+        file === "az" || file === "cmd.exe"
+          ? await execFileAsync(file, renderVcsArgs(args), {
+              ...spawnOptions,
+              encoding: "utf8",
+            })
+          : await runVcs(file, args, spawnOptions)
+      ).stdout;
+    } catch (error) {
+      // SAFETY: execFile rejects with an ExecFileException carrying stderr.
+      const failure = error as { killed?: boolean; stderr?: string };
+
+      const reason = failure.killed
+        ? `timed out after ${options.timeoutMs / 1000}s`
+        : String(failure.stderr ?? "").trim() || errorMessage(error);
+
+      throw new Error(`${file} ${String(args[0])}: ${reason}`);
+    }
+  },
   fetch: (input, init) => fetch(input, init),
 };
 
@@ -135,55 +150,62 @@ export async function fetchPullRequest(
   const { pullRequest: pr } = input;
   const refs = pullRequestRefs(input.provider, pr);
 
-  const git = (args: string[], timeoutMs = LOCAL_TIMEOUT_MS) =>
+  const git = (args: VcsArg[], timeoutMs = LOCAL_TIMEOUT_MS) =>
     deps
       .run("git", ["--git-dir", input.gitDir, ...args], { timeoutMs })
       .then((stdout) => stdout.trim());
 
-  const fetchRefs = (...refspecs: string[]) =>
+  const fetchRefs = (...refspecs: VcsArg[]) =>
     git(
       [
         "fetch",
         "--no-tags",
         "--no-write-fetch-head",
         "--quiet",
-        input.remote,
+        { remote: input.remote },
         ...refspecs,
       ],
       FETCH_TIMEOUT_MS,
     );
 
   const commit = (ref: string) =>
-    git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]).catch(
+    git(["rev-parse", "--verify", "--quiet", { rev: `${ref}^{commit}` }]).catch(
       () => undefined,
     );
 
   const mergeBase = (left: string, right: string) =>
-    git(["merge-base", left, right]).catch(() => undefined);
+    git(["merge-base", { rev: left }, { rev: right }]).catch(() => undefined);
 
   const frozenBase = async () => {
     if (!pr.baseRefOid) return undefined;
 
     if (!(await commit(pr.baseRefOid)))
-      await fetchRefs(`+${pr.baseRefOid}:${refs.frozenBase}`).catch(
-        () => undefined,
-      );
+      await fetchRefs({
+        refspec: { from: pr.baseRefOid, to: refs.frozenBase, force: true },
+      }).catch(() => undefined);
 
     return commit(pr.baseRefOid);
   };
 
   let baseTip: string | undefined;
 
+  const pullHead: VcsArg = {
+    refspec: { from: pr.headRef, to: refs.head, force: true },
+  };
+
   try {
-    await fetchRefs(
-      `+${pr.headRef}:${refs.head}`,
-      `+refs/heads/${pr.baseRefName}:${refs.base}`,
-    );
+    await fetchRefs(pullHead, {
+      refspec: {
+        from: `refs/heads/${pr.baseRefName}`,
+        to: refs.base,
+        force: true,
+      },
+    });
     baseTip = await commit(refs.base);
   } catch (error) {
     // The base branch may be gone; the head and the frozen base suffice.
     try {
-      await fetchRefs(`+${pr.headRef}:${refs.head}`);
+      await fetchRefs(pullHead);
     } catch {
       throw new ReviewInputError(
         `Could not fetch PR #${pr.number} from remote "${input.remote}" (${pr.slug}). Check \`git fetch ${input.remote}\` works with your Git credentials, then retry. Git said: ${firstLine(errorMessage(error))}`,
@@ -232,7 +254,7 @@ export async function fetchPullRequest(
 async function indexForJj(
   rootPath: string,
   commits: string[],
-  git: (args: string[]) => Promise<string>,
+  git: (args: VcsArg[]) => Promise<string>,
   deps: PullRequestDeps,
 ) {
   const tags = commits.map(() => `refs/tags/review-index-${randomUUID()}`);
@@ -246,7 +268,7 @@ async function indexForJj(
 
   try {
     for (const [index, tag] of tags.entries())
-      await git(["update-ref", tag, commits[index]!]);
+      await git(["update-ref", { ref: tag }, { commit: commits[index]! }]);
     await jjImport();
   } finally {
     for (const tag of tags)
@@ -255,6 +277,17 @@ async function indexForJj(
   }
 }
 
+/** GitHub refused a read, as it does past a rate limit; it takes reads
+ * again at `retryAt`. */
+export class GitHubRefusedRead extends ReviewInputError {
+  constructor(
+    message: string,
+    readonly retryAt: number,
+  ) {
+    super(message, 409);
+  }
+}
+
 export function firstLine(text: string) {
   return text.split("\n")[0]!.slice(0, 300);
 }

package/src/review-api/request-origin.ts

@@ -13,6 +13,16 @@ export const REVIEW_VIA_HEADER = "x-review-via";
 
 export const REVIEW_AGENT_HEADER = "x-review-agent";
 
+/** The Ask thread a request comes from. The CLI reads it from ASK_THREAD_ENV,
+ * which Desktop sets for the thread's agent. */
+export const REVIEW_THREAD_HEADER = "x-review-thread";
+
+export const ASK_THREAD_ENV = "DEV_REVIEW_ASK_THREAD";
+
+/** Set by Desktop and the canvas on a command a person gave, such as a new
+ * board from the sidebar; its version is credited to them. */
+export const REVIEW_PERSON_HEADER = "x-review-person";
+
 export type ReviewRequestVia = "api" | "mcp" | "other";
 
 const viaSchema = z.enum(["api", "mcp", "other"]).catch("other");

package/src/review-api/review-progress.ts

@@ -1,5 +1,7 @@
 import {
   type LensSource,
+  SelectionUnavailableError,
+  type SelectionUnavailableReason,
   comparisonKey,
   resolveDiffSelection,
   selectionKey,
@@ -15,8 +17,15 @@ import {
   UNCATEGORIZED_LENS_ID,
   lensSelections,
 } from "./diff-lenses.js";
-import { type Pins, anchorPins, selectionReferences } from "./document.js";
+import {
+  type Pins,
+  anchorPins,
+  boardRepositoryId,
+  selectionReferences,
+} from "./document.js";
 import { resolveFileLens, uncategorizedSources } from "./file-lenses.js";
+import { ReviewInputError } from "./input-error.js";
+import { textualRows } from "./lens-alignment.js";
 import type { LocalReviewData } from "./local-data.js";
 import type { ReviewStore, Snapshot } from "./store.js";
 
@@ -40,7 +49,7 @@ export const progressUpdateSchema = z.strictObject({
 
 export interface ReviewProgress {
   complete?: boolean;
-  unavailableSelections?: Record<string, string>;
+  unavailableSelections?: Record<string, SelectionUnavailableReason>;
   files: CoverageFile[];
   /** Changed files of the comparisons that references with their own pins
    * named, by `comparisonKey` and then path. They are not the document's
@@ -130,7 +139,7 @@ export async function reviewProgress(
   const alignments = new Map(comparison.alignments);
   const resolvedSelections: Record<string, FileLineRange[]> = {};
 
-  const unavailableSelections: Record<string, string> = {};
+  const unavailableSelections: Record<string, SelectionUnavailableReason> = {};
   const pendingSources = new Set<string>();
 
   const resolve = async (source: LensSource): Promise<FileLineRange[]> => {
@@ -169,7 +178,8 @@ export async function reviewProgress(
     let rows = file && ownAlignments.get(file.path);
 
     // Context-only files are absent from the changed-file stream. Read both pins
-    // and require equality rather than inventing correspondence for missing diffs.
+    // and require equality rather than inventing correspondence for missing
+    // diffs; a file on one side only, such as an untracked one, is that side.
     if (!file && counting && !own) {
       pendingSources.add(key);
 
@@ -177,20 +187,43 @@ export async function reviewProgress(
     }
 
     if (!file) {
-      const [base, head] = await Promise.all([
-        data.file(sourcePins, "base", source.file),
-        data.file(sourcePins, "head", source.file),
-      ]);
-
-      if (base.text !== head.text)
-        throw new Error("Changed context file has no alignment.");
-      rows = Array.from(
-        { length: base.text.split("\n").length },
-        (_, line) => [line, line] as const,
+      const [base, head] = await Promise.all(
+        (["base", "head"] as const).map((side) =>
+          data.file(sourcePins, side, source.file).then(
+            (value) => value.text,
+            (error) => {
+              if (error instanceof ReviewInputError && error.status === 404)
+                return null;
+              throw error;
+            },
+          ),
+        ),
+      );
+
+      if (base === null && head === null)
+        throw new SelectionUnavailableError(
+          "missing_file",
+          "File is unavailable at these pins.",
+        );
+
+      if (base !== null && head !== null && base !== head)
+        throw new SelectionUnavailableError(
+          "no_alignment",
+          "Changed context file has no alignment.",
+        );
+      rows = textualRows(
+        source.file,
+        "",
+        base?.split("\n").length ?? 0,
+        head?.split("\n").length ?? 0,
       );
     }
 
-    if (!rows) throw new Error("File has no text alignment.");
+    if (!rows)
+      throw new SelectionUnavailableError(
+        "no_alignment",
+        "File has no text alignment.",
+      );
 
     const result = resolveDiffSelection(
       source,
@@ -206,9 +239,9 @@ export async function reviewProgress(
   const resolveAvailable = async (source: LensSource) => {
     try {
       return await resolve(source);
-    } catch {
+    } catch (error) {
       unavailableSelections[selectionKey(source)] =
-        "Source links need updating at these pins";
+        error instanceof SelectionUnavailableError ? error.reason : "other";
 
       return [];
     }
@@ -254,15 +287,16 @@ export async function reviewProgress(
 
   // Peeks share alignment resolution without claiming lens coverage.
   await Promise.all(
-    selectionReferences(snapshot.document, { tolerant: true }).map(
-      async ({ source }) => {
-        try {
-          await resolveAvailable(source);
-        } catch {
-          /* An unavailable peek does not hide other content. */
-        }
-      },
-    ),
+    selectionReferences(snapshot.document, {
+      tolerant: true,
+      repositoryId: boardRepositoryId(snapshot),
+    }).map(async ({ source }) => {
+      try {
+        await resolveAvailable(source);
+      } catch {
+        /* An unavailable peek does not hide other content. */
+      }
+    }),
   );
 
   const uncategorized = counting
@@ -299,7 +333,7 @@ export async function reviewProgress(
   });
 
   const progress: ReviewProgress = {
-    complete: !counting,
+    complete: !counting && !pendingSources.size,
     files,
     referenceFiles,
     lenses,