@dev.fast/whiteboard 0.3.4-preview.20261019.126 → 0.3.4

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

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

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

@@ -1,7 +1,9 @@
+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, runVcs } from "@dev.fast/local-vcs";
+import { type LocalVcs, gitCommonDir } from "@dev.fast/local-vcs";
 import { isMissingFileError } from "@review/fs-utils.js";
 
 import { checkoutFs } from "./checkout-fs.js";
@@ -9,6 +11,8 @@ 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. */
@@ -45,7 +49,7 @@ export async function workingFiles(vcs: LocalVcs): Promise<string[]> {
       "Working source requires a Git-backed jj repository.",
     );
 
-  const { stdout } = await runVcs(
+  const { stdout } = await exec(
     "git",
     [
       "-C",
@@ -96,7 +100,7 @@ export async function untrackedFileCount(
   if (vcs.kind !== "git") return undefined;
 
   try {
-    const { stdout } = await runVcs(
+    const { stdout } = await exec(
       "git",
       [
         "-C",

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

@@ -318,75 +318,3 @@ 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-preferences.ts

@@ -0,0 +1,88 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  type JsonValue,
+  isJsonObject,
+  parseJsonText,
+} from "@dev.fast/review-protocol";
+import { writePrivateJsonAtomic } from "@dev.fast/trace-core";
+
+import { devReviewHome } from "./review-home-paths";
+
+/**
+ * Machine-wide Review preferences the server itself needs. Workbench settings
+ * do not work here: the review server never reads the workbench
+ * configuration.
+ */
+export interface ReviewPreferences {
+  /**
+   * Whether the scratchpad exists on this machine. Off, the server neither
+   * makes nor lists it and Review's instructions do not offer it to agents.
+   */
+  scratchpadEnabled: boolean;
+}
+
+const DEFAULT_REVIEW_PREFERENCES: ReviewPreferences = {
+  scratchpadEnabled: false,
+};
+
+function reviewPreferencesPath(devHome = devReviewHome()): string {
+  return path.join(devHome, "preferences.json");
+}
+
+/** A missing or unreadable file falls back to the defaults; it never throws. */
+export async function readReviewPreferences(
+  devHome?: string,
+): Promise<ReviewPreferences> {
+  try {
+    const raw = parseJsonText(
+      await readFile(reviewPreferencesPath(devHome), "utf8"),
+    );
+
+    return {
+      scratchpadEnabled: parseScratchpadEnabled(raw),
+    };
+  } catch {
+    return { ...DEFAULT_REVIEW_PREFERENCES };
+  }
+}
+
+export async function writeReviewPreferences(
+  preferences: ReviewPreferences,
+  devHome?: string,
+): Promise<ReviewPreferences> {
+  const next: ReviewPreferences = {
+    scratchpadEnabled: preferences.scratchpadEnabled === true,
+  };
+
+  await writePrivateJsonAtomic(reviewPreferencesPath(devHome), next);
+
+  return next;
+}
+
+/** Reads the scratchpad preference; a missing file means off. */
+export async function readScratchpadEnabled(
+  devHome?: string,
+): Promise<boolean> {
+  return (await readReviewPreferences(devHome)).scratchpadEnabled;
+}
+
+/** Sets the scratchpad preference, keeping the other preferences as they are. */
+export async function writeScratchpadEnabled(
+  enabled: boolean,
+  devHome?: string,
+): Promise<boolean> {
+  const current = await readReviewPreferences(devHome);
+
+  return (
+    await writeReviewPreferences(
+      { ...current, scratchpadEnabled: enabled },
+      devHome,
+    )
+  ).scratchpadEnabled;
+}
+
+function parseScratchpadEnabled(raw: JsonValue): boolean {
+  return isJsonObject(raw) && raw.scratchpadEnabled === true;
+}

package/src/review-stack.ts

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

package/src/runtime.ts

@@ -1,7 +1,6 @@
+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,
@@ -40,9 +39,36 @@ export async function resolveReviewRoot(
 }
 
 function execFilePromise(
-  file: "git" | "jj",
+  file: string,
   args: string[],
   options: { cwd?: string } = {},
 ): Promise<{ stdout: string }> {
-  return runVcs(file, args, options);
+  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}`));
+    });
+  });
 }

package/src/server/desktop-host.ts

@@ -84,8 +84,6 @@ 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
@@ -199,12 +197,9 @@ 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,6 +47,10 @@ import {
   reviewInstanceDiscoveryPath,
   reviewLegacyDiscoveryPath,
 } from "@review/review-home-paths";
+import {
+  readScratchpadEnabled,
+  writeScratchpadEnabled,
+} from "@review/review-preferences";
 import {
   ReviewTelemetry,
   type ReviewTelemetryContext,
@@ -172,6 +176,10 @@ 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,
@@ -204,6 +212,7 @@ export function createGlobalReviewServer(
     relay,
     token,
     instanceId,
+    scratchpad: () => scratchpadEnabled,
     status: () => {
       const { key, channel, checkout, appVersion, cliVersion, instanceId } =
         discovery;
@@ -256,6 +265,25 @@ 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",
@@ -497,6 +525,7 @@ export function createGlobalReviewServer(
         store: reviewStore,
         data: input.reviewData,
       });
+      scratchpadEnabled = await readScratchpadEnabled();
       boundPort = await listen(httpServer, input.port);
       discovery.url = urlForBoundPort();
 
@@ -554,7 +583,8 @@ export function sessionStartedSource(
   try {
     const snapshot = reviewStore.read(reviewUuid);
 
-    const sourceKind = snapshot.target?.kind;
+    const sourceKind =
+      snapshot.kind === "scratchpad" ? snapshot.kind : snapshot.target?.kind;
 
     const pullRequestUrl = snapshot.origin?.pullRequestUrl;
 

package/src/server/headless-host.ts

@@ -221,6 +221,8 @@ 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,7 +7,6 @@ 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";
@@ -74,7 +73,7 @@ export function applyCorsHeaders(
 
   response.headers.set(
     "access-control-allow-headers",
-    `content-type, x-review-token, ${REVIEW_PERSON_HEADER}, ${REVIEW_APP_SESSION_ID_HEADER}`,
+    `content-type, x-review-token, ${REVIEW_APP_SESSION_ID_HEADER}`,
   );
   response.headers.set(
     "access-control-allow-methods",

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

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

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

@@ -32,9 +32,11 @@ function decorate(
 
   return {
     ...entry,
-    // A project on another machine is that machine's.
-    ...(entry.project && {
-      project: { id: `${alias}:${entry.project.id}`, name: entry.project.name },
+    ...(entry.repositoryGroup && {
+      repositoryGroup: {
+        key: `${alias}:${entry.repositoryGroup.key}`,
+        label: entry.repositoryGroup.label,
+      },
     }),
     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(),
-  project: z.object({ id: z.string(), name: z.string() }).optional(),
+  repositoryGroup: z.object({ key: z.string(), label: 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, blocks, via, agentKind }) => {
+    onReviewCreated: ({ reviewId, kind, blocks, via, agentKind }) => {
       if (reported.has(reviewId)) return;
       reported.add(reviewId);
 
       if (via === "api" || via === "mcp") authoring.set(reviewId, agentKind);
-      const properties: PostHogCaptureProperties = { blocks, via };
+      const properties: PostHogCaptureProperties = { kind, blocks, via };
 
       if (agentKind) properties.agent_kind = agentKind;
       capture("review_review_created", properties, reviewId);

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

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

package/src/server/structural-comparisons.ts

@@ -1,8 +1,3 @@
-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 {
@@ -23,7 +18,6 @@ export class StructuralComparisons {
 
     const key = JSON.stringify([
       configGeneration,
-      await classificationStamp(input.repositoryPath),
       input.repositoryPath,
       input.comparison,
       input.paths,
@@ -72,47 +66,6 @@ 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++;
 }