@dev.fast/whiteboard 0.0.0-stage → 0.2.0

package/src/review-head-checkout.ts

@@ -0,0 +1,300 @@
+import { existsSync, realpathSync, rmSync } from "node:fs";
+import { lstat, mkdir, readdir, rm } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  git,
+  gitCommonDir,
+  jjRevisionIsConflicted,
+  resolveRevision,
+} from "@dev.fast/local-vcs";
+import { errorMessage, withFileLock } from "@dev.fast/trace-core";
+
+import {
+  type ReviewCheckoutRole,
+  reviewManagedCheckoutDir,
+  reviewManagedCheckoutRoot,
+  reviewManagedCheckoutsDir,
+} from "./review-checkout-paths";
+import { removeReviewPrepareArtifacts } from "./review-prepare.js";
+
+// A review renders the pinned code on the canvas, but file reads against the
+// user's working tree see whatever is checked out there — including edits
+// made after the pin. Materialize any pinned commit (the head, the base) as a
+// detached, reusable git worktree beside the other dev-fast state in the
+// shared git dir so review sessions and graph builds read immutable bytes,
+// even when the working copy currently sits at the pinned commit. Returns the
+// checkout path, or null when the ref cannot be resolved to a commit or the
+// repo has no shared git dir.
+export async function ensureReviewPinnedCheckout(input: {
+  rootPath: string;
+  ref: string;
+  reviewUuid: string;
+  role?: ReviewCheckoutRole;
+}): Promise<string | null> {
+  const target = await resolveReviewPinnedCheckout({
+    ...input,
+    role: input.role ?? "head",
+  });
+
+  if (!target) return null;
+
+  const prepared = await withFileLock(
+    `${target.checkoutPath}.prepare-lock`,
+    {
+      retryMs: 20,
+      timeoutMs: 30_000,
+      staleMs: 120_000,
+      heartbeatMs: 5_000,
+      unownedGraceMs: 1_000,
+    },
+    () =>
+      materializeReviewPinnedCheckout({ rootPath: input.rootPath, ...target }),
+  );
+
+  if (!prepared.acquired)
+    throw new Error(
+      `Pinned checkout ${target.commit} is busy; retry the operation.`,
+    );
+
+  return target.checkoutPath;
+}
+
+async function resolveReviewPinnedCheckout(input: {
+  rootPath: string;
+  ref: string;
+  reviewUuid: string;
+  role: ReviewCheckoutRole;
+}): Promise<{ checkoutPath: string; commit: string } | null> {
+  const commit = await resolveReviewPinnedCommit(input.rootPath, input.ref);
+
+  if (!commit) return null;
+  const commonDir = await gitCommonDir(input.rootPath);
+
+  if (!commonDir) return null;
+
+  return {
+    checkoutPath: reviewManagedCheckoutDir(
+      commonDir,
+      input.reviewUuid,
+      input.role ?? "head",
+      commit,
+    ),
+    commit,
+  };
+}
+
+async function materializeReviewPinnedCheckout(input: {
+  rootPath: string;
+  checkoutPath: string;
+  commit: string;
+}): Promise<void> {
+  const { checkoutPath } = input;
+
+  if (await isWorktreeAt(input.rootPath, checkoutPath, input.commit)) {
+    return;
+  }
+
+  // jj materializes conflict markers into the git export of a conflicted
+  // revision, so a checkout of it would silently contain marker text instead
+  // of code — and the graph would index that. Refuse with the remedy instead.
+  if (await jjRevisionIsConflicted(input.rootPath, input.commit)) {
+    throw new Error(
+      `Whiteboard cannot pin conflicted revision ${input.commit.slice(0, 12)}: the jj change has unresolved conflicts. Resolve them (jj resolve), then re-pin the review.`,
+    );
+  }
+
+  // A stale registration (e.g. a manually gutted or deleted directory) blocks
+  // re-adding the same path: drop both the registration and any leftover
+  // directory before recreating the worktree.
+  await git(input.rootPath, ["worktree", "remove", "--force", checkoutPath], {
+    allowFailure: true,
+  });
+  await git(input.rootPath, ["worktree", "prune"], { allowFailure: true });
+  rmSync(checkoutPath, { recursive: true, force: true });
+  await removeReviewPrepareArtifacts(checkoutPath);
+  await mkdir(path.dirname(checkoutPath), { recursive: true });
+  await git(input.rootPath, [
+    "worktree",
+    "add",
+    "--detach",
+    checkoutPath,
+    input.commit,
+  ]);
+}
+
+/**
+ * Remove every checkout one Review owns in a repository. Registrations go
+ * first, so an interrupted removal cannot leave a gutted tree that git still
+ * lists and a later ensure would reuse; an unregistered leftover is replaced
+ * by the next ensure. Each checkout is removed on its own, so one that cannot
+ * be deleted leaves the others removed; the error names every failure.
+ */
+export async function removeReviewManagedCheckouts(
+  commonDir: string,
+  reviewUuid: string,
+): Promise<void> {
+  const root = reviewManagedCheckoutRoot(commonDir, reviewUuid);
+
+  if (!isInsideDirectory(root, reviewManagedCheckoutsDir(commonDir)))
+    throw new Error(`Refusing to remove non-managed checkouts at ${root}.`);
+
+  // Resolve symlinks above the root (say /tmp) only; never the root itself.
+  const roots = [
+    root,
+    path.join(realPath(path.dirname(root)), path.basename(root)),
+  ];
+
+  const errors: string[] = [];
+  // A checkout git refused to remove (say, locked) stays registered and whole.
+  const kept = new Set<string>();
+
+  const attempt = (work: Promise<unknown>) =>
+    work.then(
+      () => true,
+      (error) => {
+        errors.push(errorMessage(error));
+
+        return false;
+      },
+    );
+
+  for (const worktree of await listRegisteredWorktrees(commonDir))
+    if (
+      roots.some((dir) => isInsideDirectory(worktree.worktreePath, dir)) &&
+      !(await attempt(
+        git(commonDir, [
+          "worktree",
+          "remove",
+          "--force",
+          worktree.worktreePath,
+        ]),
+      ))
+    )
+      kept.add(realPath(worktree.worktreePath));
+
+  // Descend only into real directories. rm removes a symlink itself, never
+  // what it points to, so nothing outside the root is touched.
+  const entries = async (dir: string) =>
+    (await lstat(dir).catch(() => null))?.isDirectory()
+      ? await readdir(dir, { withFileTypes: true })
+      : [];
+
+  for (const entry of await entries(root)) {
+    const dir = path.join(root, entry.name);
+
+    // base/<commit> and head/<commit> are checkouts; anything else (the
+    // navigator workspaces) goes whole.
+    const checkouts =
+      entry.isDirectory() && (entry.name === "base" || entry.name === "head")
+        ? (await entries(dir)).map((child) => path.join(dir, child.name))
+        : [dir];
+
+    for (const checkout of checkouts)
+      if (
+        !kept.has(
+          path.join(realPath(path.dirname(checkout)), path.basename(checkout)),
+        )
+      )
+        await attempt(rm(checkout, { recursive: true, force: true }));
+  }
+
+  if (!errors.length) await rm(root, { recursive: true, force: true });
+  await git(commonDir, ["worktree", "prune"], { allowFailure: true });
+
+  if (errors.length) throw new Error(errors.join("\n"));
+}
+
+// Resolve a pinned ref to a commit. Prefer the jj-first local-vcs
+// resolution (worktree-aware for HEAD/@ and branch names); fall back to git
+// against the shared git dir for refs only the backing store knows, like the
+// pinned refs/dev-fast/reviews/pr-N/head in a non-colocated jj workspace.
+async function resolveReviewPinnedCommit(
+  rootPath: string,
+  ref: string,
+): Promise<string | null> {
+  const resolved = await resolveRevision(rootPath, ref).catch(() => null);
+
+  if (resolved) return resolved.commit;
+
+  const fromGitDir = await git(
+    rootPath,
+    ["rev-parse", "--verify", `${ref}^{commit}`],
+    { allowFailure: true },
+  ).catch(() => null);
+
+  if (!fromGitDir?.ok) return null;
+
+  return fromGitDir.stdout.trim() || null;
+}
+
+// A checkout is reusable only when git still registers a worktree at that
+// path, its HEAD is the wanted commit, and the directory has not been gutted
+// on disk (its .git link is the marker git itself relies on).
+async function isWorktreeAt(
+  rootPath: string,
+  checkoutPath: string,
+  commit: string,
+): Promise<boolean> {
+  if (!existsSync(path.join(checkoutPath, ".git"))) return false;
+
+  const list = await git(rootPath, ["worktree", "list", "--porcelain"], {
+    allowFailure: true,
+  }).catch(() => null);
+
+  if (!list?.ok) return false;
+
+  return parseWorktreeList(list.stdout).some(
+    (entry) =>
+      path.resolve(entry.worktreePath) === path.resolve(checkoutPath) &&
+      entry.headCommit === commit,
+  );
+}
+
+function parseWorktreeList(
+  output: string,
+): Array<{ worktreePath: string; headCommit: string | null }> {
+  const entries: Array<{ worktreePath: string; headCommit: string | null }> =
+    [];
+
+  for (const block of output.split(/\n\n+/)) {
+    let worktreePath: string | null = null;
+    let headCommit: string | null = null;
+
+    for (const line of block.split("\n")) {
+      if (line.startsWith("worktree ")) {
+        worktreePath = line.slice("worktree ".length);
+      } else if (line.startsWith("HEAD ")) {
+        headCommit = line.slice("HEAD ".length);
+      }
+    }
+
+    if (worktreePath) entries.push({ worktreePath, headCommit });
+  }
+
+  return entries;
+}
+
+async function listRegisteredWorktrees(
+  rootPath: string,
+): Promise<Array<{ worktreePath: string; headCommit: string | null }>> {
+  const listed = await git(rootPath, ["worktree", "list", "--porcelain"], {
+    allowFailure: true,
+  }).catch(() => null);
+
+  return listed?.ok ? parseWorktreeList(listed.stdout) : [];
+}
+
+function realPath(filePath: string): string {
+  return existsSync(filePath) ? realpathSync(filePath) : path.resolve(filePath);
+}
+
+function isInsideDirectory(filePath: string, directory: string): boolean {
+  const relative = path.relative(directory, filePath);
+
+  return (
+    Boolean(relative) &&
+    !relative.startsWith("..") &&
+    !path.isAbsolute(relative)
+  );
+}

