@dev.fast/whiteboard 0.0.0-stage → 0.2.1-preview.20261005.98

package/src/review-app.ts

@@ -0,0 +1,134 @@
+import type { Writable } from "node:stream";
+
+import {
+  ReviewApiClient,
+  type ReviewApiSummary,
+} from "@dev.fast/review-protocol";
+
+import {
+  type ReviewInstanceSelection,
+  healthyReviewInstance,
+  reviewInstanceUnavailable,
+  selectReviewInstance,
+} from "./desktop-discovery";
+import { focusReviewDesktop, runReviewAppLaunch } from "./review-app-launcher";
+import { pickReview } from "./review-app-picker";
+import { resolveReviewRoot } from "./runtime";
+
+interface ReviewAppRuntime {
+  launch: typeof runReviewAppLaunch;
+  selectInstance: () => Promise<ReviewInstanceSelection>;
+  resolveReviewRoot: typeof resolveReviewRoot;
+  pickReview: typeof pickReview;
+  fetch: typeof globalThis.fetch;
+}
+
+export class ReviewAppUsageError extends Error {
+  readonly name = "ReviewAppUsageError";
+}
+
+export class ReviewAppStateError extends Error {
+  readonly name = "ReviewAppStateError";
+}
+
+export interface RunReviewAppInput {
+  cwd: string;
+  reviewUuid?: string;
+  /** Bring Whiteboard Desktop forward. */
+  focus?: boolean;
+  stdin: NodeJS.ReadStream;
+  stdout: Writable;
+}
+
+export interface ReviewAppEvent {
+  event: "app";
+  action: "pick";
+  reviewUuid: string;
+  title: string;
+  cancelled?: boolean;
+}
+
+export async function runReviewAppPick(
+  input: RunReviewAppInput,
+  overrides: Partial<ReviewAppRuntime> = {},
+): Promise<ReviewAppEvent | null> {
+  const fetch = overrides.fetch ?? globalThis.fetch;
+
+  const runtime = {
+    launch: runReviewAppLaunch,
+    selectInstance: () => selectReviewInstance({ fetch }),
+    resolveReviewRoot,
+    pickReview,
+    fetch,
+    ...overrides,
+  };
+
+  // Only `whiteboard app launch` may recover a stale or incompatible record; the
+  // other verbs report the diagnosis rather than start a second Desktop. No
+  // record at all means nothing is running, which launching does fix.
+  let selection = await runtime.selectInstance();
+  let launched = false;
+
+  if (!selection.instance && !selection.problem) {
+    await runtime.launch({ focus: input.focus });
+    launched = true;
+    selection = await runtime.selectInstance();
+  }
+
+  const discovery = healthyReviewInstance(selection);
+
+  if (!discovery) throw reviewInstanceUnavailable(selection);
+
+  const client = new ReviewApiClient(
+    { serverUrl: discovery.url, token: discovery.token },
+    runtime.fetch,
+  );
+
+  let review: Pick<ReviewApiSummary, "reviewId" | "title">;
+
+  if (input.reviewUuid) {
+    // Without `full`, GET /reviews-api/:id answers inspectSnapshot(): block
+    // descriptors with no reviewId or title.
+    review = await client.read(
+      `/${encodeURIComponent(input.reviewUuid)}?full=true`,
+    );
+  } else {
+    if (!input.stdin.isTTY)
+      throw new ReviewAppUsageError(
+        "whiteboard app pick needs a terminal without --session. Pass --session <uuid> or run it in a terminal.",
+      );
+    const root = await runtime.resolveReviewRoot(input.cwd);
+
+    const reviews = (await client.read<ReviewApiSummary[]>(""))
+      .filter((review) => review.repositoryPath === root && !review.dismissedAt)
+      .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+
+    if (!reviews.length) throw new ReviewAppStateError("No review to show.");
+
+    const picked = await runtime.pickReview(
+      reviews.map((review) => ({
+        uuid: review.reviewId,
+        title: review.title,
+        status: review.viewedAt ? "viewed" : "new",
+        lastPublishedAt: review.createdAt,
+      })),
+      input,
+    );
+
+    if (!picked) return null;
+    review = { reviewId: picked.uuid, title: picked.title };
+  }
+
+  await client.post(`/${encodeURIComponent(review.reviewId)}/open`, {});
+
+  // A focused fresh launch already came forward; a running one must be asked.
+  if (input.focus && !launched)
+    await focusReviewDesktop(discovery, runtime.fetch);
+
+  return {
+    event: "app",
+    action: "pick",
+    reviewUuid: review.reviewId,
+    title: review.title,
+  };
+}

package/src/review-bundled-tools.ts

