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

package/src/exception-telemetry.ts

@@ -0,0 +1,126 @@
+// The PostHog error-tracking twin of a sanitized review_client_error. It reuses
+// the already cleaned message, the digest and the bundle-relative frames, so it
+// adds nothing the allowlist has not checked.
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+import {
+  type JsonObject,
+  jsonObject,
+  jsonString,
+  parseJsonText,
+} from "@dev.fast/json";
+
+import { BUNDLE_FRAME_SEPARATOR } from "./ui-telemetry-events";
+
+const FRAME_PATTERN = /^(.+):(\d+):(\d+)$/;
+
+/** Processes that run on Node rather than in a browser renderer. */
+const NODE_PROCESSES = new Set(["main", "server"]);
+
+export type ChunkIds = ReadonlyMap<string, string>;
+
+/** Written by apps/review-desktop/scripts/upload-source-maps.mjs. */
+const CHUNK_ID_MANIFEST = "review-chunk-ids.json";
+
+const CHUNK_ID_PATTERN = /^[0-9a-f-]{36}$/;
+
+/** The entry is `<app>/review-runtime/dist/server/desktop-host.js`. */
+export function readChunkIds(serverEntry: string | undefined): ChunkIds {
+  if (!serverEntry) return new Map();
+
+  try {
+    const manifest = jsonObject(
+      parseJsonText(
+        readFileSync(
+          path.resolve(
+            path.dirname(serverEntry),
+            "../../../out",
+            CHUNK_ID_MANIFEST,
+          ),
+          "utf8",
+        ),
+      ),
+    );
+
+    return new Map(
+      Object.entries(manifest ?? {}).flatMap(([file, id]) => {
+        const chunkId = jsonString(id);
+
+        return chunkId && CHUNK_ID_PATTERN.test(chunkId)
+          ? [[file, chunkId] as const]
+          : [];
+      }),
+    );
+  } catch {
+    return new Map();
+  }
+}
+
+export function exceptionProperties(
+  properties: JsonObject,
+  chunkIds: ChunkIds = new Map(),
+): JsonObject | undefined {
+  const type = jsonString(properties.error_name);
+  const hash = jsonString(properties.message_hash);
+
+  if (type === undefined && hash === undefined) return undefined;
+
+  const platform = NODE_PROCESSES.has(
+    jsonString(properties.error_process) ?? "",
+  )
+    ? "node:javascript"
+    : "web:javascript";
+
+  const frames = (jsonString(properties.frames) ?? "")
+    .split(BUNDLE_FRAME_SEPARATOR)
+    .flatMap((frame) => parseFrame(frame, platform, chunkIds));
+
+  const exception = {
+    $exception_level: "error",
+    $exception_list: [
+      {
+        type: type ?? "Error",
+        value:
+          jsonString(properties.message) ??
+          (hash ? `[message withheld] ${hash}` : "[message withheld]"),
+        mechanism: { handled: true, synthetic: false },
+        stacktrace: { type: "raw", frames },
+      },
+    ],
+  } satisfies JsonObject;
+
+  // Let PostHog group resolvable stacks by frame, not by message.
+  const resolvable =
+    frames.length > 0 && frames.every((frame) => frame.chunk_id);
+
+  return hash === undefined || resolvable
+    ? exception
+    : { ...exception, $exception_fingerprint: hash };
+}
+
+function parseFrame(
+  frame: string,
+  platform: string,
+  chunkIds: ChunkIds,
+): JsonObject[] {
+  const match = FRAME_PATTERN.exec(frame);
+
+  if (!match) return [];
+
+  const parsed: JsonObject = {
+    platform,
+    filename: match[1],
+    lineno: Number(match[2]),
+    colno: Number(match[3]),
+    function: "?",
+    in_app: true,
+  };
+
+  const chunkId = chunkIds.get(match[1]);
+
+  if (chunkId) parsed.chunk_id = chunkId;
+
+  return [parsed];
+}

package/src/fixtures/blocks/call_stack_diff.json

@@ -0,0 +1,27 @@
+[
+  {
+    "id": "block-1",
+    "type": "call_stack_diff",
+    "title": "Status path",
+    "base": [
+      {
+        "id": "frame-1",
+        "key": "status",
+        "source": "base/order.ts#L1",
+        "label": "status = draft"
+      }
+    ],
+    "head": [
+      {
+        "id": "frame-2",
+        "key": "status",
+        "source": "head/order.ts#L1",
+        "label": "status = queued",
+        "via": {
+          "kind": "call",
+          "reason": "direct"
+        }
+      }
+    ]
+  }
+]