package/src/review-home-paths.ts

@@ -0,0 +1,73 @@
+import crypto from "node:crypto";
+import path from "node:path";
+
+import { devReviewHome } from "@dev.fast/trace-core";
+
+export { DEV_REVIEW_HOME_ENV, devReviewHome } from "@dev.fast/trace-core";
+
+/** Return the repository-specific storage root under the shared Review home. */
+export function reviewRepoStorageRoot(rootPath: string): string {
+  return path.join(devReviewHome(), "repos", hashedSegment(rootPath, "repo"));
+}
+
+/** `<basename>-<12 hex>` of a resolved path, one safe storage segment. */
+function hashedSegment(target: string, fallback: string): string {
+  const resolved = path.resolve(target);
+  const basename = safeStorageSegment(path.basename(resolved) || fallback);
+
+  const hash = crypto
+    .createHash("sha256")
+    .update(resolved)
+    .digest("hex")
+    .slice(0, 12);
+
+  return `${basename}-${hash}`;
+}
+
+/** Encode a value as one filesystem-safe storage path segment. */
+export function safeStorageSegment(value: string): string {
+  return value.replace(/[^A-Za-z0-9_.-]+/g, "__");
+}
+
+export function reviewDesktopRoot(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return path.join(devReviewHome(env), "review-desktop");
+}
+
+/** Written by Desktops that predate instance selection. */
+export function reviewLegacyDiscoveryPath(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return path.join(reviewDesktopRoot(env), "server.json");
+}
+
+export function reviewInstancesDir(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return path.join(reviewDesktopRoot(env), "instances");
+}
+
+export function reviewInstanceDiscoveryPath(
+  key: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return path.join(reviewInstancesDir(env), `${key}.json`);
+}
+
+export function reviewDefaultInstancePath(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return path.join(reviewDesktopRoot(env), "default-instance");
+}
+
+/** `dev-<name>-<hash>` for a source checkout, keyed like reviewRepoStorageRoot. */
+export function reviewDevInstanceKey(checkout: string): string {
+  return `dev-${hashedSegment(checkout, "checkout")}`;
+}
+
+export function reviewDesktopStateDir(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return path.join(reviewDesktopRoot(env), "state");
+}

