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

package/src/review-api/image-decode.ts

@@ -0,0 +1,29 @@
+import { ReviewInputError } from "./document.js";
+
+/** The one decoder for images entering the store, whether uploaded by a client
+ * or read from a legacy review: bounded, single frame, re-encoded as PNG. */
+export async function decodeImage(bytes: Uint8Array): Promise<Buffer> {
+  const { default: sharp } = await import("sharp");
+
+  try {
+    const decoder = sharp(Buffer.from(bytes), {
+      limitInputPixels: 20_000_000,
+      failOn: "warning",
+    });
+
+    const metadata = await decoder.metadata();
+
+    if (
+      !["png", "jpeg", "webp"].includes(metadata.format ?? "") ||
+      (metadata.pages ?? 1) !== 1
+    )
+      throw new Error("Unsupported image");
+
+    // One bounded full decode; retain a safe raster format, not the original file.
+    return await decoder.png().toBuffer();
+  } catch {
+    throw new ReviewInputError(
+      "Provide a valid single PNG, JPEG, or WebP image (at most 20 megapixels).",
+    );
+  }
+}

package/src/review-api/input-error.ts

@@ -0,0 +1,9 @@
+/** Deliberately safe to show to API clients, unlike filesystem/provider errors. */
+export class ReviewInputError extends Error {
+  constructor(
+    message: string,
+    readonly status: 400 | 401 | 404 | 409 = 400,
+  ) {
+    super(message);
+  }
+}

package/src/review-api/instructions.ts

@@ -0,0 +1,89 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { findReviewPackageRoot } from "@review/package-paths.js";
+import { z } from "zod";
+
+import { COMPONENT_REFERENCE } from "./component-reference.js";
+
+export const INSTRUCTION_TOPICS = [
+  "authoring",
+  "file-lenses",
+  "scratchpad",
+  "trace-archaeology",
+] as const;
+
+export type InstructionTopic = (typeof INSTRUCTION_TOPICS)[number];
+
+export const instructionsQuerySchema = z.strictObject({
+  topic: z.enum(INSTRUCTION_TOPICS).default("authoring"),
+});
+
+export interface InstructionContext {
+  desktopAvailable: boolean;
+  scratchpadEnabled: boolean;
+  traceEnabled: boolean;
+}
+
+export function scratchpadAvailable(context: InstructionContext): boolean {
+  return context.desktopAvailable && context.scratchpadEnabled;
+}
+
+const cache = new Map<string, Promise<string>>();
+
+function read(root: string, name: string): Promise<string> {
+  const file = path.join(root, "instructions", `${name}.md`);
+  let content = cache.get(file);
+
+  if (!content) {
+    content = readFile(file, "utf8").catch((error) => {
+      cache.delete(file);
+      throw error;
+    });
+    cache.set(file, content);
+  }
+
+  return content;
+}
+
+export async function renderInstructions(
+  topic: InstructionTopic,
+  context: InstructionContext,
+  root = findReviewPackageRoot(import.meta.url),
+): Promise<string> {
+  if (topic === "scratchpad" && !scratchpadAvailable(context)) {
+    return "The Whiteboard scratchpad is turned off or Whiteboard Desktop is not running. Answer in chat; the scratchpad can be turned on in Whiteboard Desktop Settings.";
+  }
+
+  if (topic === "trace-archaeology" && !context.traceEnabled)
+    return "Trace capture is off on this machine, so no agent traces are available. It can be turned on in Whiteboard Desktop Settings under Experimental Features.";
+
+  if (topic === "scratchpad")
+    return `${await read(root, topic)}\n\n${COMPONENT_REFERENCE}`;
+
+  if (topic !== "authoring") return read(root, topic);
+
+  const more = [
+    ...(scratchpadAvailable(context)
+      ? [
+          '- Explaining code visually outside a review: `session_get_instructions({topic:"scratchpad"})`',
+        ]
+      : []),
+    ...(context.traceEnabled
+      ? [
+          '- Why code exists / past agent sessions: `session_get_instructions({topic:"trace-archaeology"})`',
+        ]
+      : []),
+  ];
+
+  return [
+    await read(root, "authoring"),
+    COMPONENT_REFERENCE,
+    ...(context.traceEnabled
+      ? [
+          '## Traces\n\nAt the end, run `whiteboard trace list --session <sessionId> --json`, which covers every commit in the review. If it lists no sessions, there are no traces to quote: skip this step. Otherwise read `session_get_instructions({topic:"trace-archaeology"})` and rewrite as much as possible of the what/why, design, and requirements sections in terms of literal trace quotes from the user.',
+        ]
+      : []),
+    ...(more.length ? [`## More guidance\n\n${more.join("\n")}`] : []),
+  ].join("\n\n");
+}

package/src/review-api/lens-alignment.ts

@@ -0,0 +1,52 @@
+import type { AlignmentRow } from "@review/lens-selection.js";
+import { parseUnifiedPatch } from "@review/unified-diff.js";
+
+/** Project the already-computed patch's runs, including unchanged gaps. */
+export function textualRows(
+  path: string,
+  patch: string,
+  baseCount: number,
+  headCount: number,
+): AlignmentRow[] {
+  const rows: AlignmentRow[] = [];
+
+  let base = 0,
+    head = 0;
+
+  const append = (baseEnd: number, headEnd: number) => {
+    while (base < baseEnd || head < headEnd)
+      rows.push([
+        base < baseEnd ? base++ : null,
+        head < headEnd ? head++ : null,
+      ]);
+  };
+
+  for (const hunk of parseUnifiedPatch(path, patch)) {
+    append(
+      hunk.oldLines ? hunk.oldStart - 1 : hunk.oldStart,
+      hunk.newLines ? hunk.newStart - 1 : hunk.newStart,
+    );
+
+    let removed = 0,
+      added = 0;
+
+    const flush = () => {
+      append(base + removed, head + added);
+      removed = added = 0;
+    };
+
+    for (const line of hunk.lines) {
+      if (line.kind === "context") {
+        flush();
+        append(base + 1, head + 1);
+      } else if (line.kind === "add") added++;
+      else removed++;
+    }
+
+    flush();
+  }
+
+  append(baseCount, headCount);
+
+  return rows;
+}