@dev.fast/whiteboard 0.0.0-stage → 0.2.0

package/src/review-logger.ts

@@ -0,0 +1,183 @@
+import {
+  type JsonValue,
+  isJsonObject,
+  jsonString,
+  parseJsonText,
+} from "@dev.fast/review-protocol";
+import pino from "pino";
+import pretty from "pino-pretty";
+
+export type ReviewLogFormat = "ndjson" | "pretty";
+
+export type ReviewLifecyclePhaseName = "review_document" | "server";
+
+export interface ReviewLifecycleError {
+  name: string;
+  message: string;
+  stack?: string;
+  component?: string;
+  propertyPath?: string;
+  expected?: unknown;
+  received?: unknown;
+}
+
+export type ReviewLifecycleEvent =
+  | {
+      event: "start";
+      cliPath: string;
+      cliName: string;
+      cliVersion: string;
+      provenance: "workspace" | "installed";
+      source: string;
+      args: string[];
+      base: string;
+      head: string;
+      repo?: string;
+      pullRequest?: number;
+    }
+  | {
+      event: "phase";
+      name: ReviewLifecyclePhaseName;
+      status: "running" | "complete";
+    }
+  | {
+      event: "ready";
+      url: string;
+      document: string;
+      headCheckout?: string;
+    }
+  | {
+      event: "diagnostic";
+      level: "info" | "warn" | "error";
+      origin: "review";
+      message: string;
+      error?: ReviewLifecycleError;
+    }
+  | { event: "dismissed"; reason: "canvas_closed" }
+  | {
+      event: "error";
+      error: ReviewLifecycleError;
+    };
+
+// This is the only presentation choice in the Review logging pipeline.
+export const DEFAULT_REVIEW_LOG_FORMAT: ReviewLogFormat = "ndjson";
+
+export interface ReviewLogger {
+  event(event: ReviewLifecycleEvent): void;
+}
+
+export function createReviewLogger(input: {
+  output: NodeJS.WritableStream;
+  format?: ReviewLogFormat;
+  colorize?: boolean;
+}): ReviewLogger {
+  const format = input.format ?? DEFAULT_REVIEW_LOG_FORMAT;
+
+  const destination =
+    format === "pretty"
+      ? pretty({
+          destination: input.output,
+          sync: true,
+          colorize:
+            input.colorize ??
+            ("isTTY" in input.output && Boolean(input.output.isTTY)),
+          translateTime: false,
+          singleLine: true,
+          messageFormat: "{event}",
+          ignore: "pid,hostname,time,event",
+        })
+      : input.output;
+
+  const logger = pino(
+    {
+      base: null,
+      timestamp: false,
+      formatters: {
+        level(label) {
+          return { level: label };
+        },
+      },
+    },
+    destination,
+  );
+
+  return {
+    event(event) {
+      if (event.event === "diagnostic") {
+        const { level, ...record } = event;
+        logger[level](record);
+
+        return;
+      }
+
+      if (event.event === "error") {
+        logger.error(event);
+
+        return;
+      }
+
+      logger.info(event);
+    },
+  };
+}
+
+const defaultLoggers = new WeakMap<NodeJS.WritableStream, ReviewLogger>();
+
+export function emitReviewEvent(
+  output: NodeJS.WritableStream,
+  event: ReviewLifecycleEvent,
+): void {
+  let logger = defaultLoggers.get(output);
+
+  if (!logger) {
+    logger = createReviewLogger({ output });
+    defaultLoggers.set(output, logger);
+  }
+
+  logger.event(event);
+}
+
+export function serializeReviewError(cause: unknown): ReviewLifecycleError {
+  // A thrown object is read as the JSON record it is about to be logged as;
+  // each field the record keeps is decoded on its own below.
+  const fields = isJsonObject(cause) ? cause : undefined;
+  const stack = jsonString(fields?.stack);
+  const component = jsonString(fields?.component);
+  const propertyPath = jsonString(fields?.propertyPath);
+
+  const error: ReviewLifecycleError = {
+    name:
+      cause instanceof Error
+        ? cause.name
+        : (jsonString(fields?.name) ?? "Error"),
+    message:
+      cause instanceof Error
+        ? cause.message
+        : (jsonString(fields?.message) ?? String(cause)),
+  };
+
+  if (stack !== undefined) error.stack = stack;
+
+  if (component !== undefined) error.component = component;
+
+  if (propertyPath !== undefined) error.propertyPath = propertyPath;
+
+  if (fields && "expected" in fields) {
+    error.expected = jsonSafeValue(fields.expected);
+  }
+
+  if (fields && "received" in fields) {
+    error.received = jsonSafeValue(fields.received);
+  }
+
+  return error;
+}
+
+/** Round-trip through JSON so a value that cannot serialize still logs. */
+function jsonSafeValue(value: JsonValue): JsonValue {
+  try {
+    return parseJsonText(JSON.stringify(value));
+  } catch {
+    return String(value);
+  }
+}

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-prepare.ts