package/src/review-info.ts

@@ -0,0 +1,59 @@
+import {
+  ReviewApiClient,
+  type ReviewApiSummary,
+} from "@dev.fast/review-protocol";
+
+import { requireHealthyReviewDesktop } from "./desktop-discovery";
+import { resolveReviewRoot } from "./runtime";
+
+export interface RunReviewInfoInput {
+  cwd: string;
+  all?: boolean;
+  reviewUuid?: string;
+}
+
+export interface ReviewInfoEvent {
+  event: "info";
+  reviews: ReviewApiSummary[];
+}
+
+export async function runReviewInfo(
+  input: RunReviewInfoInput,
+  runtime = { requireHealthyReviewDesktop, resolveReviewRoot },
+): Promise<ReviewInfoEvent> {
+  if (input.all && input.reviewUuid)
+    throw new Error("Review info cannot combine all and reviewUuid.");
+  const discovery = await runtime.requireHealthyReviewDesktop();
+
+  const client = new ReviewApiClient({
+    serverUrl: discovery.url,
+    token: discovery.token,
+  });
+
+  // The API is mounted at "/reviews-api" and Hono matches strictly; "" is the
+  // catalog route and "/" is a 404.
+  const reviews = await client.read<ReviewApiSummary[]>("");
+
+  if (input.reviewUuid) {
+    const selected = reviews.find(
+      (review) => review.reviewId === input.reviewUuid,
+    );
+
+    if (!selected)
+      throw new Error(
+        `Review not found: ${input.reviewUuid}. If this is an old Whiteboard review, ask your agent to migrate your old Whiteboard reviews.`,
+      );
+
+    return { event: "info", reviews: [selected] };
+  }
+
+  const root = await runtime.resolveReviewRoot(input.cwd);
+
+  return {
+    event: "info",
+    reviews: reviews.filter(
+      (review) =>
+        review.repositoryPath === root && (input.all || !review.dismissedAt),
+    ),
+  };
+}

