@dev.fast/whiteboard 0.4.0 → 0.4.1-preview.20261026.138

package/src/review-api/onboarding.ts

@@ -1,6 +1,6 @@
 import { execFile } from "node:child_process";
 import crypto from "node:crypto";
-import { stat } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 
@@ -82,25 +82,54 @@ async function modified(file: string): Promise<number> {
   }
 }
 
+/** The folder holding a bare clone's `.git` file, as in `project/.bare`;
+ * else the clone itself. */
+async function bareRoot(bare: string) {
+  const parent = path.dirname(bare);
+
+  try {
+    const gitdir = /^gitdir:\s*(.+)$/m.exec(
+      await readFile(path.join(parent, ".git"), "utf8"),
+    )?.[1];
+
+    if (gitdir && path.resolve(parent, gitdir.trim()) === bare) return parent;
+  } catch {
+    // No `.git` file beside it.
+  }
+
+  return bare;
+}
+
+/** A folder's project: its main checkout, its bare clone, or itself. */
+async function projectOf(folder: string, run: OnboardingRun) {
+  const git = (args: string[], cwd = folder) =>
+    run("git", args, cwd).then((output) => output.trim());
+
+  const common = path.resolve(
+    folder,
+    await git(["rev-parse", "--path-format=absolute", "--git-common-dir"]),
+  );
+
+  if (path.basename(common) === ".git")
+    return { root: path.dirname(common), common, bare: false };
+
+  if ((await git(["rev-parse", "--is-bare-repository"], common)) === "true")
+    return { root: await bareRoot(common), common, bare: true };
+
+  return {
+    root: await git(["rev-parse", "--show-toplevel"]),
+    common,
+    bare: false,
+  };
+}
+
 /** The repository a folder belongs to, and when it last saw Git activity.
  * Worktrees resolve to their main checkout, which lists them as targets. */
 async function repositoryOf(folder: string, run: OnboardingRun) {
   try {
     if (!(await stat(folder)).isDirectory()) return undefined;
 
-    const common = path.resolve(
-      folder,
-      (
-        await run(
-          "git",
-          ["rev-parse", "--path-format=absolute", "--git-common-dir"],
-          folder,
-        )
-      ).trim(),
-    );
-
-    // A bare repository has no checkout to draw from.
-    if (path.basename(common) !== ".git") return undefined;
+    const { root, common } = await projectOf(folder, run);
 
     const activity = await Promise.all(
       ["index", "FETCH_HEAD", path.join("logs", "HEAD")].map((file) =>
@@ -108,7 +137,7 @@ async function repositoryOf(folder: string, run: OnboardingRun) {
       ),
     );
 
-    return { root: path.dirname(common), active: Math.max(...activity) };
+    return { root, active: Math.max(...activity) };
   } catch {
     return undefined;
   }
@@ -151,6 +180,8 @@ export async function onboardingProjects(
 interface Worktree {
   path: string;
   branch?: string;
+  bare?: true;
+  prunable?: true;
 }
 
 /** `git worktree list --porcelain`: blocks of `worktree`, `HEAD`, `branch`. */
@@ -162,15 +193,40 @@ export function parseWorktrees(output: string): Worktree[] {
     if (line.startsWith("worktree ")) {
       current = { path: line.slice("worktree ".length) };
       worktrees.push(current);
-    } else if (current && line.startsWith("branch "))
+    } else if (!current) continue;
+    else if (line.startsWith("branch "))
       current.branch = line
         .slice("branch ".length)
         .replace(/^refs\/heads\//, "");
+    else if (line === "bare") current.bare = true;
+    else if (line.startsWith("prunable")) current.prunable = true;
   }
 
   return worktrees;
 }
 
+const drawable = (worktree: Worktree) =>
+  !worktree.bare &&
+  !worktree.prunable &&
+  // Whiteboard's own checkouts live under the git dir.
+  !worktree.path.split(/[\\/]/).includes("dev-fast") &&
+  // Scratch checkouts, such as an agent's throwaway worktree.
+  !isInside(TEMPORARY_ROOTS, worktree.path);
+
+/** In a bare clone, a pull request is drawn from the worktree on its branch. */
+async function checkoutOf(project: string, branch: string, run: OnboardingRun) {
+  const worktrees = parseWorktrees(
+    await run("git", ["worktree", "list", "--porcelain"], project).catch(
+      () => "",
+    ),
+  );
+
+  if (!worktrees[0]?.bare) return project;
+  const usable = worktrees.filter(drawable);
+
+  return (usable.find((tree) => tree.branch === branch) ?? usable[0])?.path;
+}
+
 const pullRequestsSchema = z.array(
   z.object({
     number: z.number().int().positive(),
@@ -281,20 +337,31 @@ export async function onboardingTargets(
   run: OnboardingRun = runCommand,
 ): Promise<ReviewOnboardingTargetsResponse> {
   let root: string;
+  let bare = false;
 
   try {
     root = (
       await run("git", ["rev-parse", "--show-toplevel"], directory)
     ).trim();
   } catch {
-    throw new ReviewInputError("Choose a folder inside a Git repository.", 400);
+    const project = await projectOf(directory, run).catch(() => undefined);
+
+    if (!project?.bare)
+      throw new ReviewInputError(
+        "Choose a folder inside a Git repository.",
+        400,
+      );
+    root = project.root;
+    bare = true;
   }
 
   const [branch, worktreeList, base, prs, times] = await Promise.all([
-    run("git", ["branch", "--show-current"], root).then(
-      (output) => output.trim(),
-      () => "",
-    ),
+    bare
+      ? ""
+      : run("git", ["branch", "--show-current"], root).then(
+          (output) => output.trim(),
+          () => "",
+        ),
     run("git", ["worktree", "list", "--porcelain"], root).catch(() => ""),
     defaultBase(root, run),
     pullRequests(root, run),
@@ -311,10 +378,7 @@ export async function onboardingTargets(
       (worktree) =>
         worktree.branch &&
         path.resolve(worktree.path) !== path.resolve(root) &&
-        // Whiteboard's own checkouts live under the git dir.
-        !worktree.path.split(/[\\/]/).includes("dev-fast") &&
-        // Scratch checkouts, such as an agent's throwaway worktree.
-        !isInside(TEMPORARY_ROOTS, worktree.path),
+        drawable(worktree),
     )
     .map((worktree) =>
       local({
@@ -417,7 +481,17 @@ export function registerOnboardingRoutes(
     const { target } = input;
 
     // A pull request is drawn from the project; a branch from its checkout.
-    const cwd = target.kind === "pr" ? input.projectPath : target.path;
+    const cwd =
+      target.kind === "pr"
+        ? await checkoutOf(input.projectPath, target.branch, run)
+        : target.path;
+
+    if (!cwd)
+      throw new ReviewInputError(
+        "This bare clone has no worktrees. Add one with git worktree add.",
+        400,
+      );
+
     let head: string;
 
     try {

package/src/review-preferences.ts

@@ -0,0 +1,43 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { 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.
+ */
+function reviewPreferencesPath(devHome = devReviewHome()): string {
+  return path.join(devHome, "preferences.json");
+}
+
+/** Whether agents are offered animation authoring; existing animations
+ * always render. A missing or unreadable file means off; it never throws. */
+export async function readAnimationsEnabled(
+  devHome?: string,
+): Promise<boolean> {
+  try {
+    const raw = parseJsonText(
+      await readFile(reviewPreferencesPath(devHome), "utf8"),
+    );
+
+    return isJsonObject(raw) && raw.animationsEnabled === true;
+  } catch {
+    return false;
+  }
+}
+
+export async function writeAnimationsEnabled(
+  enabled: boolean,
+  devHome?: string,
+): Promise<boolean> {
+  await writePrivateJsonAtomic(reviewPreferencesPath(devHome), {
+    animationsEnabled: enabled,
+  });
+
+  return enabled;
+}

package/src/server/desktop-server.ts

@@ -46,6 +46,10 @@ import {
   reviewInstanceDiscoveryPath,
   reviewLegacyDiscoveryPath,
 } from "@review/review-home-paths";
+import {
+  readAnimationsEnabled,
+  writeAnimationsEnabled,
+} from "@review/review-preferences";
 import {
   ReviewTelemetry,
   type ReviewTelemetryContext,
@@ -173,6 +177,10 @@ export function createGlobalReviewServer(
   let closing = false;
   const cliPath = path.join(input.packageRoot, "dist", "cli.js");
 
+  // The animations preference, read once at listen and kept current by the
+  // settings endpoint below: this server is the only writer while it runs.
+  let animationsEnabled = false;
+
   const discovery: ReviewDesktopDiscovery = {
     version: REVIEW_DESKTOP_DISCOVERY_VERSION,
     instanceId,
@@ -205,6 +213,7 @@ export function createGlobalReviewServer(
     relay,
     token,
     instanceId,
+    animations: () => animationsEnabled,
     status: () => {
       const { key, channel, checkout, appVersion, cliVersion, instanceId } =
         discovery;
@@ -257,6 +266,20 @@ 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/animations", () =>
+    serverJson(200, { enabled: animationsEnabled }),
+  );
+  app.put("/preferences/animations", 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);
+    animationsEnabled = await writeAnimationsEnabled(request.data.enabled);
+
+    return serverJson(200, { enabled: animationsEnabled });
+  });
   app.post("/app/focus", async () => {
     const result = await relay.dispatch({
       name: "focusWindow",
@@ -499,6 +522,7 @@ export function createGlobalReviewServer(
     },
     listen: async () => {
       await migrateDiffrConfig();
+      animationsEnabled = await readAnimationsEnabled();
       boundPort = await listen(loopback.server, input.port);
       discovery.url = urlForBoundPort();
 

package/src/server/json-review-reporting.ts

@@ -168,7 +168,7 @@ export function createJsonReviewReporting(
                 files: { "review.json": JSON.stringify(snapshot) },
                 omitted: [],
               }),
-              map: async () => JSON.stringify(imported.presentation.maps),
+              map: async () => JSON.stringify(imported.maps),
               diff: () => jsonReviewBugReportSource(store, snapshot).diff(),
             }
           : jsonReviewBugReportSource(store, snapshot),

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

@@ -132,6 +132,7 @@ export interface WhiteboardCoreInput {
   token: string;
   instanceId: string;
   softwareMapEnabled?: boolean;
+  animations?: () => boolean;
   status: () => JsonObject;
   hooks?: ReviewApiHooks;
   ask?: {
@@ -198,6 +199,7 @@ export function createWhiteboardCore(input: WhiteboardCoreInput) {
       threads: askThreads,
       agents: async () => detectAskAgents(await ask?.env),
     },
+    input.animations,
   );
 
   // A shared store mounts the publisher with the rest of sharing.

package/src/server/structural-comparisons.ts

@@ -42,19 +42,16 @@ export class StructuralComparisons {
     } finally {
       entry.readers--;
 
-      if (
-        (!entry.done && !entry.initialReady && !entry.readers) ||
-        entry.error ||
-        entry.failed
-      ) {
+      // Summaries arrive after the files, so a run nobody reads stops. Full
+      // comparisons keep coverage as a reader until diffr completes.
+      if ((!entry.done && !entry.readers) || entry.error || entry.failed) {
         entry.abort.abort();
         this.entries.delete(key);
       }
-      // Keep the most recently read idle comparisons, including background enrichment.
-      // Coverage can finish before an editor subscribes; it must not cancel summaries.
 
+      // Keep the most recently read finished comparisons.
       const idle = [...this.entries].filter(
-        ([, value]) => (value.done || value.initialReady) && !value.readers,
+        ([, value]) => value.done && !value.readers,
       );
 
       for (const [oldKey, old] of idle.slice(0, -IDLE_COMPARISONS)) {
@@ -124,7 +121,6 @@ class Comparison {
   done = false;
   error: unknown;
   failed = false;
-  initialReady = false;
   private remaining: Set<string> | undefined;
   private readonly listeners = new Set<() => void>();
 
@@ -144,13 +140,11 @@ class Comparison {
               (entry) => (entry.file.rhs ?? entry.file.lhs)!.path,
             ),
           );
-          this.initialReady = this.remaining.size === 0;
         } else if (event.type === "file") {
           const path = (event.file.rhs ?? event.file.lhs)!.path;
 
           if (!this.remaining?.delete(path))
             throw new Error(`Unexpected structural result: ${path}`);
-          this.initialReady = this.remaining.size === 0;
         }
 
         if (event.type === "complete")

package/src/server/structural-diff.ts

@@ -61,7 +61,7 @@ export async function* structuralDiff(
       args.push(`${comparison.base}...${comparison.head}`);
   }
 
-  args.push("--", ...(input.paths ?? []));
+  args.push("--defer", "--", ...(input.paths ?? []));
 
   // Plugins can exceed two minutes between records. Apply this timeout only
   // until the manifest arrives; plugins enforce their own request timeouts.
@@ -101,6 +101,7 @@ export async function* structuralDiff(
   let completed = false;
   let aborted: StructuralProblem | undefined;
   let failed = 0;
+  const sent = new Set<string>();
   const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
 
   try {
@@ -131,7 +132,12 @@ export async function* structuralDiff(
 
         failed = event.failed;
         aborted = event.aborted;
-      } else if (event.type !== "file") {
+      } else if (event.type === "file") {
+        sent.add((event.file.rhs ?? event.file.lhs)!.path);
+      } else if (
+        event.type !== "update" ||
+        !sent.has((event.file.rhs ?? event.file.lhs)!.path)
+      ) {
         throw new Error(`Unexpected diffr event: ${event.type}`);
       }
 

package/src/sharing/cli.ts

@@ -43,7 +43,7 @@ export async function runShareCli(input: {
           : z.number().int().nonnegative().parse(Number(input.version));
 
       input.stderr.write(
-        "Sharing includes retained images, maps, and full trace conversations. Anyone with the link can download them. Reviews with code require GitHub repository access to fetch the pinned commits.\n",
+        "Sharing uploads the whiteboard with its maps, full trace conversations, and the code lines it references. Anyone with the link can read them; no GitHub access is needed. Opening it in Whiteboard Desktop also fetches the pinned commits from GitHub.\n",
       );
 
       const result = resultSchema.parse(