package/src/fixtures/blocks/callout.json

@@ -0,0 +1,11 @@
+[
+  {
+    "id": "block-1",
+    "type": "callout",
+    "title": "Note",
+    "tone": "warning",
+    "children": [
+      { "id": "block-2", "type": "markdown", "markdown": "Careful.\n" }
+    ]
+  }
+]

package/src/fixtures/blocks/code.json

@@ -0,0 +1,9 @@
+[
+  {
+    "id": "block-1",
+    "type": "code",
+    "language": "ts",
+    "text": "export const status = \"queued\";\n",
+    "caption": "The new status"
+  }
+]

package/src/fixtures/blocks/code_peek.json

@@ -0,0 +1,8 @@
+[
+  {
+    "id": "block-1",
+    "type": "code_peek",
+    "source": "head/order.ts#L1",
+    "caption": "Queued"
+  }
+]

package/src/fixtures/blocks/database_lens.json

@@ -0,0 +1,51 @@
+[
+  {
+    "id": "block-1",
+    "type": "database_lens",
+    "title": "Orders",
+    "actors": {
+      "service": "Order service"
+    },
+    "stores": {
+      "orders": {
+        "label": "Orders DB",
+        "storage": "relational",
+        "collections": {
+          "orders": {
+            "label": "orders",
+            "key": "id",
+            "fields": {
+              "id": {
+                "label": "id",
+                "dataType": "text",
+                "primaryKey": true
+              },
+              "status": {
+                "label": "status",
+                "dataType": "text"
+              }
+            }
+          }
+        }
+      }
+    },
+    "useCases": [
+      {
+        "id": "case-1",
+        "label": "Queue an order",
+        "operations": [
+          {
+            "id": "operation-1",
+            "kind": "write",
+            "store": "orders",
+            "collection": "orders",
+            "field": "status",
+            "actor": "service",
+            "label": "write queued",
+            "source": "head/order.ts#L1"
+          }
+        ]
+      }
+    ]
+  }
+]

package/src/fixtures/blocks/divider.json

@@ -0,0 +1 @@
+[{ "id": "block-1", "type": "divider" }]

package/src/fixtures/blocks/fixtures.ts

@@ -0,0 +1,33 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { type JsonValue, parseJsonText } from "@dev.fast/review-protocol";
+
+export const BLOCK_FIXTURES_ROOT = path.dirname(fileURLToPath(import.meta.url));
+
+export {
+  FIXTURE_IMAGE_ID,
+  FIXTURE_MAP_ID,
+  FIXTURE_TRACE_EVENT_ID,
+  FIXTURE_TRACE_ID,
+} from "./ids.js";
+
+/** One entry per `<type>.json`: the block type and its array of valid blocks. */
+export async function readBlockFixtures(): Promise<Map<string, JsonValue[]>> {
+  const fixtures = new Map<string, JsonValue[]>();
+
+  for (const name of (await readdir(BLOCK_FIXTURES_ROOT)).sort()) {
+    if (!name.endsWith(".json")) continue;
+
+    const parsed = parseJsonText(
+      await readFile(path.join(BLOCK_FIXTURES_ROOT, name), "utf8"),
+    );
+
+    if (!Array.isArray(parsed))
+      throw new Error(`${name} must be an array of blocks.`);
+    fixtures.set(name.slice(0, -".json".length), parsed);
+  }
+
+  return fixtures;
+}

package/src/fixtures/blocks/flow_diagram.json

@@ -0,0 +1,36 @@
+[
+  {
+    "type": "flow_diagram",
+    "title": "Queue an order",
+    "nodes": [
+      {
+        "key": "request",
+        "label": "Queue order",
+        "attachments": [
+          {
+            "label": "Handler",
+            "sources": ["head/order.ts#L1"]
+          },
+          {
+            "label": "Validation",
+            "sources": ["base/order.ts#L1"]
+          }
+        ]
+      },
+      {
+        "key": "saved",
+        "label": "Saved",
+        "kind": "terminal",
+        "attachments": []
+      }
+    ],
+    "edges": [
+      {
+        "from": "request",
+        "to": "saved",
+        "label": "persist"
+      }
+    ],
+    "id": "flow-1"
+  }
+]

