@dev.fast/whiteboard 0.0.0-stage → 0.2.0

package/src/desktop-discovery.ts

@@ -0,0 +1,355 @@
+import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  type JsonValue,
+  REVIEW_DESKTOP_DISCOVERY_VERSION,
+  type ReviewDesktopDiscovery,
+  isJsonObject,
+  jsonNumber,
+  jsonProperty,
+  parseJsonText,
+  parseReviewDesktopDiscovery,
+} from "@dev.fast/review-protocol";
+
+import {
+  reviewDefaultInstancePath,
+  reviewDevInstanceKey,
+  reviewInstancesDir,
+  reviewLegacyDiscoveryPath,
+} from "./review-home-paths";
+
+export class ReviewDesktopProtocolMismatchError extends Error {
+  readonly name = "ReviewDesktopProtocolMismatchError";
+
+  constructor(
+    readonly actualVersion: number,
+    readonly expectedVersion = REVIEW_DESKTOP_DISCOVERY_VERSION,
+  ) {
+    super(
+      `Whiteboard Desktop uses protocol ${actualVersion}, but this Whiteboard CLI needs protocol ${expectedVersion}. Update the Whiteboard CLI and Whiteboard Desktop to compatible versions, then try again.`,
+    );
+  }
+}
+
+export class ReviewDesktopDiscoveryUnreadableError extends Error {
+  readonly name = "ReviewDesktopDiscoveryUnreadableError";
+
+  constructor(filePath: string, detail?: string) {
+    super(
+      `Whiteboard Desktop discovery is unreadable at ${filePath}. Restart Whiteboard Desktop and try again.${detail ? ` ${detail}` : ""}`,
+    );
+  }
+}
+
+/** One record, or null when the file does not exist. */
+export async function readReviewDesktopDiscoveryFile(
+  filePath: string,
+): Promise<ReviewDesktopDiscovery | null> {
+  let source: string;
+
+  try {
+    source = await readFile(filePath, "utf8");
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return null;
+    }
+
+    throw new ReviewDesktopDiscoveryUnreadableError(filePath, String(error));
+  }
+
+  let value: JsonValue;
+
+  try {
+    value = parseJsonText(source);
+  } catch (error) {
+    throw new ReviewDesktopDiscoveryUnreadableError(filePath, String(error));
+  }
+
+  try {
+    return parseReviewDesktopDiscovery(value);
+  } catch (error) {
+    const version = isJsonObject(value)
+      ? jsonNumber(jsonProperty(value, "version"))
+      : undefined;
+
+    if (
+      version !== undefined &&
+      Number.isInteger(version) &&
+      version !== REVIEW_DESKTOP_DISCOVERY_VERSION
+    ) {
+      throw new ReviewDesktopProtocolMismatchError(version);
+    }
+
+    throw new ReviewDesktopDiscoveryUnreadableError(filePath, String(error));
+  }
+}
+
+export async function isHealthyReviewDesktop(
+  discovery: ReviewDesktopDiscovery,
+  fetch = globalThis.fetch,
+): Promise<boolean> {
+  try {
+    const response = await fetch(`${discovery.url}/health`, {
+      signal: AbortSignal.timeout(1_500),
+    });
+
+    if (!response.ok) return false;
+    const health = await response.json();
+
+    return (
+      isJsonObject(health) &&
+      health.ok === true &&
+      health.instanceId === discovery.instanceId &&
+      health.desktopAttached === true
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** The selected Desktop's record while it is running, else null. */
+export function healthyReviewInstance(
+  selection: ReviewInstanceSelection,
+): ReviewDesktopDiscovery | null {
+  return selection.instance?.healthy ? selection.instance.discovery : null;
+}
+
+export async function requireHealthyReviewDesktop(
+  fetch = globalThis.fetch,
+): Promise<ReviewDesktopDiscovery> {
+  const selection = await selectReviewInstance({ fetch });
+  const discovery = healthyReviewInstance(selection);
+
+  if (!discovery) throw reviewInstanceUnavailable(selection);
+
+  return discovery;
+}
+
+/** Shell-session override; agents inherit it through the bare shim. */
+export const REVIEW_INSTANCE_ENV = "DEV_REVIEW_INSTANCE";
+
+// Keys name files, so nothing else may select one.
+function checkedInstanceKey(key: string, origin = "") {
+  if (/^(?:stable|preview|dev-[A-Za-z0-9_.-]+)$/.test(key)) return key;
+  throw new Error(
+    `Unknown Whiteboard instance ${JSON.stringify(key)}${origin}. Use stable, preview, or a dev-… key from \`whiteboard instances\`.`,
+  );
+}
+
+export type ReviewInstanceIdentity = Required<
+  Pick<ReviewDesktopDiscovery, "key" | "channel">
+> &
+  Pick<ReviewDesktopDiscovery, "checkout" | "appPath" | "appVersion">;
+
+/** Identity of the Desktop hosting this process, from the env electron-main passes. */
+export function reviewInstanceIdentity(
+  env: NodeJS.ProcessEnv,
+): ReviewInstanceIdentity {
+  const checkout = env.DEV_FAST_REVIEW_CHECKOUT?.trim();
+
+  const channel = checkout
+    ? "dev"
+    : env.DEV_FAST_REVIEW_RELEASE_CHANNEL === "preview"
+      ? "preview"
+      : "stable";
+
+  const identity: ReviewInstanceIdentity = {
+    key: checkout ? reviewDevInstanceKey(checkout) : channel,
+    channel,
+  };
+
+  if (checkout) identity.checkout = path.resolve(checkout);
+  const appPath = env.DEV_FAST_REVIEW_APP_PATH?.trim();
+
+  if (appPath) identity.appPath = appPath;
+  const appVersion = env.DEV_FAST_REVIEW_APP_VERSION?.trim();
+
+  if (appVersion) identity.appVersion = appVersion;
+
+  return identity;
+}
+
+export interface ReviewInstance {
+  key: string;
+  filePath: string;
+  discovery: ReviewDesktopDiscovery;
+  healthy: boolean;
+}
+
+export interface ReviewInstanceDependencies {
+  env?: NodeJS.ProcessEnv;
+  fetch?: typeof globalThis.fetch;
+  warn?: (message: string) => void;
+}
+
+/** Records by key, plus the files that could not be read, by key. */
+export async function readReviewInstances(
+  dependencies: ReviewInstanceDependencies,
+) {
+  const env = dependencies.env ?? process.env;
+  const directory = reviewInstancesDir(env);
+  const names = await readdir(directory).catch((): string[] => []);
+
+  const files = names
+    .filter((name) => name.endsWith(".json"))
+    .map((name): [string, string] => [
+      path.basename(name, ".json"),
+      path.join(directory, name),
+    ]);
+
+  // A stable Desktop that predates instances wrote only the legacy file; it
+  // stands in for stable only while no stable record exists at all.
+  if (!names.includes("stable.json"))
+    files.push(["stable", reviewLegacyDiscoveryPath(env)]);
+
+  const records: Omit<ReviewInstance, "healthy">[] = [];
+  const broken = new Map<string, Error>();
+
+  for (const [key, filePath] of files) {
+    try {
+      const discovery = await readReviewDesktopDiscoveryFile(filePath);
+
+      if (discovery) records.push({ key, filePath, discovery });
+    } catch (error) {
+      const problem = error instanceof Error ? error : new Error(String(error));
+      broken.set(key, problem);
+      dependencies.warn?.(`Skipping ${filePath}: ${problem.message}`);
+    }
+  }
+
+  const instances = await Promise.all(
+    records.map(async (record) => ({
+      ...record,
+      healthy: await isHealthyReviewDesktop(
+        record.discovery,
+        dependencies.fetch,
+      ),
+    })),
+  );
+
+  return { instances, broken };
+}
+
+export async function readDefaultReviewInstance(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<string | undefined> {
+  const value = await readFile(reviewDefaultInstancePath(env), "utf8")
+    .then((text) => text.trim())
+    .catch(() => "");
+
+  return value || undefined;
+}
+
+export async function writeDefaultReviewInstance(
+  key: string,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+  const filePath = reviewDefaultInstancePath(env);
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${checkedInstanceKey(key)}\n`);
+}
+
+export async function clearDefaultReviewInstance(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+  await rm(reviewDefaultInstancePath(env), { force: true });
+}
+
+export interface ReviewInstanceSelection {
+  key: string;
+  source: "env" | "default" | "only-running" | "fallback";
+  /** The selected key's record, when one exists. */
+  instance?: ReviewInstance;
+  instances: ReviewInstance[];
+  /** Why the selected key's record could not be read, when it has a broken one. */
+  problem?: Error;
+}
+
+/** DEV_REVIEW_INSTANCE, then the machine default, then the only running Desktop, then stable. */
+export async function selectReviewInstance(
+  dependencies: ReviewInstanceDependencies = {},
+): Promise<ReviewInstanceSelection> {
+  const env = dependencies.env ?? process.env;
+  const { instances, broken } = await readReviewInstances(dependencies);
+  const fromEnv = env[REVIEW_INSTANCE_ENV]?.trim();
+
+  const fromDefault = fromEnv
+    ? undefined
+    : await readDefaultReviewInstance(env);
+
+  const running = instances.filter((instance) => instance.healthy);
+
+  const [key, source]: [string, ReviewInstanceSelection["source"]] = fromEnv
+    ? [checkedInstanceKey(fromEnv, ` from ${REVIEW_INSTANCE_ENV}`), "env"]
+    : fromDefault
+      ? [
+          checkedInstanceKey(
+            fromDefault,
+            " as the machine default (`whiteboard instances clear` removes it)",
+          ),
+          "default",
+        ]
+      : running.length === 1
+        ? [running[0]!.key, "only-running"]
+        : ["stable", "fallback"];
+
+  const selection: ReviewInstanceSelection = { key, source, instances };
+  const instance = instances.find((instance) => instance.key === key);
+
+  // A broken record is a diagnosis, not "not running": `app pick` must not
+  // launch a second Desktop over it. With nothing selected explicitly, any
+  // broken record may be the one Desktop that is running.
+  const problem = instance
+    ? undefined
+    : fromEnv || fromDefault
+      ? broken.get(key)
+      : broken.values().next().value;
+
+  if (instance) selection.instance = instance;
+
+  if (problem) selection.problem = problem;
+
+  return selection;
+}
+
+/** Never a redirect: names what is running and how to start or pick one. */
+export function reviewInstanceUnavailable(
+  selection: ReviewInstanceSelection,
+): Error {
+  if (selection.problem) return selection.problem;
+
+  const running = selection.instances
+    .filter((instance) => instance.healthy)
+    .map((instance) => instance.key);
+
+  const others = running.length
+    ? ` Running: ${running.join(", ")}.`
+    : " No Whiteboard is running.";
+
+  if (selection.source === "fallback" && running.length > 1)
+    return new ReviewInstanceUnavailableError(
+      `Several Whiteboard instances are running and none is selected.${others} Choose one with \`whiteboard instances use <key>\`, or \`export ${REVIEW_INSTANCE_ENV}=<key>\` for this shell.`,
+    );
+
+  return new ReviewInstanceUnavailableError(
+    `Whiteboard \`${selection.key}\` is not running. ${reviewInstanceStartHint(selection)}, or pick another instance with \`whiteboard instances\`.${others}`,
+  );
+}
+
+/** A command could not reach the selected Desktop instance. */
+export class ReviewInstanceUnavailableError extends Error {
+  readonly name = "ReviewInstanceUnavailableError";
+}
+
+export function reviewInstanceStartHint(
+  selection: Pick<ReviewInstanceSelection, "key" | "instance">,
+): string {
+  if (!selection.key.startsWith("dev-"))
+    return "Start it with `whiteboard app launch`";
+  const checkout = selection.instance?.discovery.checkout;
+
+  return checkout
+    ? `Start it with \`pnpm dev\` in ${checkout}`
+    : "Start it with `pnpm dev` in its checkout";
+}

package/src/diff-selection-migration.ts

@@ -0,0 +1,63 @@
+import {
+  type JsonValue,
+  isJsonObject,
+  isNumberValue,
+  isStringValue,
+  jsonValueSchema,
+} from "@dev.fast/review-protocol";
+
+/** Upgrade retained document attachments at the read/import boundary. New edits
+ * use the strict DiffSelection schema and never accept these retired forms. */
+// This is the decoder boundary for stored documents in retired wire formats.
+// oxlint-disable-next-line anti-slop/no-unknown-parameters
+export function migrateDiffSelections(input: unknown): JsonValue {
+  return migrateNode(jsonValueSchema.parse(input));
+}
+
+function migrateNode(value: JsonValue, attachment = false): JsonValue {
+  if (Array.isArray(value))
+    return value.map((child) => migrateNode(child, attachment));
+
+  if (!isJsonObject(value)) return value;
+
+  if (attachment && isStringValue(value.file)) {
+    if (isNumberValue(value.fromLine) && isNumberValue(value.toLine)) {
+      const side = value.side ?? value.graph ?? "head";
+
+      return {
+        file: value.file,
+        start: { side, line: value.fromLine },
+        end: { side, line: value.toLine },
+      };
+    }
+
+    if (
+      isJsonObject(value.start) &&
+      isJsonObject(value.end) &&
+      "baseLine" in value.start
+    ) {
+      const endpoint = (row: typeof value.start) =>
+        isNumberValue(row.headLine)
+          ? { side: "head", line: row.headLine }
+          : { side: "base", line: row.baseLine };
+
+      return {
+        file: value.file,
+        start: endpoint(value.start),
+        end: endpoint(value.end),
+      };
+    }
+  }
+
+  return Object.fromEntries(
+    Object.entries(value).map(([key, child]) => [
+      key,
+      migrateNode(
+        child,
+        ["source", "peek", "sources", "contextSources", "callSite"].includes(
+          key,
+        ),
+      ),
+    ]),
+  );
+}

package/src/embedded-posthog-key.ts

@@ -0,0 +1,6 @@
+// Placeholder replaced by release builds (scripts/embed-posthog-key.mjs).
+// Source checkouts embed no key: telemetry capture stays disabled unless
+// PROGRESSIVE_REVIEW_POSTHOG_KEY (or DEV_FAST_POSTHOG_KEY / POSTHOG_KEY) is
+// set in the environment.
+export const EMBEDDED_PROGRESSIVE_REVIEW_POSTHOG_KEY: string | undefined =
+  undefined;

package/src/error-telemetry.ts

@@ -0,0 +1,247 @@
+// Turns a raw JavaScript error into reportable telemetry properties.
+//
+// This module is the only place that sees raw error text on the way to PostHog.
+// Callers hand it the `error` envelope of a loopback telemetry request, and it
+// returns four things: the class name, the message with paths, addresses and
+// secrets replaced by markers, a digest of the original message, and stack
+// frames rewritten to start inside the shipped Review bundle.
+//
+// The message is cleaned with a port of VS Code's cleaner (telemetry-clean-text
+// .ts) rather than a rule of our own, because that one is proven at scale in the
+// product this is a fork of.
+//
+// ui-telemetry-events.ts re-checks the result independently — the frames
+// against a bundle-path pattern, the message against the same secret shapes plus
+// a refusal of any surviving path separator — so a bug here cannot by itself
+// leak a path.
+
+import { createHash } from "node:crypto";
+
+import {
+  type JsonObject,
+  type JsonValue,
+  isJsonObject,
+  jsonString,
+} from "@dev.fast/review-protocol";
+
+import { cleanTelemetryText } from "./telemetry-clean-text";
+import {
+  BUNDLE_FRAME_PATTERN,
+  BUNDLE_FRAME_SEPARATOR,
+  isReportableCleanedMessage,
+} from "./ui-telemetry-events";
+
+export interface DerivedErrorTelemetryProperties {
+  error_name?: string;
+  message?: string;
+  message_hash?: string;
+  frames?: string;
+}
+
+/**
+ * Errors whose message quotes the document being checked. A review tool runs
+ * authored prose through schemas, so these carry review content by design —
+ * unlike an editor, which mostly reports on files. Keep the class, the digest
+ * and the frames; drop the message. VS Code drops file-operation errors and
+ * errors carrying a system code for the same reason.
+ */
+const SCHEMA_ERROR_NAMES = new Set(["ZodError", "ValidationError"]);
+
+const MESSAGE_HASH_LENGTH = 16;
+
+const MAX_FRAMES = 10;
+
+const MAX_STACK_LENGTH = 16_384;
+
+const MAX_ERROR_NAME_LENGTH = 40;
+
+const ERROR_NAME_PATTERN = /^[A-Za-z0-9_$-]+$/;
+
+/**
+ * Path segments that exist only inside the shipped bundle. A frame keeps the
+ * text that follows the LAST occurrence of one of these and discards everything
+ * before it, which is what removes the absolute prefix. A frame with no such
+ * segment is not ours, so it is dropped.
+ */
+const BUNDLE_ANCHORS = ["/out/", "/assets/", "/review-runtime/"];
+
+/** `at fn (url:line:col)`, `at url:line:col`, and the bare `url:line:col`. */
+const STACK_FRAME_PATTERN = /(?:\(|\bat\s+|^\s*)([^()\s]+?):(\d+):(\d+)\)?\s*$/;
+
+/**
+ * `cause` is the raw error envelope a client attached beside its event
+ * properties: `{ name, message, stack }` as JSON, or anything else a hostile
+ * client sent, which derives nothing.
+ */
+export function deriveErrorTelemetryProperties(
+  cause: unknown,
+): DerivedErrorTelemetryProperties {
+  const derived: DerivedErrorTelemetryProperties = {};
+
+  try {
+    if (!isJsonObject(cause)) return derived;
+
+    const name = jsonString(cause.name);
+
+    if (
+      name !== undefined &&
+      name.length > 0 &&
+      name.length <= MAX_ERROR_NAME_LENGTH &&
+      ERROR_NAME_PATTERN.test(name)
+    ) {
+      derived.error_name = name;
+    }
+
+    const message = jsonString(cause.message);
+
+    if (message !== undefined && message.length > 0) {
+      // The digest goes on every report, cleaned message or not. It is what
+      // groups the reports whose message does not survive the checks below.
+      derived.message_hash = hashErrorMessage(message);
+
+      if (!SCHEMA_ERROR_NAMES.has(derived.error_name ?? "")) {
+        const cleaned = cleanTelemetryText(message, NO_DELETED_DIRECTORIES);
+
+        // Ask the allowlist's own check before sending. Failing here rather
+        // than there keeps a message that the cleaner could not finish out of
+        // the payload entirely, instead of relying on the later gate.
+        if (isReportableCleanedMessage(cleaned)) derived.message = cleaned;
+      }
+    }
+
+    const frames = packBundleFrames(cause.stack);
+
+    if (frames) derived.frames = frames;
+  } catch {
+    // Telemetry must never break the request that carried it.
+  }
+
+  return derived;
+}
+
+/**
+ * Properties only this module may produce, because each is a claim about work
+ * the server did that the allowlist cannot check for itself: whether a message
+ * was cleaned, and whether a digest or a frame list really came from this
+ * error. A client that sent one directly would reach the allowlist with no
+ * cleaning behind it.
+ *
+ * `error_name` is deliberately absent. The allowlist caps it at 40 identifier
+ * characters, which makes it safe whoever sends it, and `bug_report_send_failed`
+ * sends it with no error envelope.
+ */
+const SERVER_DERIVED_PROPERTIES = [
+  "message",
+  "message_hash",
+  "frames",
+] as const;
+
+/**
+ * Merge a client's event properties with the ones derived from its raw error.
+ * This is the only supported way to build an error-bearing telemetry payload:
+ * it removes any server-derived property the client tried to assert before
+ * adding the real ones.
+ */
+export function mergeErrorTelemetryProperties(
+  clientProperties: JsonObject,
+  cause: unknown,
+): JsonObject {
+  const merged = { ...clientProperties };
+
+  for (const key of SERVER_DERIVED_PROPERTIES) delete merged[key];
+
+  if (cause) Object.assign(merged, deriveErrorTelemetryProperties(cause));
+
+  return merged;
+}
+
+/**
+ * Review deliberately gives the cleaner NO directories to delete, which is the
+ * one place its configuration differs from VS Code's.
+ *
+ * VS Code passes five — its app root, extensions path, user data path, home
+ * directory and temporary directory — and deletes each prefix outright so the
+ * remainder reads as a relative path. That is right for a stack trace, where
+ * the remainder is VS Code's own file. It is wrong here: a path under the home
+ * directory then keeps everything after it, so
+ * `/Users/you/work/acme-repo/plan.md` would be sent as
+ * `/work/acme-repo/plan.md` — the repository name intact. A review tool cannot
+ * disclose that.
+ *
+ * With no directories to delete, the cleaner's overlap check never fires and
+ * the whole path is replaced by a marker instead, which is what we want. Frames
+ * are unaffected: they are anchored on the bundle directory separately.
+ */
+const NO_DELETED_DIRECTORIES: RegExp[] = [];
+
+/**
+ * A stable fingerprint of the message. Two reports with the same digest had the
+ * same cause; the digest itself reveals nothing, because it is one-way and the
+ * message is never sent alongside it.
+ */
+export function hashErrorMessage(message: string): string {
+  return createHash("sha256")
+    .update(message, "utf8")
+    .digest("hex")
+    .slice(0, MESSAGE_HASH_LENGTH);
+}
+
+/**
+ * Rewrite a stack into bundle-relative `file:line:col` frames joined by "|".
+ * Returns undefined when no frame resolves inside the bundle.
+ */
+export function packBundleFrames(
+  stack: JsonValue | undefined,
+): string | undefined {
+  const text = Array.isArray(stack) ? stack.join("\n") : jsonString(stack);
+
+  if (!text) return undefined;
+
+  const frames: string[] = [];
+
+  for (const line of text.slice(0, MAX_STACK_LENGTH).split("\n")) {
+    const match = STACK_FRAME_PATTERN.exec(line);
+
+    if (!match) continue;
+    const file = bundleRelativePath(match[1]);
+
+    if (!file) continue;
+    const frame = `${file}:${match[2]}:${match[3]}`;
+
+    // A user directory can be called "out" too, so anchoring alone is not
+    // enough: the result must also start inside a known bundle directory.
+    if (!BUNDLE_FRAME_PATTERN.test(frame)) continue;
+    frames.push(frame);
+
+    if (frames.length >= MAX_FRAMES) break;
+  }
+
+  return frames.length > 0 ? frames.join(BUNDLE_FRAME_SEPARATOR) : undefined;
+}
+
+function bundleRelativePath(location: string): string | undefined {
+  // Drop a query or fragment first: either can carry arbitrary text, and a
+  // cache-busting query is common on the canvas bundle.
+  const clean = location.split(/[?#]/, 1)[0];
+  let cut = -1;
+  let anchorLength = 0;
+
+  for (const anchor of BUNDLE_ANCHORS) {
+    const index = clean.lastIndexOf(anchor);
+
+    if (index > cut) {
+      cut = index;
+      anchorLength = anchor.length;
+    }
+  }
+
+  if (cut < 0) return undefined;
+  const relative = clean.slice(cut + anchorLength);
+  // "/review-runtime/" and "/assets/" name the directory the frame lives in, so
+  // put it back; "/out/" is a build directory and is not part of the path we
+  // report.
+  const prefix = clean.slice(cut + 1, cut + anchorLength);
+  const path = prefix === "out/" ? relative : `${prefix}${relative}`;
+
+  return path.length > 0 ? path : undefined;
+}

package/src/evidence.ts

@@ -0,0 +1,14 @@
+/** Quote matching shared by legacy publish and JSON accept: authors paste
+ * transcript text with arbitrary line wrapping, so both sides compare on
+ * whitespace-normalized text. */
+export function normalizeQuoteText(text: string): string {
+  return text.trim().replace(/\s+/g, " ");
+}
+
+export function textIncludesQuote(text: string, quote: string): boolean {
+  const normalizedQuote = normalizeQuoteText(quote);
+
+  return (
+    normalizedQuote !== "" && normalizeQuoteText(text).includes(normalizedQuote)
+  );
+}