package/src/review-instances.ts

@@ -0,0 +1,113 @@
+import type { Writable } from "node:stream";
+
+import {
+  REVIEW_INSTANCE_ENV,
+  clearDefaultReviewInstance,
+  readDefaultReviewInstance,
+  selectReviewInstance,
+  writeDefaultReviewInstance,
+} from "./desktop-discovery";
+
+interface ReviewInstancesInput {
+  env: NodeJS.ProcessEnv;
+  stdout: Writable;
+  stderr: Writable;
+  json?: boolean;
+}
+
+export async function listReviewInstancesCommand(input: ReviewInstancesInput) {
+  const selection = await selectReviewInstance({
+    env: input.env,
+    warn: (message) => input.stderr.write(`${message}\n`),
+  });
+
+  const defaultKey = await readDefaultReviewInstance(input.env);
+
+  const rows = selection.instances.map(({ key, discovery, healthy }) => ({
+    key,
+    channel: discovery.channel ?? null,
+    state: healthy ? "running" : "stopped",
+    version: discovery.appVersion ?? null,
+    url: discovery.url,
+    checkout: discovery.checkout ?? null,
+    selected: key === selection.key,
+    default: key === defaultKey,
+  }));
+
+  if (input.json) {
+    input.stdout.write(
+      `${JSON.stringify({ event: "instances", selected: selection.key, selectedBy: selection.source, default: defaultKey ?? null, problem: selection.problem?.message ?? null, instances: rows })}\n`,
+    );
+
+    return;
+  }
+
+  const table = [
+    ["", "KEY", "CHANNEL", "STATE", "VERSION", "URL", "CHECKOUT"],
+    ...rows.map((row) => [
+      row.selected ? "*" : "",
+      row.key,
+      row.channel ?? "",
+      row.state,
+      row.version ?? "",
+      row.url,
+      row.checkout ?? "",
+    ]),
+  ];
+
+  const widths = table[0]!.map((_, column) =>
+    Math.max(...table.map((row) => row[column]!.length)),
+  );
+
+  for (const row of table)
+    input.stdout.write(
+      `${row
+        .map((cell, column) => cell.padEnd(widths[column]!))
+        .join("  ")
+        .trimEnd()}\n`,
+    );
+
+  const state = selection.instance
+    ? ""
+    : selection.problem
+      ? ` Its record is unusable: ${selection.problem.message}`
+      : " It has not started on this machine.";
+
+  input.stdout.write(
+    `\nSelected: ${selection.key} (${describeSource(selection.source)}).${state}\n`,
+  );
+}
+
+export async function useReviewInstance(
+  key: string,
+  input: ReviewInstancesInput,
+) {
+  await writeDefaultReviewInstance(key, input.env);
+
+  input.stdout.write(
+    input.json
+      ? `${JSON.stringify({ event: "instances.use", default: key })}\n`
+      : `Default instance: ${key}\nFor this shell only: export ${REVIEW_INSTANCE_ENV}=${key}\n`,
+  );
+}
+
+export async function clearReviewInstance(input: ReviewInstancesInput) {
+  await clearDefaultReviewInstance(input.env);
+
+  input.stdout.write(
+    input.json
+      ? `${JSON.stringify({ event: "instances.clear" })}\n`
+      : "Cleared the default instance.\n",
+  );
+}
+
+function describeSource(
+  source: Awaited<ReturnType<typeof selectReviewInstance>>["source"],
+) {
+  return {
+    env: `from ${REVIEW_INSTANCE_ENV}`,
+    default: "the machine default",
+    "only-running": "the only one running",
+    fallback: "no selection, so stable",
+  }[source];
+}