package/src/fixtures/blocks/ids.ts

@@ -0,0 +1,8 @@
+/** Resource ids the block fixtures reference; tests map them to real uploads or stubs. */
+export const FIXTURE_IMAGE_ID = "11111111-1111-4111-8111-111111111111";
+
+export const FIXTURE_TRACE_ID = "22222222-2222-4222-8222-222222222222";
+
+export const FIXTURE_TRACE_EVENT_ID = "0";
+
+export const FIXTURE_MAP_ID = "33333333-3333-4333-8333-333333333333";

package/src/fixtures/blocks/image.json

@@ -0,0 +1,9 @@
+[
+  {
+    "id": "block-1",
+    "type": "image",
+    "assetId": "11111111-1111-4111-8111-111111111111",
+    "alt": "One pixel",
+    "caption": "An image"
+  }
+]

package/src/fixtures/blocks/markdown.json

@@ -0,0 +1,7 @@
+[
+  {
+    "id": "block-1",
+    "type": "markdown",
+    "markdown": "# Order status\n\nThe status moves to [queued](review-source:head/order.ts#L1).\n"
+  }
+]

package/src/fixtures/blocks/section.json

@@ -0,0 +1,11 @@
+[
+  {
+    "id": "block-1",
+    "type": "section",
+    "title": "Welcome",
+    "defaultCollapsed": false,
+    "children": [
+      { "id": "block-2", "type": "markdown", "markdown": "Hello.\n" }
+    ]
+  }
+]

package/src/fixtures/blocks/sequence.json

@@ -0,0 +1,31 @@
+[
+  {
+    "id": "diagram-1",
+    "type": "sequence",
+    "title": "Order status",
+    "actors": {
+      "api": "API",
+      "store": "Order store"
+    },
+    "steps": [
+      {
+        "id": "step-1",
+        "type": "step",
+        "from": "api",
+        "to": "store",
+        "label": "set status",
+        "style": "call",
+        "source": "head/order.ts#L1"
+      },
+      {
+        "id": "step-2",
+        "type": "step",
+        "from": "store",
+        "to": "api",
+        "label": "queued",
+        "style": "return",
+        "explanation": "The stored status"
+      }
+    ]
+  }
+]

package/src/fixtures/blocks/software_map.json

@@ -0,0 +1,7 @@
+[
+  {
+    "id": "block-1",
+    "type": "software_map",
+    "mapVersionId": "33333333-3333-4333-8333-333333333333"
+  }
+]

package/src/fixtures/blocks/trace_quote.json

@@ -0,0 +1,9 @@
+[
+  {
+    "id": "block-1",
+    "type": "trace_quote",
+    "traceId": "22222222-2222-4222-8222-222222222222",
+    "eventId": "0",
+    "text": "queue the order"
+  }
+]

package/src/fixtures/blocks/tutorial.json

@@ -0,0 +1,51 @@
+[
+  {
+    "type": "tutorial",
+    "kind": "keymap",
+    "id": "block-1"
+  },
+  {
+    "type": "tutorial",
+    "kind": "conversation",
+    "conversation": {
+      "version": 1,
+      "title": "How an agent authors a review",
+      "messages": [
+        {
+          "role": "user",
+          "body": "Explain this change."
+        },
+        {
+          "role": "assistant",
+          "body": "Here is a review."
+        }
+      ]
+    },
+    "id": "block-2"
+  },
+  {
+    "type": "tutorial",
+    "kind": "view",
+    "view": "commits",
+    "label": "Explore commits",
+    "id": "block-3"
+  },
+  {
+    "type": "tutorial",
+    "kind": "feature",
+    "feature": "softwareMap",
+    "children": [
+      {
+        "type": "markdown",
+        "markdown": "Explore the map.",
+        "id": "block-5"
+      },
+      {
+        "id": "block-6",
+        "type": "software_map",
+        "mapVersionId": "33333333-3333-4333-8333-333333333333"
+      }
+    ],
+    "id": "block-4"
+  }
+]

package/src/fs-utils.ts