@@ -0,0 +1,249 @@
+import { createHash, randomBytes } from "node:crypto";
+import fs from "node:fs";
+import {
+  chmod,
+  copyFile,
+  mkdir,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+import { Writable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { setTimeout as delay } from "node:timers/promises";
+
+import { isJsonObject, parseJsonText } from "@dev.fast/review-protocol";
+
+import { devReviewHome } from "./review-home-paths";
+
+interface EnsureBundledToolInput {
+  tool: string;
+  sourcePath?: string;
+  env?: NodeJS.ProcessEnv;
+}
+
+type EnsureBundledToolResult = "staged" | "fresh" | "no-source";
+
+interface ReviewToolIdentity {
+  tool: string;
+  platform: string;
+  sha256: string;
+}
+
+export function reviewToolsRoot(env: NodeJS.ProcessEnv = process.env): string {
+  return path.join(devReviewHome(env), "review-tools");
+}
+
+async function ensureBundledTool(
+  input: EnsureBundledToolInput,
+): Promise<EnsureBundledToolResult> {
+  if (!/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/.test(input.tool)) {
+    throw new Error(`Invalid bundled tool name: ${input.tool}`);
+  }
+
+  const sourcePath = input.sourcePath?.trim();
+
+  if (!sourcePath) return "no-source";
+  const source = path.resolve(sourcePath);
+
+  if (!(await isExecutableFile(source))) return "no-source";
+
+  const env = input.env ?? process.env;
+  const platform = reviewToolPlatform();
+  const executable = stagedToolPath(env, input.tool, platform);
+  const destination = path.dirname(executable);
+  const sha256 = await hashFile(source);
+
+  const identity: ReviewToolIdentity = {
+    tool: input.tool,
+    platform,
+    sha256,
+  };
+
+  if (installedToolMatches(destination, executable, identity)) return "fresh";
+
+  await mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
+
+  return await withInstallLock(destination, async () => {
+    if (installedToolMatches(destination, executable, identity)) return "fresh";
+    const staging = `${destination}.staging-${process.pid}-${randomBytes(6).toString("hex")}`;
+    await rm(staging, { recursive: true, force: true });
+    await mkdir(staging, { recursive: true, mode: 0o700 });
+
+    try {
+      const stagedExecutable = path.join(
+        staging,
+        executableName(input.tool, platform),
+      );
+
+      await copyFile(source, stagedExecutable);
+
+      if ((await hashFile(stagedExecutable)) !== sha256) {
+        throw new Error(
+          `The bundled ${input.tool} source changed while Whiteboard staged it.`,
+        );
+      }
+
+      await chmod(stagedExecutable, 0o755);
+      await writeToolStamp(staging, identity);
+      await rm(destination, { recursive: true, force: true });
+      await rename(staging, destination);
+
+      return "staged";
+    } finally {
+      await rm(staging, { recursive: true, force: true });
+    }
+  });
+}
+
+export async function ensureBundledRustAnalyzer(
+  input: { env?: NodeJS.ProcessEnv } = {},
+): Promise<EnsureBundledToolResult> {
+  const env = input.env ?? process.env;
+
+  return await ensureBundledTool({
+    tool: "rust-analyzer",
+    sourcePath: env.DEV_FAST_REVIEW_RUST_ANALYZER,
+    env,
+  });
+}
+
+export function stagedToolPath(
+  env: NodeJS.ProcessEnv,
+  tool: string,
+  platform = reviewToolPlatform(),
+): string {
+  return path.join(
+    reviewToolsRoot(env),
+    tool,
+    "bundled",
+    platform,
+    executableName(tool, platform),
+  );
+}
+
+async function withInstallLock<T>(
+  destination: string,
+  operation: () => Promise<T>,
+): Promise<T> {
+  const lockPath = `${destination}.install-lock`;
+  const deadline = Date.now() + 120_000;
+
+  while (true) {
+    try {
+      await mkdir(lockPath, { mode: 0o700 });
+      break;
+    } catch (error) {
+      if (
+        !(error instanceof Error && "code" in error && error.code === "EEXIST")
+      ) {
+        throw error;
+      }
+
+      const lockAge = await stat(lockPath)
+        .then((value) => Date.now() - value.mtimeMs)
+        .catch(() => 0);
+
+      if (lockAge > 10 * 60_000) {
+        await rm(lockPath, { recursive: true, force: true });
+        continue;
+      }
+
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `Timed out waiting for another Whiteboard process to install ${path.basename(destination)}.`,
+        );
+      }
+
+      await delay(100);
+    }
+  }
+
+  try {
+    return await operation();
+  } finally {
+    await rm(lockPath, { recursive: true, force: true });
+  }
+}
+
+function installedToolMatches(
+  destination: string,
+  executable: string,
+  identity: ReviewToolIdentity,
+): boolean {
+  if (!isExecutable(executable)) return false;
+
+  try {
+    const stamp = parseJsonText(
+      fs.readFileSync(path.join(destination, "review-tool.json"), "utf8"),
+    );
+
+    return (
+      isJsonObject(stamp) &&
+      stamp.tool === identity.tool &&
+      stamp.platform === identity.platform &&
+      stamp.sha256 === identity.sha256
+    );
+  } catch {
+    return false;
+  }
+}
+
+async function writeToolStamp(
+  destination: string,
+  identity: ReviewToolIdentity,
+): Promise<void> {
+  await writeFile(
+    path.join(destination, "review-tool.json"),
+    `${JSON.stringify(identity, null, 2)}\n`,
+    { encoding: "utf8", mode: 0o600 },
+  );
+}
+
+function reviewToolPlatform(): string {
+  const platform =
+    process.platform === "darwin"
+      ? "darwin"
+      : process.platform === "linux"
+        ? "linux"
+        : process.platform;
+
+  return `${platform}-${process.arch}`;
+}
+
+function executableName(name: string, platform: string): string {
+  return platform.startsWith("win32-") ? `${name}.exe` : name;
+}
+
+function isExecutable(filePath: string): boolean {
+  try {
+    fs.accessSync(filePath, fs.constants.X_OK);
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function isExecutableFile(filePath: string): Promise<boolean> {
+  const metadata = await stat(filePath).catch(() => undefined);
+
+  return Boolean(metadata?.isFile() && isExecutable(filePath));
+}
+
+async function hashFile(filePath: string): Promise<string> {
+  const hash = createHash("sha256");
+  await pipeline(
+    fs.createReadStream(filePath),
+    new Writable({
+      write(chunk: Buffer, _encoding, callback) {
+        hash.update(chunk);
+        callback();
+      },
+    }),
+  );
+
+  return hash.digest("hex");
+}

package/src/review-checkout-paths.ts

@@ -0,0 +1,37 @@
+import path from "node:path";
+
+import { safeStorageSegment } from "./review-home-paths";
+
+export type ReviewCheckoutRole = "head" | "base";
+
+/**
+ * Root for Review-owned checkouts. A Review UUID identifies one subtree.
+ */
+export function reviewManagedCheckoutsDir(gitCommonDir: string): string {
+  return path.join(gitCommonDir, "dev-fast", "reviews");
+}
+
+/** Return the checkout subtree owned by one Review UUID. */
+export function reviewManagedCheckoutRoot(
+  gitCommonDir: string,
+  reviewUuid: string,
+): string {
+  return path.join(
+    reviewManagedCheckoutsDir(gitCommonDir),
+    safeStorageSegment(reviewUuid),
+  );
+}
+
+/** A detached checkout owned by one Review revision and source role. */
+export function reviewManagedCheckoutDir(
+  gitCommonDir: string,
+  reviewUuid: string,
+  role: ReviewCheckoutRole,
+  commit: string,
+): string {
+  return path.join(
+    reviewManagedCheckoutRoot(gitCommonDir, reviewUuid),
+    role,
+    safeStorageSegment(commit),
+  );
+}

package/src/review-diff-files.ts

@@ -0,0 +1,89 @@
+import {
+  diff as readLocalVcsDiff,
+  diffFileSummaries as readLocalVcsDiffFileSummaries,
+  splitGitPatchFiles,
+} from "@dev.fast/local-vcs";
+
+export interface ReviewDiffFile {
+  path: string;
+  previousPath?: string;
+  status: "added" | "modified" | "deleted" | "renamed";
+  additions: number;
+  deletions: number;
+  patch?: string;
+}
+
+export interface ReviewDiffFilesResult {
+  baseRef?: string;
+  headRef?: string;
+  files: ReviewDiffFile[];
+}
+
+export async function resolveReviewDiffFiles(input: {
+  rootPath: string;
+  baseRef?: string;
+  headRef?: string;
+  contextLines?: number;
+  includePatch?: boolean;
+  paths?: string[];
+}): Promise<ReviewDiffFilesResult> {
+  const baseRef = input.baseRef?.trim();
+
+  if (!baseRef) return { files: [] };
+
+  const headRef = input.headRef?.trim() || undefined;
+  const paths = normalizeDiffPaths(input.paths);
+
+  if (input.includePatch === false) {
+    return {
+      baseRef,
+      headRef,
+      files: await readLocalVcsDiffFileSummaries({
+        rootPath: input.rootPath,
+        baseRef,
+        headRef,
+        paths,
+      }),
+    };
+  }
+
+  const stdout = await readLocalVcsDiff({
+    rootPath: input.rootPath,
+    baseRef,
+    headRef,
+    paths,
+    contextLines: input.contextLines,
+  });
+
+  return {
+    baseRef,
+    headRef,
+    files: splitGitPatchFiles(stdout)
+      .map(({ file, patch }) => ({
+        path: file.path,
+        previousPath: file.previousPath,
+        status: file.status,
+        additions: file.additions,
+        deletions: file.deletions,
+        patch,
+      }))
+      .filter((file) => matchesDiffPath(file, paths)),
+  };
+}
+
+function normalizeDiffPaths(paths: string[] | undefined): string[] {
+  return [
+    ...new Set(
+      (paths ?? [])
+        .map((path) => path.trim())
+        .filter((path) => path.length > 0),
+    ),
+  ].sort();
+}
+
+function matchesDiffPath(file: ReviewDiffFile, paths: string[]): boolean {
+  if (paths.length === 0) return true;
+  const candidates = new Set([file.path, file.previousPath].filter(Boolean));
+
+  return paths.some((path) => candidates.has(path));
+}