@dev.fast/whiteboard 0.2.5-preview.20261013.113 → 0.2.5-preview.20261015.115

package/src/review-stack.ts

@@ -1,6 +1,7 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
+import { defaultBranch, git } from "@dev.fast/local-vcs";
 import type {
   ReviewApiSummary,
   ReviewStackLayer,
@@ -22,14 +23,71 @@ const GitHubStacksSchema = z.array(
 
 export type RunGitHubApi = (host: string, endpoint: string) => Promise<string>;
 
+type Subject = Pick<ReviewApiSummary, "origin"> & { reviewId?: string };
+
+type Candidate = Pick<
+  ReviewApiSummary,
+  "reviewId" | "title" | "origin" | "pins" | "trashedAt" | "repositoryGroup"
+>;
+
+interface StackEntry {
+  branch: string;
+  pullRequestNumber: number | null;
+  pullRequestUrl: string | null;
+  base: string | null;
+  subject: string | null;
+  current: boolean;
+  reviews: readonly Candidate[];
+}
+
+/** The review's GitHub stack, else the chain of reviews through its base. */
 export async function resolveReviewStackLayers(
-  subject: Pick<ReviewApiSummary, "origin"> & { reviewId?: string },
-  reviews: readonly Pick<
-    ReviewApiSummary,
-    "reviewId" | "title" | "origin" | "pins" | "trashedAt"
-  >[],
-  runGitHubApi: RunGitHubApi = defaultRunGitHubApi,
+  subject: Subject,
+  reviews: readonly Candidate[],
+  options: { runGitHubApi?: RunGitHubApi; repositoryPath?: string } = {},
 ): Promise<ReviewStackLayer[]> {
+  let entries = await gitHubStack(
+    subject,
+    reviews,
+    options.runGitHubApi ?? defaultRunGitHubApi,
+  );
+
+  if (!entries.length && options.repositoryPath)
+    entries = await localStack(subject, reviews, options.repositoryPath);
+
+  const currentIndex = entries.findIndex((entry) => entry.current);
+
+  return entries.map((entry, index) => {
+    const review =
+      entry.reviews.find(
+        (candidate) => candidate.reviewId === subject.reviewId,
+      ) ??
+      entry.reviews.findLast((candidate) => !candidate.trashedAt) ??
+      entry.reviews.at(-1);
+
+    return {
+      branch: entry.branch,
+      pullRequestNumber: entry.pullRequestNumber,
+      pullRequestUrl: entry.pullRequestUrl,
+      base: entry.base,
+      subject: entry.subject,
+      reviewUuid: review?.reviewId ?? null,
+      reviewTitle: review?.title ?? null,
+      relation:
+        index < currentIndex
+          ? "earlier"
+          : index === currentIndex
+            ? "current"
+            : "later",
+    };
+  });
+}
+
+async function gitHubStack(
+  subject: Subject,
+  reviews: readonly Candidate[],
+  runGitHubApi: RunGitHubApi,
+): Promise<StackEntry[]> {
   const binding = subject.origin?.pullRequestUrl?.match(
     /^https:\/\/([a-z0-9.-]+)\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/pull\/([1-9]\d*)$/,
   );
@@ -59,43 +117,111 @@ export async function resolveReviewStackLayers(
     candidate.pull_requests.some((pr) => pr.number === pullRequestNumber),
   );
 
-  if (!stack) return [];
+  return (stack?.pull_requests ?? []).map((pr) => ({
+    branch: pr.head.ref,
+    pullRequestNumber: pr.number,
+    pullRequestUrl: `${repoKey}/pull/${pr.number}`,
+    base: null,
+    subject: null,
+    current: pr.number === pullRequestNumber,
+    reviews: reviews.filter(
+      (candidate) =>
+        (candidate.origin?.pullRequestUrl?.replace(/\/pull\/\d+.*$/, "") ??
+          candidate.pins?.repositoryId) === repoKey &&
+        candidate.origin?.pullRequestNumber === pr.number,
+    ),
+  }));
+}
+
+/** The chain of reviews through this one, linked by the base each names. */
+async function localStack(
+  subject: Subject,
+  reviews: readonly Candidate[],
+  repositoryPath: string,
+): Promise<StackEntry[]> {
+  const group = reviews.find((review) => review.reviewId === subject.reviewId)
+    ?.repositoryGroup?.key;
+
+  const current = subject.origin?.branch;
+
+  if (!group || !current) return [];
+
+  const main = subject.origin?.baseBranch
+    ? await defaultBranch(repositoryPath).catch(() => null)
+    : null;
+
+  const name = (ref: string) => ref.replace(/^origin\//, "");
 
-  const currentIndex = stack.pull_requests.findIndex(
-    (pr) => pr.number === pullRequestNumber,
+  const inGroup = reviews.filter(
+    (review) => review.repositoryGroup?.key === group,
   );
 
-  return stack.pull_requests.map((pr, index) => {
-    const matches = reviews.filter((candidate) => {
-      const repository =
-        candidate.origin?.pullRequestUrl?.replace(/\/pull\/\d+.*$/, "") ??
-        candidate.pins?.repositoryId;
+  const latest = (field: "branch" | "baseBranch", branch: string) => {
+    const matches = inGroup.filter(
+      (review) => review.origin?.[field] === branch,
+    );
 
-      return (
-        repository === repoKey &&
-        candidate.origin?.pullRequestNumber === pr.number
-      );
-    });
+    return matches.findLast((review) => !review.trashedAt) ?? matches.at(-1);
+  };
+
+  const branches = [current];
+
+  for (
+    let base = subject.origin?.baseBranch;
+    base && name(base) !== (main && name(main.ref)) && !branches.includes(base);
+    base = latest("branch", base)?.origin?.baseBranch
+  )
+    branches.unshift(base);
+
+  for (
+    let child = latest("baseBranch", current)?.origin?.branch;
+    child && !branches.includes(child);
+    child = latest("baseBranch", child)?.origin?.branch
+  )
+    branches.push(child);
+
+  const bottom = branches[0]!;
+
+  // A base nobody reviewed gets a row; a new review of it starts at its fork.
+  const start =
+    latest("branch", bottom) || !main
+      ? null
+      : await forkPoint(repositoryPath, main.commit, bottom);
+
+  if (!latest("branch", bottom) && !start) branches.shift();
+
+  if (branches.length < 2) return [];
+
+  return branches.map((branch) => ({
+    branch,
+    pullRequestNumber: null,
+    pullRequestUrl: null,
+    base: (branch === bottom && start?.base) || null,
+    subject: (branch === bottom && start?.subject) || null,
+    current: branch === current,
+    reviews: inGroup.filter((review) => review.origin?.branch === branch),
+  }));
+}
 
-    const review =
-      matches.find((candidate) => candidate.reviewId === subject.reviewId) ??
-      matches.findLast((candidate) => !candidate.trashedAt) ??
-      matches.at(-1);
+/** Where a local branch left `main`, and its oldest commit's subject. */
+async function forkPoint(repositoryPath: string, main: string, branch: string) {
+  const ref = `refs/heads/${branch}`;
 
-    return {
-      branch: pr.head.ref,
-      pullRequestNumber: pr.number,
-      pullRequestUrl: `${repoKey}/pull/${pr.number}`,
-      reviewUuid: review?.reviewId ?? null,
-      reviewTitle: review?.title ?? null,
-      relation:
-        index < currentIndex
-          ? "earlier"
-          : index === currentIndex
-            ? "current"
-            : "later",
-    };
+  const fork = await git(repositoryPath, ["merge-base", main, ref], {
+    allowFailure: true,
   });
+
+  if (!fork.ok) return null;
+
+  const base = fork.stdout.trim();
+
+  const log = await git(
+    repositoryPath,
+    ["log", "--reverse", "--format=%s", `${base}..${ref}`],
+    { allowFailure: true },
+  );
+
+  return { base, subject: log.stdout.split("\n")[0] || null };
 }
 
 async function defaultRunGitHubApi(

package/src/server/background-server.ts

@@ -0,0 +1,250 @@
+import { spawn } from "node:child_process";
+import { mkdir, open, readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+
+import { liveLockOwner, processIsAlive } from "@dev.fast/trace-core";
+import {
+  type ReviewInstanceSelection,
+  desktopUsesHome,
+} from "@review/desktop-discovery.js";
+import { findReviewPackageRoot } from "@review/package-paths.js";
+import { desktopApplicationInstalled } from "@review/review-app-launcher.js";
+import {
+  type ReviewServerDiscovery,
+  desktopOwnsHome,
+  headlessServerLockPath,
+  readReviewServerDiscovery,
+  readReviewServerHealth,
+  reviewServerStateDir,
+} from "@review/server-discovery.js";
+
+export interface EnsureBackgroundServerInput {
+  stateDir: string;
+  env?: NodeJS.ProcessEnv;
+  timeoutMs?: number;
+  startedBy?: "cli" | "desktop";
+  args?: readonly string[];
+  cli?: readonly string[];
+}
+
+export function backgroundServerLogPath(stateDir: string) {
+  return path.join(stateDir, "review-server", "server.log");
+}
+
+export async function ensureBackgroundServer(
+  input: EnsureBackgroundServerInput,
+): Promise<{ discovery: ReviewServerDiscovery; started: boolean }> {
+  const stateDir = path.resolve(input.stateDir);
+  const running = await healthyDiscovery(stateDir);
+
+  if (running) return { discovery: running, started: false };
+
+  if (await desktopUsesHome(stateDir, input.env))
+    throw new Error(desktopOwnsHome(stateDir));
+
+  const logPath = backgroundServerLogPath(stateDir);
+  await mkdir(path.dirname(logPath), { recursive: true, mode: 0o700 });
+  const logStart = (await stat(logPath).catch(() => null))?.size ?? 0;
+  const deadline = Date.now() + (input.timeoutMs ?? 15_000);
+  let child = await spawnServer(stateDir, logPath, input);
+  let respawned = false;
+
+  while (Date.now() < deadline) {
+    const discovery = await healthyDiscovery(stateDir);
+
+    if (discovery)
+      return { discovery, started: discovery.serverPid === child.pid };
+
+    if (child.error)
+      throw new Error(
+        `Could not start the Whiteboard server: ${child.error.message}`,
+      );
+
+    if (child.exited && (await headlessServerOwner(stateDir)) === undefined) {
+      if (respawned) break;
+      respawned = true;
+      child = await spawnServer(stateDir, logPath, input);
+    }
+
+    await delay(100);
+  }
+
+  const owner = await headlessServerOwner(stateDir);
+
+  throw new Error(
+    `The Whiteboard server did not become ready${child.exited ? "" : ` within ${Math.round((input.timeoutMs ?? 15_000) / 1_000)} s; process ${child.pid} is still starting`}.${owner !== undefined && owner !== child.pid ? ` Process ${owner} holds its state directory without answering; \`whiteboard server stop\` ends it.` : ""} The end of ${logPath}:\n${await logTail(logPath, logStart)}`,
+  );
+}
+
+export async function ensureServerWithoutDesktop(input: {
+  selection: ReviewInstanceSelection;
+  env: NodeJS.ProcessEnv;
+  desktopInstalled?: () => boolean;
+  cli?: readonly string[];
+}) {
+  const { selection, env } = input;
+
+  if (
+    selection.source !== "fallback" ||
+    selection.instances.length !== 0 ||
+    selection.problem ||
+    (input.desktopInstalled ?? (() => desktopApplicationInstalled({ env })))()
+  )
+    return undefined;
+
+  const { discovery } = await ensureBackgroundServer({
+    stateDir: reviewServerStateDir(env),
+    env,
+    cli: input.cli,
+  });
+
+  return discovery;
+}
+
+export async function headlessServerOwner(stateDir: string) {
+  const resolved = await realpath(stateDir).catch(() => path.resolve(stateDir));
+
+  return liveLockOwner(headlessServerLockPath(resolved));
+}
+
+export async function recordedBackgroundServer(stateDir: string) {
+  const discovery = await readReviewServerDiscovery(stateDir).catch(() => null);
+  const health = discovery && (await readReviewServerHealth(discovery));
+
+  return discovery && health?.serverPid === discovery.serverPid
+    ? { discovery, health }
+    : undefined;
+}
+
+export async function stopBackgroundServer(
+  discovery: Pick<ReviewServerDiscovery, "serverPid">,
+  first: NodeJS.Signals = "SIGTERM",
+) {
+  const { serverPid } = discovery;
+
+  for (const [signal, waitMs] of [
+    [first, 10_000],
+    ["SIGKILL", 2_000],
+  ] as const) {
+    try {
+      process.kill(serverPid, signal);
+    } catch (error) {
+      if (error instanceof Error && "code" in error && error.code === "ESRCH")
+        return;
+      throw error;
+    }
+
+    for (let waited = 0; waited < waitMs; waited += 100) {
+      if (!processIsAlive(serverPid)) return;
+      await delay(100);
+    }
+  }
+
+  throw new Error(`The Whiteboard server (process ${serverPid}) did not stop.`);
+}
+
+interface DetachedChild {
+  pid?: number;
+  exited: boolean;
+  error?: Error;
+}
+
+export async function spawnDetached(input: {
+  command: string;
+  args: readonly string[];
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  log: string;
+}) {
+  const log = await open(input.log, "a", 0o600);
+
+  const child = spawn(input.command, input.args, {
+    cwd: input.cwd,
+    detached: true,
+    env: input.env,
+    stdio: ["ignore", log.fd, log.fd],
+  });
+
+  const state: DetachedChild = { pid: child.pid, exited: false };
+
+  child.once("exit", () => (state.exited = true));
+  child.once("error", (error) => {
+    state.exited = true;
+    state.error = error;
+  });
+  child.unref();
+  await log.close();
+
+  return state;
+}
+
+function spawnServer(
+  stateDir: string,
+  logPath: string,
+  input: EnsureBackgroundServerInput,
+) {
+  const { command, args, env } = cliSpawn(input.cli, input.env ?? process.env);
+
+  return spawnDetached({
+    command,
+    args: [
+      ...args,
+      "server",
+      "start",
+      "--state-dir",
+      stateDir,
+      "--started-by",
+      input.startedBy ?? "cli",
+      ...(input.args ?? []),
+    ],
+    cwd: stateDir,
+    env,
+    log: logPath,
+  });
+}
+
+export function cliSpawn(
+  cli: readonly string[] | undefined,
+  env: NodeJS.ProcessEnv,
+) {
+  const [command, ...args] = cli ?? currentCli();
+
+  return {
+    command: command!,
+    args,
+    // Run from source, tsx finds the path aliases only through this.
+    env:
+      args.at(-1)?.endsWith(".ts") && !env.TSX_TSCONFIG_PATH
+        ? {
+            ...env,
+            TSX_TSCONFIG_PATH: path.join(
+              findReviewPackageRoot(import.meta.url),
+              "tsconfig.json",
+            ),
+          }
+        : env,
+  };
+}
+
+function currentCli() {
+  return [
+    process.execPath,
+    ...process.execArgv,
+    path.resolve(process.argv[1]!),
+  ];
+}
+
+async function healthyDiscovery(stateDir: string) {
+  const discovery = await readReviewServerDiscovery(stateDir).catch(() => null);
+
+  return discovery && (await readReviewServerHealth(discovery))
+    ? discovery
+    : null;
+}
+
+async function logTail(logPath: string, from: number) {
+  const text = (await readFile(logPath)).subarray(from).toString("utf8");
+
+  return text.trimEnd().split("\n").slice(-20).join("\n");
+}

package/src/server/desktop-host-shutdown.ts

@@ -1,5 +1,7 @@
 import {
   type JsonValue,
+  type ReviewGatewayHost,
+  ReviewGatewayHostSchema,
   isJsonObject,
   jsonBoolean,
   jsonProperty,
@@ -9,12 +11,23 @@ import {
 interface DesktopHostMessagePort {
   on(event: "message", listener: (event: { data: JsonValue }) => void): void;
   off(event: "message", listener: (event: { data: JsonValue }) => void): void;
+  postMessage?(message: JsonValue): void;
 }
 
 interface DesktopHostProcess {
   parentPort?: DesktopHostMessagePort;
   on(event: "message", listener: (message: JsonValue) => void): void;
   off(event: "message", listener: (message: JsonValue) => void): void;
+  send?(message: JsonValue): void;
+}
+
+export function postToDesktop(
+  hostProcess: DesktopHostProcess,
+  message: JsonValue,
+): void {
+  if (hostProcess.parentPort?.postMessage)
+    hostProcess.parentPort.postMessage(message);
+  else hostProcess.send?.(message);
 }
 
 export function listenForDesktopHostShutdown(
@@ -22,6 +35,7 @@ export function listenForDesktopHostShutdown(
   onShutdown: () => void,
   onTelemetrySetting?: (enabled: boolean) => void,
   onStageRustAnalyzer?: (path: string) => void,
+  onRemoteHosts?: (hosts: ReviewGatewayHost[]) => void,
 ): () => void {
   const handleMessage = (message: JsonValue) => {
     if (!isJsonObject(message)) return;
@@ -45,6 +59,16 @@ export function listenForDesktopHostShutdown(
       const path = jsonString(jsonProperty(message, "path"));
 
       if (path) onStageRustAnalyzer?.(path);
+
+      return;
+    }
+
+    if (type === "remote-hosts") {
+      const hosts = ReviewGatewayHostSchema.array().safeParse(
+        jsonProperty(message, "hosts"),
+      );
+
+      if (hosts.success) onRemoteHosts?.(hosts.data);
     }
   };
 

package/src/server/desktop-host.ts

@@ -12,8 +12,12 @@ import { ReviewTelemetry } from "@review/review-telemetry";
 import { SharedReviewStore } from "@review/sharing/import.js";
 import { reviewTelemetryChannel } from "@review/telemetry-config";
 
-import { listenForDesktopHostShutdown } from "./desktop-host-shutdown";
+import {
+  listenForDesktopHostShutdown,
+  postToDesktop,
+} from "./desktop-host-shutdown";
 import { createGlobalReviewServer } from "./desktop-server";
+import { takeOverServerHome } from "./headless-host";
 import {
   drainServerCrashReport,
   installProcessErrorTelemetry,
@@ -74,34 +78,44 @@ export async function runDesktopHost(
   const home = devReviewHome(env);
   await mkdir(home, { recursive: true });
 
-  const local = await openReviewProfile(home, {
-    manageWorkspaces: true,
-  });
+  const log = (message: string) =>
+    process.stdout.write(`[Whiteboard gateway] ${message}\n`);
+
+  const { local, shared, server } = await takeOverServerHome(home, async () => {
+    const local = await openReviewProfile(home, {
+      manageWorkspaces: true,
+    });
 
-  // JSON is the sole user-review store. A failure is surfaced, never replaced
-  // by a second catalog or an old document renderer.
+    // JSON is the sole user-review store. A failure is surfaced, never replaced
+    // by a second catalog or an old document renderer.
+
+    const shared = new SharedReviewStore(path.join(home, "shared-reviews"));
+    shared.connect(local.store, local.data);
+    await shared.load();
+
+    const server = createGlobalReviewServer({
+      ...serverInput,
+      log,
+      sharedReviews: shared,
+      reviewStore: local.store,
+      reviewData: local.data,
+      cliRuntimePath: env.DEV_FAST_REVIEW_CLI_RUNTIME,
+      crashDumpsDir: env.DEV_FAST_REVIEW_CRASH_DUMPS_DIR,
+      onRemoteHostRestarted: (alias) =>
+        postToDesktop(process, { type: "remote-host-restarted", alias }),
+    });
 
-  const shared = new SharedReviewStore(path.join(home, "shared-reviews"));
-  shared.connect(local.store, local.data);
-  await shared.load();
+    try {
+      await server.listen();
+    } catch (error) {
+      await local?.data.close();
+      await local?.store.close();
+      throw error;
+    }
 
-  const server = createGlobalReviewServer({
-    ...serverInput,
-    sharedReviews: shared,
-    reviewStore: local.store,
-    reviewData: local.data,
-    cliRuntimePath: env.DEV_FAST_REVIEW_CLI_RUNTIME,
-    crashDumpsDir: env.DEV_FAST_REVIEW_CRASH_DUMPS_DIR,
+    return { local, shared, server };
   });
 
-  try {
-    await server.listen();
-  } catch (error) {
-    await local?.data.close();
-    await local?.store.close();
-    throw error;
-  }
-
   process.stdout.write(
     `${JSON.stringify({ event: "ready", ...server.discovery, installationId })}\n`,
   );
@@ -142,6 +156,7 @@ export async function runDesktopHost(
       env.DEV_FAST_REVIEW_RUST_ANALYZER = sourcePath;
       void stageRustAnalyzer();
     },
+    (hosts) => server.setRemoteHosts(hosts),
   );
   process.once("SIGINT", () => {
     void stop().then(() => process.exit(0));