@@ -0,0 +1,32 @@
+import { readdir, stat } from "node:fs/promises";
+
+/** Whether a thrown filesystem error reports a missing file (ENOENT). */
+export function isMissingFileError(cause: unknown): boolean {
+  return cause instanceof Error && "code" in cause && cause.code === "ENOENT";
+}
+
+/** Entries of a directory that may not exist yet. */
+export async function readDirectory(directory: string) {
+  try {
+    return await readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    if (isMissingFileError(error)) return [];
+    throw error;
+  }
+}
+
+export async function isDirectory(target: string): Promise<boolean> {
+  try {
+    return (await stat(target)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export async function isFile(target: string): Promise<boolean> {
+  try {
+    return (await stat(target)).isFile();
+  } catch {
+    return false;
+  }
+}

package/src/fuzzy-match.ts

@@ -0,0 +1,94 @@
+import fuzzysort from "fuzzysort";
+
+/* Below this score the query only matched as scattered letters — "dev" landing
+   on the d, e and v of "Speed up Review Desktop". Those hits are noise, and a
+   plain subsequence matcher cannot tell them from real ones. */
+const SCORE_THRESHOLD = 0.5;
+
+/**
+ * The single fuzzy matcher for this package. Each label is scored on its own,
+ * never joined: a match across a join could pair a letter from one label with
+ * a letter from the next and keep an item that shows neither word.
+ */
+function bestScore(needle: string, labels: readonly string[]): number {
+  let best = 0;
+
+  for (const label of labels) {
+    const score = fuzzysort.single(needle, label)?.score ?? 0;
+
+    if (score > best) best = score;
+  }
+
+  return best;
+}
+
+/** True when the query hits any label. An empty query matches everything. */
+export function fuzzyMatches(query: string, ...labels: string[]): boolean {
+  const needle = query.trim();
+
+  if (!needle) return true;
+
+  return bestScore(needle, labels) >= SCORE_THRESHOLD;
+}
+
+export interface FuzzySegment {
+  text: string;
+  matched: boolean;
+}
+
+/**
+ * The label split into matched and unmatched runs, in order, for callers that
+ * want to mark the hit. Returns the whole label as one unmatched segment when
+ * the label itself did not match — a review found by its worktree name shows a
+ * plain title, not a scatter of marked letters.
+ *
+ * Segments, not markup: this module must not depend on a UI framework.
+ */
+export function fuzzySegments(query: string, label: string): FuzzySegment[] {
+  const whole = [{ text: label, matched: false }];
+  const needle = query.trim();
+
+  if (!needle) return whole;
+  const result = fuzzysort.single(needle, label);
+
+  if (!result || result.score < SCORE_THRESHOLD) return whole;
+
+  // Indexed by code unit, the way fuzzysort reports its matches.
+  const hit = new Set<number>(result.indexes);
+  const segments: FuzzySegment[] = [];
+
+  for (let index = 0; index < label.length; index++) {
+    const matched = hit.has(index);
+    const last = segments.at(-1);
+
+    if (last && last.matched === matched) {
+      last.text += label[index];
+    } else {
+      segments.push({ text: label[index], matched });
+    }
+  }
+
+  return segments;
+}
+
+/**
+ * The items whose labels hit the query, best match first. An empty query keeps
+ * every item in its original order.
+ */
+export function fuzzyRank<T>(
+  query: string,
+  items: readonly T[],
+  labelsOf: (item: T) => string[],
+): T[] {
+  const needle = query.trim();
+
+  if (!needle) return [...items];
+
+  return items
+    .values()
+    .map((item) => ({ item, score: bestScore(needle, labelsOf(item)) }))
+    .filter((hit) => hit.score >= SCORE_THRESHOLD)
+    .toArray()
+    .sort((left, right) => right.score - left.score)
+    .map((hit) => hit.item);
+}

package/src/install.ts

@@ -0,0 +1,29 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type InstallTarget =
+  | "claude"
+  | "codex"
+  | "cursor"
+  | "opencode"
+  | "pi"
+  | "omp"
+  | "copilot";
+
+export const ALL_INSTALL_TARGETS: InstallTarget[] = [
+  "claude",
+  "codex",
+  "cursor",
+  "opencode",
+  "pi",
+  "omp",
+  "copilot",
+];
+
+export function isInstallTarget(value: string): value is InstallTarget {
+  return ALL_INSTALL_TARGETS.some((target) => target === value);
+}
+
+export function defaultPackageRoot(): string {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+}