@@ -0,0 +1,291 @@
+import { spawn } from "node:child_process";
+import crypto from "node:crypto";
+import { readFile, rm, writeFile } from "node:fs/promises";
+
+import { jsonObject, parseJsonText } from "@dev.fast/review-protocol";
+import { withFileLock } from "@dev.fast/trace-core";
+
+// Dependency preparation for pinned worktrees. The repo owner configures the
+// commands once per clone (`git config devfast.prepare '<command>'`, the key
+// is multi-valued and ordered); Review runs them opaquely with the worktree as
+// the working directory. A marker beside the worktree records the command-list
+// hash, so a tree prepares once per commit and re-prepares when the
+// configuration changes. Failure is soft by design: the caller warns and
+// indexes the unprepared tree, which is today's quality — a broken install
+// must never block review.
+
+const PREPARE_LOCK_RETRY_MS = 250;
+
+const PREPARE_LOCK_STALE_MS = 30 * 60_000;
+
+const PREPARE_LOCK_TIMEOUT_MS = 1000;
+
+const PREPARE_LOCK_UNOWNED_GRACE_MS = 1_000;
+
+const PREPARE_OUTPUT_TAIL_LINES = 20;
+
+export interface PrepareCommandResult {
+  exitCode: number | null;
+  /** Combined stdout+stderr, bounded to the most recent output. */
+  output?: string;
+}
+
+export interface PrepareReviewPinnedCheckoutInput {
+  checkoutPath: string;
+  commit: string;
+  commands: readonly string[];
+  warning?: (message: string) => void;
+  signal?: AbortSignal;
+  progress?: (log: string) => void;
+  timeoutMs?: number;
+  /** Test seam: replaces the shell execution of one prepare command. */
+  runCommand?: (command: string, cwd: string) => Promise<PrepareCommandResult>;
+}
+
+/** The marker file that records a completed prepare, beside the worktree. */
+export function reviewPrepareMarkerPath(checkoutPath: string): string {
+  return `${checkoutPath}.prepared`;
+}
+
+/** The failure log written beside the worktree when a prepare command fails. */
+export function reviewPrepareLogPath(checkoutPath: string): string {
+  return `${checkoutPath}.prepare-log`;
+}
+
+export function reviewPrepareCommandsHash(commands: readonly string[]): string {
+  return crypto
+    .createHash("sha256")
+    .update(JSON.stringify(commands))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+// A tree that ceases to exist takes its prepare state with it: the caller
+// removes these artifacts on every checkout removal or recreation, so a fresh
+// bare tree can never inherit a marker that claims it is prepared.
+export async function removeReviewPrepareArtifacts(
+  checkoutPath: string,
+): Promise<void> {
+  await rm(reviewPrepareMarkerPath(checkoutPath), { force: true });
+  await rm(reviewPrepareLogPath(checkoutPath), { force: true });
+}
+
+// Run the configured prepare commands in order inside the pinned checkout.
+// Returns whether the tree is prepared for exactly this command list. On the
+// first failing command: warn with the commit, the command, and the output
+// tail; write the captured output beside the worktree; leave no marker; and
+// return unprepared — the caller continues against the bare tree.
+export async function prepareReviewPinnedCheckout(
+  input: PrepareReviewPinnedCheckoutInput,
+): Promise<{ prepared: boolean }> {
+  if (input.commands.length === 0) return { prepared: false };
+  const markerPath = reviewPrepareMarkerPath(input.checkoutPath);
+  const expectedHash = reviewPrepareCommandsHash(input.commands);
+
+  if (await markerMatches(markerPath, expectedHash)) {
+    return { prepared: true };
+  }
+
+  const outcome = await withFileLock(
+    `${input.checkoutPath}.prepare-lock`,
+    {
+      retryMs: PREPARE_LOCK_RETRY_MS,
+      staleMs: PREPARE_LOCK_STALE_MS,
+      heartbeatMs: 5000,
+      timeoutMs: PREPARE_LOCK_TIMEOUT_MS,
+      unownedGraceMs: PREPARE_LOCK_UNOWNED_GRACE_MS,
+    },
+    async () => {
+      if (await markerMatches(markerPath, expectedHash)) {
+        return { prepared: true };
+      }
+
+      // A stale marker from an older command list must not survive a failed
+      // re-prepare: remove it before the first command runs.
+      await rm(markerPath, { force: true });
+
+      const runCommand =
+        input.runCommand ??
+        (async (command: string, cwd: string) => {
+          const output = await runPrepareCommand(
+            command,
+            cwd,
+            input.progress ?? (() => {}),
+            input.signal ?? new AbortController().signal,
+            input.timeoutMs,
+          );
+
+          return { exitCode: 0, output };
+        });
+
+      for (const command of input.commands) {
+        const result = await runCommand(command, input.checkoutPath).catch(
+          (cause: unknown) => ({
+            exitCode: null,
+            output: cause instanceof Error ? cause.message : String(cause),
+          }),
+        );
+
+        if (result.exitCode !== 0) {
+          const exit =
+            result.exitCode === null
+              ? "no exit code"
+              : `exit ${result.exitCode}`;
+
+          // The log is written whether or not anyone listens for warnings:
+          // it is the durable diagnostic for a failure the caller soft-skips.
+          const logNote = await writePrepareFailureLog(
+            input.checkoutPath,
+            result.output,
+          );
+
+          input.warning?.(
+            formatPrepareFailure({
+              commit: input.commit,
+              command,
+              exit,
+              output: result.output,
+              logNote,
+            }),
+          );
+
+          return { prepared: false };
+        }
+      }
+
+      await rm(reviewPrepareLogPath(input.checkoutPath), { force: true });
+      await writeFile(
+        markerPath,
+        JSON.stringify({ commandsHash: expectedHash, preparedAt: Date.now() }),
+        "utf8",
+      );
+
+      return { prepared: true };
+    },
+  );
+
+  if (!outcome.acquired) {
+    input.warning?.(
+      `devfast.prepare skipped for commit ${input.commit.slice(0, 12)}: another process holds the prepare lock. Language features use the unprepared pinned checkout.`,
+    );
+
+    return { prepared: false };
+  }
+
+  return outcome.result;
+}
+
+async function writePrepareFailureLog(
+  checkoutPath: string,
+  output: string | undefined,
+): Promise<string> {
+  const trimmed = output?.trimEnd();
+
+  if (!trimmed) return "";
+  const logPath = reviewPrepareLogPath(checkoutPath);
+
+  return writeFile(logPath, `${trimmed}\n`, "utf8")
+    .then(() => ` Full output: ${logPath}.`)
+    .catch(() => "");
+}
+
+function formatPrepareFailure(input: {
+  commit: string;
+  command: string;
+  exit: string;
+  output: string | undefined;
+  logNote: string;
+}): string {
+  const base = `devfast.prepare failed for commit ${input.commit.slice(0, 12)} (${input.exit}): ${input.command}. Language features use the unprepared pinned checkout.`;
+  const output = input.output?.trimEnd();
+
+  if (!output) return base;
+  const lines = output.split("\n");
+  const tail = lines.slice(-PREPARE_OUTPUT_TAIL_LINES).join("\n");
+  const elided = lines.length > PREPARE_OUTPUT_TAIL_LINES ? "…\n" : "";
+
+  return `${base} Last output:\n${elided}${tail}${input.logNote}`;
+}
+
+export async function markerMatches(
+  markerPath: string,
+  expectedHash: string,
+): Promise<boolean> {
+  return readFile(markerPath, "utf8")
+    .then(
+      (contents) =>
+        jsonObject(parseJsonText(contents))?.commandsHash === expectedHash,
+    )
+    .catch(() => false);
+}
+
+// Process lifecycle adapted from Milan’s managed-workspaces implementation (#334).
+export function runPrepareCommand(
+  command: string,
+  cwd: string,
+  progress: (log: string) => void,
+  signal: AbortSignal,
+  timeoutMs = 15 * 60_000,
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    signal.throwIfAborted();
+    let output = "";
+
+    const child = spawn(command, {
+      cwd,
+      shell: true,
+      detached: process.platform !== "win32",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let interrupted: Error | undefined;
+    let force: ReturnType<typeof setTimeout> | undefined;
+
+    const kill = (signal: NodeJS.Signals) => {
+      try {
+        if (process.platform !== "win32" && child.pid)
+          process.kill(-child.pid, signal);
+        else child.kill(signal);
+      } catch {
+        /* The process may already have exited. */
+      }
+    };
+
+    const stop = (reason: Error) => {
+      interrupted = reason;
+      kill("SIGTERM");
+      force ??= setTimeout(() => kill("SIGKILL"), 2000);
+      force.unref();
+    };
+
+    const abort = () =>
+      stop(new Error("Project command interrupted by shutdown."));
+
+    signal.addEventListener("abort", abort, { once: true });
+
+    const timeout = setTimeout(
+      () => stop(new Error("Project preparation timed out.")),
+      timeoutMs,
+    );
+
+    timeout.unref();
+
+    const append = (chunk: Buffer) => {
+      output = (output + chunk.toString()).slice(-64_000);
+      progress(output);
+    };
+
+    child.stdout.on("data", append);
+    child.stderr.on("data", append);
+    child.on("error", reject);
+    child.on("close", (code) => {
+      clearTimeout(timeout);
+      clearTimeout(force);
+      signal.removeEventListener("abort", abort);
+
+      if (interrupted) reject(new Error(`${interrupted.message}\n${output}`));
+      else if (code === 0) resolve(output);
+      else reject(new Error(`Command exited with ${code}.\n${output}`));
+    });
+  });
+}

package/src/review-stack.ts

@@ -0,0 +1,112 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+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(
+      z.object({
+        number: z.number().int().positive(),
+        head: z.object({ ref: z.string().min(1) }),
+      }),
+    ),
+  }),
+);
+
+export type RunGitHubApi = (host: string, endpoint: string) => Promise<string>;
+
+export async function resolveReviewStackLayers(
+  subject: Pick<ReviewApiSummary, "origin">,
+  reviews: readonly Pick<
+    ReviewApiSummary,
+    "reviewId" | "title" | "origin" | "pins"
+  >[],
+  runGitHubApi: RunGitHubApi = defaultRunGitHubApi,
+): Promise<ReviewStackLayer[]> {
+  const binding = subject.origin?.pullRequestUrl?.match(
+    /^https:\/\/([a-z0-9.-]+)\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/pull\/([1-9]\d*)$/,
+  );
+
+  if (!binding) return [];
+  const [, host, owner, repository, number] = binding;
+  const pullRequestNumber = Number(number);
+  const repoKey = `https://${host}/${owner}/${repository}`;
+  let stacks: z.infer<typeof GitHubStacksSchema>;
+
+  try {
+    stacks = GitHubStacksSchema.parse(
+      JSON.parse(
+        await runGitHubApi(
+          host!,
+          `repos/${owner}/${repository}/stacks?pull_request=${number}`,
+        ),
+      ),
+    );
+  } catch {
+    // Stack discovery must not make the Review unavailable when GitHub or
+    // authentication is unavailable, or stacks are not enabled for the repo.
+    return [];
+  }
+
+  const stack = stacks.find((candidate) =>
+    candidate.pull_requests.some((pr) => pr.number === pullRequestNumber),
+  );
+
+  if (!stack) return [];
+
+  const currentIndex = stack.pull_requests.findIndex(
+    (pr) => pr.number === pullRequestNumber,
+  );
+
+  return stack.pull_requests.map((pr, index) => {
+    const review = reviews.find((candidate) => {
+      const repository =
+        candidate.origin?.pullRequestUrl?.replace(/\/pull\/\d+.*$/, "") ??
+        candidate.pins?.repositoryId;
+
+      return (
+        repository === repoKey &&
+        candidate.origin?.pullRequestNumber === pr.number
+      );
+    });
+
+    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",
+    };
+  });
+}
+
+async function defaultRunGitHubApi(
+  host: string,
+  endpoint: string,
+): Promise<string> {
+  const { stdout } = await execFileAsync(
+    "gh",
+    ["api", "--hostname", host, endpoint],
+    {
+      env: { ...process.env, GH_PROMPT_DISABLED: "1" },
+      encoding: "utf8",
+      timeout: 10_000,
+      maxBuffer: 2 * 1024 * 1024,
+    },
+  );
+
+  return stdout;
+}