@dev.fast/whiteboard 0.3.4 → 0.3.5-preview.20261020.130

package/src/review-api/worktree-events.ts

@@ -1,8 +1,6 @@
-import { execFile } from "node:child_process";
 import { isAbsolute, relative } from "node:path";
-import { promisify } from "node:util";
 
-const exec = promisify(execFile);
+import { runVcs } from "@dev.fast/local-vcs";
 
 const normalize = (name: string) => name.replaceAll("\\", "/").normalize("NFC");
 
@@ -53,7 +51,7 @@ export async function ignoredDirectories(
   gitDirectory?: string,
 ): Promise<string[]> {
   try {
-    const { stdout } = await exec(
+    const { stdout } = await runVcs(
       "git",
       [
         "-C",
@@ -105,7 +103,7 @@ export async function gitDirectoryPrefix(
   common: string,
 ): Promise<string | null> {
   try {
-    const { stdout } = await exec("git", [
+    const { stdout } = await runVcs("git", [
       "-C",
       rootPath,
       "rev-parse",

package/src/review-api/worktree-source.ts

@@ -1,9 +1,7 @@
-import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
-import { promisify } from "node:util";
 
-import { type LocalVcs, gitCommonDir } from "@dev.fast/local-vcs";
+import { type LocalVcs, gitCommonDir, runVcs } from "@dev.fast/local-vcs";
 import { isMissingFileError } from "@review/fs-utils.js";
 
 import { checkoutFs } from "./checkout-fs.js";
@@ -11,8 +9,6 @@ import { ReviewInputError } from "./document.js";
 
 const { lstat, readFile, readlink, realpath } = checkoutFs;
 
-const exec = promisify(execFile);
-
 export const EMPTY_SOURCE = "empty-worktree-baseline";
 
 /** Never follow a working-copy link outside the selected checkout. */
@@ -49,7 +45,7 @@ export async function workingFiles(vcs: LocalVcs): Promise<string[]> {
       "Working source requires a Git-backed jj repository.",
     );
 
-  const { stdout } = await exec(
+  const { stdout } = await runVcs(
     "git",
     [
       "-C",
@@ -100,7 +96,7 @@ export async function untrackedFileCount(
   if (vcs.kind !== "git") return undefined;
 
   try {
-    const { stdout } = await exec(
+    const { stdout } = await runVcs(
       "git",
       [
         "-C",

package/src/review-api/worktree-structural.integration.ts

@@ -318,3 +318,75 @@ it("compares a staged file in an unborn repository with empty source", async ()
     rmSync(root, { recursive: true, force: true });
   }
 }, 30_000);
+
+it("shows a peek on an untracked file as head lines", async () => {
+  const root = mkdtempSync(path.join(tmpdir(), "worktree-untracked-"));
+  const repository = path.join(root, "repository");
+  mkdirSync(repository);
+
+  const git = (...args: string[]) =>
+    execFileSync("git", ["-C", repository, ...args], {
+      encoding: "utf8",
+    }).trim();
+
+  git("init", "-q", "-b", "main");
+  writeFileSync(path.join(repository, "value.ts"), "export const value = 1;\n");
+  git("add", "value.ts");
+  git(
+    "-c",
+    "user.name=Test",
+    "-c",
+    "user.email=test@example.invalid",
+    "commit",
+    "-qm",
+    "Base",
+  );
+  writeFileSync(path.join(repository, "new.ts"), "export const a = 1;\n");
+
+  const local = openLocalReviewStore(path.join(root, "reviews.db"));
+
+  const selection = {
+    file: "new.ts",
+    start: { side: "head" as const, line: 1 },
+    end: { side: "head" as const, line: 1 },
+  };
+
+  try {
+    const { id } = await local.data.register(repository);
+
+    const { reviewId } = await local.store.execute({
+      operation: {
+        type: "create",
+        title: "Live",
+        target: { kind: "worktree", repositoryId: id },
+      },
+    });
+
+    await local.store.execute({
+      operation: {
+        type: "edit",
+        reviewId,
+        edit: {
+          type: "insert",
+          content: { type: "code_peek", source: formatAnchor(selection) },
+        },
+      },
+    });
+
+    const progress = await (
+      await createReviewApi(local.store, local.data).request(
+        `/${reviewId}/progress`,
+      )
+    ).json();
+
+    expect(progress.untrackedFiles).toBe(1);
+    expect(progress.unavailableSelections).toEqual({});
+    expect(progress.resolvedSelections[selectionKey(selection)]).toEqual([
+      { file: "new.ts", side: "head", fromLine: 1, toLine: 1 },
+    ]);
+  } finally {
+    await local.data.close();
+    await local.store.close();
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/src/review-stack.ts

@@ -1,15 +1,10 @@
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-
-import { defaultBranch, git } from "@dev.fast/local-vcs";
+import { defaultBranch, git, runVcs } from "@dev.fast/local-vcs";
 import type {
   ReviewApiSummary,
   ReviewStackLayer,
 } from "@dev.fast/review-protocol";
 import { z } from "zod";
 
-const execFileAsync = promisify(execFile);
-
 const GitHubStacksSchema = z.array(
   z.object({
     pull_requests: z.array(
@@ -27,7 +22,7 @@ type Subject = Pick<ReviewApiSummary, "origin"> & { reviewId?: string };
 
 type Candidate = Pick<
   ReviewApiSummary,
-  "reviewId" | "title" | "origin" | "pins" | "trashedAt" | "repositoryGroup"
+  "reviewId" | "title" | "origin" | "pins" | "trashedAt" | "project"
 >;
 
 interface StackEntry {
@@ -140,7 +135,7 @@ async function localStack(
   repositoryPath: string,
 ): Promise<StackEntry[]> {
   const group = reviews.find((review) => review.reviewId === subject.reviewId)
-    ?.repositoryGroup?.key;
+    ?.project?.id;
 
   const current = subject.origin?.branch;
 
@@ -152,9 +147,7 @@ async function localStack(
 
   const name = (ref: string) => ref.replace(/^origin\//, "");
 
-  const inGroup = reviews.filter(
-    (review) => review.repositoryGroup?.key === group,
-  );
+  const inGroup = reviews.filter((review) => review.project?.id === group);
 
   const latest = (field: "branch" | "baseBranch", branch: string) => {
     const matches = inGroup.filter(
@@ -208,9 +201,13 @@ async function localStack(
 async function forkPoint(repositoryPath: string, main: string, branch: string) {
   const ref = `refs/heads/${branch}`;
 
-  const fork = await git(repositoryPath, ["merge-base", main, ref], {
-    allowFailure: true,
-  });
+  const fork = await git(
+    repositoryPath,
+    ["merge-base", { rev: main }, { rev: ref }],
+    {
+      allowFailure: true,
+    },
+  );
 
   if (!fork.ok) return null;
 
@@ -218,7 +215,7 @@ async function forkPoint(repositoryPath: string, main: string, branch: string) {
 
   const log = await git(
     repositoryPath,
-    ["log", "--reverse", "--format=%s", `${base}..${ref}`],
+    ["log", "--reverse", "--format=%s", { rev: `${base}..${ref}` }],
     { allowFailure: true },
   );
 
@@ -229,15 +226,10 @@ async function defaultRunGitHubApi(
   host: string,
   endpoint: string,
 ): Promise<string> {
-  const { stdout } = await execFileAsync(
+  const { stdout } = await runVcs(
     "gh",
-    ["api", "--hostname", host, endpoint],
-    {
-      env: { ...process.env, GH_PROMPT_DISABLED: "1" },
-      encoding: "utf8",
-      timeout: 10_000,
-      maxBuffer: 2 * 1024 * 1024,
-    },
+    ["api", "--hostname", { value: host }, { value: endpoint }],
+    { timeout: 10_000, maxBuffer: 2 * 1024 * 1024 },
   );
 
   return stdout;

package/src/runtime.ts

@@ -1,6 +1,7 @@
-import { spawn } from "node:child_process";
 import path from "node:path";
 
+import { runVcs } from "@dev.fast/local-vcs";
+
 export async function resolveReviewRoot(
   cwd: string,
   execFile: typeof execFilePromise = execFilePromise,
@@ -39,36 +40,9 @@ export async function resolveReviewRoot(
 }
 
 function execFilePromise(
-  file: string,
+  file: "git" | "jj",
   args: string[],
   options: { cwd?: string } = {},
 ): Promise<{ stdout: string }> {
-  return execFileUntraced(file, args, options);
-}
-
-function execFileUntraced(
-  file: string,
-  args: string[],
-  options: { cwd?: string } = {},
-): Promise<{ stdout: string }> {
-  return new Promise((resolve, reject) => {
-    const child = spawn(file, args, {
-      cwd: options.cwd,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-
-    let stdout = "";
-    let stderr = "";
-    child.stdout?.on("data", (chunk) => {
-      stdout += String(chunk);
-    });
-    child.stderr?.on("data", (chunk) => {
-      stderr += String(chunk);
-    });
-    child.on("error", reject);
-    child.on("exit", (code) => {
-      if (code === 0) resolve({ stdout });
-      else reject(new Error(stderr.trim() || `${file} exited with ${code}`));
-    });
-  });
+  return runVcs(file, args, options);
 }

package/src/server/desktop-host.ts

@@ -84,6 +84,8 @@ export async function runDesktopHost(
   const { local, shared, server } = await takeOverServerHome(home, async () => {
     const local = await openReviewProfile(home, {
       manageWorkspaces: true,
+      // Desktop shows each PR's state beside its board.
+      pullRequestStates: true,
     });
 
     // JSON is the sole user-review store. A failure is surfaced, never replaced
@@ -197,9 +199,12 @@ function requiredPositiveInteger(
 
 if (process.env.DEV_FAST_REVIEW_DESKTOP_HOST_AUTOSTART !== "0") {
   void runDesktopHost().catch((error) => {
+    // Exit now: a host that couldn't start (a store that couldn't be
+    // upgraded) must not linger with timers alive, or Desktop waits out its
+    // ready timeout instead of reporting why.
     process.stderr.write(
       `${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`,
+      () => process.exit(1),
     );
-    process.exitCode = 1;
   });
 }

package/src/server/desktop-server.ts

@@ -47,10 +47,6 @@ import {
   reviewInstanceDiscoveryPath,
   reviewLegacyDiscoveryPath,
 } from "@review/review-home-paths";
-import {
-  readScratchpadEnabled,
-  writeScratchpadEnabled,
-} from "@review/review-preferences";
 import {
   ReviewTelemetry,
   type ReviewTelemetryContext,
@@ -176,10 +172,6 @@ export function createGlobalReviewServer(
   let closing = false;
   const cliPath = path.join(input.packageRoot, "dist", "cli.js");
 
-  // The scratchpad preference, read once at listen and kept current by the
-  // settings endpoint below: this server is the only writer while it runs.
-  let scratchpadEnabled = false;
-
   const discovery: ReviewDesktopDiscovery = {
     version: REVIEW_DESKTOP_DISCOVERY_VERSION,
     instanceId,
@@ -212,7 +204,6 @@ export function createGlobalReviewServer(
     relay,
     token,
     instanceId,
-    scratchpad: () => scratchpadEnabled,
     status: () => {
       const { key, channel, checkout, appVersion, cliVersion, instanceId } =
         discovery;
@@ -265,25 +256,6 @@ export function createGlobalReviewServer(
   app.all("/reviews-api", (context) => gateway.fetch(context.req.raw));
   app.all("/reviews-api/*", (context) => gateway.fetch(context.req.raw));
   app.get("/remote-hosts", () => serverJson(200, gateway.hosts()));
-  app.get("/preferences/scratchpad", () =>
-    serverJson(200, { enabled: scratchpadEnabled }),
-  );
-  app.put("/preferences/scratchpad", async (context) => {
-    const request = z
-      .object({ enabled: z.boolean() })
-      .safeParse(await readBoundedRequestJson(context.req.raw));
-
-    if (!request.success)
-      throw new ReviewServerError("enabled must be a boolean.", 400);
-
-    scratchpadEnabled = await writeScratchpadEnabled(request.data.enabled);
-
-    // Home watches the catalog; the pad appears or goes without a store write.
-    if (scratchpadEnabled) await reviewStore.ensureScratchpad();
-    reviewStore.invalidateCatalog();
-
-    return serverJson(200, { enabled: scratchpadEnabled });
-  });
   app.post("/app/focus", async () => {
     const result = await relay.dispatch({
       name: "focusWindow",
@@ -525,7 +497,6 @@ export function createGlobalReviewServer(
         store: reviewStore,
         data: input.reviewData,
       });
-      scratchpadEnabled = await readScratchpadEnabled();
       boundPort = await listen(httpServer, input.port);
       discovery.url = urlForBoundPort();
 
@@ -583,8 +554,7 @@ export function sessionStartedSource(
   try {
     const snapshot = reviewStore.read(reviewUuid);
 
-    const sourceKind =
-      snapshot.kind === "scratchpad" ? snapshot.kind : snapshot.target?.kind;
+    const sourceKind = snapshot.target?.kind;
 
     const pullRequestUrl = snapshot.origin?.pullRequestUrl;
 

package/src/server/headless-host.ts

@@ -221,8 +221,6 @@ async function serve(input: HeadlessServerInput) {
     token: discovery.token,
     instanceId: discovery.instanceId,
     softwareMapEnabled: input.softwareMapEnabled,
-    // The scratchpad is the laptop's alone, even with a Desktop attached.
-    scratchpad: () => false,
     status: () => ({ key: "headless", home: input.stateDir }),
     ask: {
       tools: cliAskTools(() => (existsSync(cliPath) ? cliPath : undefined), {

package/src/server/hono-http.ts

@@ -7,6 +7,7 @@ import {
   parseJsonText,
 } from "@dev.fast/review-protocol";
 import { type HttpBindings, getRequestListener } from "@hono/node-server";
+import { REVIEW_PERSON_HEADER } from "@review/review-api/request-origin";
 import { REVIEW_APP_SESSION_ID_HEADER } from "@review/ui-telemetry-events";
 import type { Hono } from "hono";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
@@ -73,7 +74,7 @@ export function applyCorsHeaders(
 
   response.headers.set(
     "access-control-allow-headers",
-    `content-type, x-review-token, ${REVIEW_APP_SESSION_ID_HEADER}`,
+    `content-type, x-review-token, ${REVIEW_PERSON_HEADER}, ${REVIEW_APP_SESSION_ID_HEADER}`,
   );
   response.headers.set(
     "access-control-allow-methods",

package/src/server/legacy-tutorial-cleanup.ts

@@ -13,14 +13,13 @@ import { devReviewHome } from "@review/review-home-paths";
  */
 export async function removeLegacyTutorial(input: {
   store: ReviewStore;
-  data: LocalReviewData;
+  data: Pick<LocalReviewData, "forgetRepository">;
   root?: string;
 }): Promise<void> {
   const tutorialRoot = input.root ?? path.join(devReviewHome(), "tutorial");
 
   try {
-    for (const reviewId of input.store.legacyTutorialIds())
-      await input.store.execute({ operation: { type: "delete", reviewId } });
+    await input.store.removeLegacyTutorials();
 
     for (const repository of input.store.repositories()) {
       const relative = path.relative(tutorialRoot, repository.path);

package/src/server/review-gateway-list.ts

@@ -32,11 +32,9 @@ function decorate(
 
   return {
     ...entry,
-    ...(entry.repositoryGroup && {
-      repositoryGroup: {
-        key: `${alias}:${entry.repositoryGroup.key}`,
-        label: entry.repositoryGroup.label,
-      },
+    // A project on another machine is that machine's.
+    ...(entry.project && {
+      project: { id: `${alias}:${entry.project.id}`, name: entry.project.name },
     }),
     host: alias,
     hostState,

package/src/server/review-gateway-memory.ts

@@ -16,7 +16,7 @@ const listEntrySchema = z.looseObject({
   repositoryName: z.string(),
   viewedAt: z.string().nullable(),
   trashedAt: z.string().nullable(),
-  repositoryGroup: z.object({ key: z.string(), label: z.string() }).optional(),
+  project: z.object({ id: z.string(), name: z.string() }).optional(),
 });
 
 export const listEntriesSchema = z.array(z.unknown()).transform(

package/src/server/review-lifecycle-telemetry.ts

@@ -34,12 +34,12 @@ export function reviewLifecycleTelemetry(
     );
 
   return {
-    onReviewCreated: ({ reviewId, kind, blocks, via, agentKind }) => {
+    onReviewCreated: ({ reviewId, blocks, via, agentKind }) => {
       if (reported.has(reviewId)) return;
       reported.add(reviewId);
 
       if (via === "api" || via === "mcp") authoring.set(reviewId, agentKind);
-      const properties: PostHogCaptureProperties = { kind, blocks, via };
+      const properties: PostHogCaptureProperties = { blocks, via };
 
       if (agentKind) properties.agent_kind = agentKind;
       capture("review_review_created", properties, reviewId);

package/src/server/review-server-core.ts

@@ -132,7 +132,6 @@ export interface WhiteboardCoreInput {
   token: string;
   instanceId: string;
   softwareMapEnabled?: boolean;
-  scratchpad: () => boolean;
   status: () => JsonObject;
   hooks?: ReviewApiHooks;
   ask?: {
@@ -192,7 +191,6 @@ export function createWhiteboardCore(input: WhiteboardCoreInput) {
     callbacks.open,
     shared,
     callbacks.capabilities,
-    input.scratchpad,
     () => traceMachineEnabled(),
     input.status,
     input.hooks,
@@ -236,9 +234,7 @@ export function relayReviewCallbacks(
 
       return z.object({ softwareMapEnabled: z.boolean() }).parse(result.result);
     },
-    async capabilities(): Promise<
-      Omit<AuthoringCapabilities, "scratchpadEnabled">
-    > {
+    async capabilities(): Promise<AuthoringCapabilities> {
       if (!relay.attached)
         return { desktopAvailable: false, softwareMapEnabled };
 

package/src/server/structural-comparisons.ts

@@ -1,3 +1,8 @@
+import { stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import { git, gitCommonDir } from "@dev.fast/local-vcs";
 import type { StructuralDiffEvent } from "@dev.fast/review-protocol";
 
 import {
@@ -18,6 +23,7 @@ export class StructuralComparisons {
 
     const key = JSON.stringify([
       configGeneration,
+      await classificationStamp(input.repositoryPath),
       input.repositoryPath,
       input.comparison,
       input.paths,
@@ -66,6 +72,47 @@ export class StructuralComparisons {
 
 let configGeneration = 0;
 
+const classificationFiles = new Map<string, Promise<string[]>>();
+
+/** Git attribute and diffr config files that diffr's classifier reads. */
+function classificationInputs(root: string): Promise<string[]> {
+  let files = classificationFiles.get(root);
+
+  if (!files) {
+    const config =
+      process.env.XDG_CONFIG_HOME || path.join(homedir(), ".config");
+
+    const diffrDirectory =
+      process.env.DIFFR_CONFIG_DIR || path.join(config, "diffr");
+
+    files = Promise.all([
+      gitCommonDir(root),
+      git(root, ["config", "--path", "core.attributesFile"], {
+        allowFailure: true,
+      }),
+    ]).then(([common, user]) => [
+      ...(common ? [path.join(common, "info", "attributes")] : []),
+      path.join(root, ".gitattributes"),
+      user.stdout.trim() || path.join(config, "git", "attributes"),
+      path.join(diffrDirectory, "config.toml"),
+    ]);
+    classificationFiles.set(root, files);
+  }
+
+  return files;
+}
+
+async function classificationStamp(root: string) {
+  return Promise.all(
+    (await classificationInputs(root)).map((file) =>
+      stat(file).then(
+        ({ mtimeMs, size }) => [mtimeMs, size],
+        () => null,
+      ),
+    ),
+  );
+}
+
 export function invalidateStructuralComparisons(): void {
   configGeneration++;
 }

package/src/sharing/export.ts

@@ -14,10 +14,11 @@ import { lensSelections } from "@review/review-api/diff-lenses.js";
 import { ReviewInputError } from "@review/review-api/document.js";
 import {
   anchorPins,
+  boardRepositoryId,
   checkReferences,
   documentSchema,
   elements,
-  hasCodeReferences,
+  readsAtBoardPins,
   resourceReference,
   resourceReferences,
   sourceReferences,
@@ -46,13 +47,33 @@ export function digestBytes(bytes: Uint8Array): string {
 export function validateShareSources(
   snapshot: Pick<Snapshot, "pins" | "document" | "lenses">,
 ) {
-  if (!snapshot.pins && hasCodeReferences(snapshot))
+  if (!snapshot.pins && readsAtBoardPins(snapshot))
     throw new ReviewInputError(
       "Reviews with code references need source pins before sharing.",
       409,
     );
 }
 
+/** The commits a board's references read at besides its base and head. A
+ * recipient fetches them too. A shared board names no repository of its
+ * own, so one stands in for its commit links. */
+export function referenceCommits(
+  snapshot: Pick<Snapshot, "pins" | "document" | "target">,
+  repositoryId = boardRepositoryId(snapshot) ?? "shared",
+): string[] {
+  const own = new Set([snapshot.pins?.base, snapshot.pins?.head]);
+  const commits = new Set<string>();
+
+  for (const { source } of sourceReferences(snapshot.document, {
+    tolerant: true,
+    repositoryId,
+  }))
+    for (const commit of [source.pins?.base, source.pins?.head])
+      if (commit && !own.has(commit)) commits.add(commit);
+
+  return [...commits].sort();
+}
+
 /** Freeze one stored version before any asynchronous source reads. */
 export async function exportShare(input: {
   store: ShareExportStore;
@@ -61,16 +82,24 @@ export async function exportShare(input: {
   version?: number;
   repository?: ShareManifest["repository"];
 }): Promise<ShareBundle> {
-  // A share is the finished document: what edit last touched it stays home.
+  const stored = structuredClone(
+    input.store.read(input.reviewId, input.version),
+  );
+
+  // Commit links read from the board's repository, which a plan names only
+  // in its target.
+  const repositoryId = boardRepositoryId(stored);
+
+  // Local-only fields stay home; the target names a local checkout.
   const {
     target,
-    kind: _kind,
     staleSources: _staleSources,
     sourceUnavailable: _sourceUnavailable,
     lastEdit: _lastEdit,
     trashedAt: _trashedAt,
+    personEdit: _personEdit,
     ...snapshot
-  } = structuredClone(input.store.read(input.reviewId, input.version));
+  } = stored;
 
   if (target?.kind === "worktree")
     throw new ReviewInputError("Pin this review to commits before sharing it.");
@@ -102,7 +131,7 @@ export async function exportShare(input: {
 
   // Lens ranges travel with the snapshot and must resolve at its pins too.
   const sources = [
-    ...sourceReferences(snapshot.document),
+    ...sourceReferences(snapshot.document, { repositoryId }),
     ...lensSelections(snapshot.lenses ?? []).flatMap((selection) =>
       sourceAnchors(selection.source).map((source) => ({
         ...selection,
@@ -116,7 +145,7 @@ export async function exportShare(input: {
 
   validateShareSources(snapshot);
 
-  if (Boolean(pins) !== Boolean(input.repository))
+  if ((pins || referenceCommits(stored).length) && !input.repository)
     throw new ReviewInputError("Shared source pins require a repository.", 409);
 
   for (const block of elements(snapshot.document)) {