@dev.fast/whiteboard 0.3.4 → 0.3.5-preview.20261021.131

package/src/stored-document-migration.ts

@@ -1,18 +1,124 @@
-import { type JsonValue, isJsonObject } from "@dev.fast/review-protocol";
+import {
+  type JsonObject,
+  type JsonValue,
+  isBooleanValue,
+  isJsonObject,
+  isNumberValue,
+  isStringValue,
+} from "@dev.fast/review-protocol";
 import { z } from "zod";
 
-import { migrateDiffSelections } from "./diff-selection-migration.js";
+import {
+  ATTACHMENT_KEYS,
+  migrateDiffSelections,
+  retiredSelection,
+} from "./diff-selection-migration.js";
 import { formatAnchor } from "./lens-selection.js";
 import { label } from "./review-api/blocks/definition.js";
 import { type Lens, lensTargetsSchema } from "./review-api/diff-lenses.js";
+import { respellLinks } from "./review-api/document.js";
 
 /** Upgrade a saved or shared Review document to the current block schema at the
  * read/import boundary. New edits use the strict schema and never accept these
- * retired forms. */
+ * retired forms. One walk makes a fresh copy: retired attachments become
+ * selections, anchors become strings, sections lose their status, and
+ * Markdown links are spelled the current way. */
 // This is the decoder boundary for stored documents in retired wire formats.
 // oxlint-disable-next-line anti-slop/no-unknown-parameters
 export function migrateStoredDocument(input: unknown): JsonValue {
-  return anchorStrings(dropSectionStatus(migrateDiffSelections(input)));
+  return upgradeNode(input, { attachment: false, anchors: true });
+}
+
+/** Where a node sits: under a key that held a retired attachment, and
+ * whether its anchors still need converting (not inside an anchor). */
+interface NodePlace {
+  attachment: boolean;
+  anchors: boolean;
+  blockPins?: JsonValue;
+}
+
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- Decoder boundary: every value is checked to be JSON as it is copied.
+function upgradeNode(value: unknown, place: NodePlace): JsonValue {
+  if (isStringValue(value) || isBooleanValue(value) || value === null)
+    return value;
+
+  if (isNumberValue(value) && Number.isFinite(value)) return value;
+
+  if (Array.isArray(value))
+    return value.map((child) => upgradeNode(child, place));
+
+  if (!isJsonObject(value)) throw new TypeError("A document must be JSON.");
+
+  const selection = place.attachment ? retiredSelection(value) : undefined;
+
+  if (selection)
+    return upgradeNode(selection, { attachment: false, anchors: false });
+
+  const inherited = place.anchors ? (value.pins ?? place.blockPins) : undefined;
+  let pins: JsonValue | undefined;
+
+  const convert = (anchor: JsonValue): JsonValue => {
+    // Most anchors are strings already.
+    if (isStringValue(anchor)) return anchor;
+
+    const parsed = selectionObjectSchema.safeParse(anchor);
+
+    if (!parsed.success) return anchor;
+
+    const { pins: own, ...anchorAt } = parsed.data;
+
+    if (own) pins = own;
+
+    return formatAnchor(anchorAt);
+  };
+
+  const entries: [string, JsonValue][] = [];
+
+  for (const [key, child] of Object.entries(value)) {
+    if (key === "status" && value.type === "section") continue;
+
+    if (key === "markdown" && isStringValue(child)) {
+      entries.push([key, respellLinks(child)]);
+      continue;
+    }
+
+    const attachment = ATTACHMENT_KEYS.includes(key);
+
+    if (place.anchors && ANCHOR_KEYS.includes(key)) {
+      const anchors = upgradeNode(child, { attachment, anchors: false });
+
+      entries.push([
+        key,
+        Array.isArray(anchors) ? anchors.map(convert) : convert(anchors),
+      ]);
+    } else
+      entries.push([
+        key,
+        upgradeNode(child, {
+          attachment,
+          anchors: place.anchors,
+          blockPins: inherited,
+        }),
+      ]);
+  }
+
+  const upgraded: JsonObject = Object.fromEntries(entries);
+
+  if (
+    pins !== undefined &&
+    value.kind !== "ranges" &&
+    JSON.stringify(pins) !== JSON.stringify(place.blockPins)
+  )
+    upgraded.pins = pins;
+
+  return upgraded;
+}
+
+/** A stored document as the store reads it: retired forms upgraded, and
+ * lens blocks lifted out to the snapshot's own lenses. */
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- Decoder boundary for stored documents in retired formats.
+export function readStoredDocument(input: unknown): LiftedLenses {
+  return liftFileLenses(migrateStoredDocument(input));
 }
 
 /** Lenses saved before ranges were anchor strings. */
@@ -82,21 +188,6 @@ export function anchorStrings(
   return migrated;
 }
 
-/** Sections once carried an optional `status` (pending, in_progress or
- * complete). The authoring lease is now the only signal of work in progress,
- * so versions saved before it was retired drop the field when read. */
-function dropSectionStatus(value: JsonValue): JsonValue {
-  if (Array.isArray(value)) return value.map(dropSectionStatus);
-
-  if (!isJsonObject(value)) return value;
-
-  return Object.fromEntries(
-    Object.entries(value)
-      .filter(([key]) => !(value.type === "section" && key === "status"))
-      .map(([key, child]) => [key, dropSectionStatus(child)]),
-  );
-}
-
 /** A saved `file_lens` block, from before lenses left the document. */
 const legacyFileLensSchema = z.object({
   type: z.literal("file_lens"),

package/src/ui-telemetry-events.ts

@@ -18,9 +18,9 @@
 
 import {
   type JsonObject,
+  REVIEW_COLOR_THEME_KINDS,
   REVIEW_DIFF_LAYOUTS,
   REVIEW_DIFF_LAYOUT_SCOPES,
-  REVIEW_THEME_CHOICES,
   isJsonObject,
   jsonBoolean,
   jsonNumber,
@@ -29,6 +29,7 @@ import {
 import { z } from "zod";
 
 import { askAgentIds } from "./ask/thread-state";
+import { SELECTION_UNAVAILABLE_REASONS } from "./lens-selection";
 import { containsFilePath, hasPossibleUserInfo } from "./telemetry-clean-text";
 
 /** Property value validators: an enum of allowed strings, or a scalar type. */
@@ -70,6 +71,13 @@ const PEEK_VIA = [
 
 export const PEEK_ROOT_KIND = ["range"] as const;
 
+/** `unresolved`: progress finished without this selection; `error`: progress failed. */
+export const PEEK_FAILURE_REASON = [
+  ...SELECTION_UNAVAILABLE_REASONS,
+  "error",
+  "unresolved",
+] as const;
+
 export const LSP_FEATURE = [
   "hover",
   "goto_definition",
@@ -137,7 +145,7 @@ export const SETTING_NAME = [
   "telemetry_enabled",
   "keymap",
   "software_map_enabled",
-  "scratchpad_enabled",
+  "sharing_enabled",
   "diffr_config",
   "theme",
   "ctrl_tab",
@@ -145,16 +153,19 @@ export const SETTING_NAME = [
   "ready_notification",
   "document_width",
   "code_font_size",
+  "document_font_size",
+  "reading_font",
+  "code_font_family",
+  "font_ligatures",
+  "diff_font_size",
+  "diff_word_wrap",
+  "diff_ignore_whitespace",
 ] as const;
 
 export const REVIEW_OPENED_VIA = ["home", "cli", "other"] as const;
 
-/** Where a review's source comes from: its target's kind, or the one scratchpad. */
-export const SESSION_SOURCE_KIND = [
-  "worktree",
-  "commits",
-  "scratchpad",
-] as const;
+/** Where a review's source comes from: its target's kind. */
+export const SESSION_SOURCE_KIND = ["worktree", "commits", "project"] as const;
 
 /**
  * The authoring agent a review session is attributed to. This is the one
@@ -246,6 +257,7 @@ export const INSTALL_LOCATION = [
 
 export const DIFF_OPENED_VIA = [
   "topbar",
+  "sidebar",
   "lens",
   "locate",
   "file_picker",
@@ -254,6 +266,15 @@ export const DIFF_OPENED_VIA = [
 /** Which diff opened: a commit's, or a file diff drawn plain or structural. */
 export const DIFF_OPENED_KIND = ["commit", "structural"] as const;
 
+export const DIFF_FAILED_REASON = [
+  "missing_binary",
+  "process_exit",
+  "stream_ended",
+  "aborted",
+  "file_error",
+  "other",
+] as const;
+
 /** GitHub Enterprise is any GitHub host but github.com. */
 export const PR_PROVIDER = [
   "github",
@@ -277,7 +298,9 @@ export const ONBOARDING_STEP = ["welcome", "install", "run"] as const;
 
 export const RUN_MODE = ["draw", "copy"] as const;
 
-export const NEW_WHITEBOARD_VIA = ["button", "command"] as const;
+export const NEW_WHITEBOARD_VIA = ["button", "command", "sidebar"] as const;
+
+export const NEW_WHITEBOARD_MODE = [...RUN_MODE, "empty"] as const;
 
 export const FIND_SURFACE = ["review", "diff"] as const;
 
@@ -390,10 +413,6 @@ export const UI_TELEMETRY_EVENTS = {
     event: "review_map_expanded",
     properties: { level: MAP_LEVEL },
   },
-  commit_expanded: {
-    event: "review_commit_expanded",
-    properties: { expanded: "boolean" },
-  },
   commit_diff_opened: {
     event: "review_commit_diff_opened",
     properties: { via: COMMIT_DIFF_VIA },
@@ -533,11 +552,11 @@ export const UI_TELEMETRY_EVENTS = {
   },
   setting_changed: {
     event: "review_setting_changed",
-    // value carries the chosen option for the one multi-valued setting, theme.
+    // value carries whether the chosen theme is dark or light.
     properties: {
       setting: SETTING_NAME,
       enabled: "boolean",
-      value: REVIEW_THEME_CHOICES,
+      value: REVIEW_COLOR_THEME_KINDS,
     },
   },
   review_opened: {
@@ -594,7 +613,10 @@ export const UI_TELEMETRY_EVENTS = {
     event: "review_diff_opened",
     properties: { kind: DIFF_OPENED_KIND, via: DIFF_OPENED_VIA },
   },
-  scratchpad_opened: { event: "review_scratchpad_opened", properties: {} },
+  diff_failed: {
+    event: "review_diff_failed",
+    properties: { reason: DIFF_FAILED_REASON, files: "number" },
+  },
   discord_clicked: {
     event: "review_discord_clicked",
     properties: { via: DISCORD_VIA },
@@ -613,7 +635,7 @@ export const UI_TELEMETRY_EVENTS = {
   },
   peek_resolve_failed: {
     event: "review_peek_resolve_failed",
-    properties: { root_kind: PEEK_ROOT_KIND },
+    properties: { root_kind: PEEK_ROOT_KIND, reason: PEEK_FAILURE_REASON },
   },
   review_deleted: {
     event: "review_review_deleted",
@@ -652,7 +674,11 @@ export const UI_TELEMETRY_EVENTS = {
   },
   new_whiteboard_started: {
     event: "review_new_whiteboard_started",
-    properties: { mode: RUN_MODE, embedded: "boolean", agent: askAgentIds },
+    properties: {
+      mode: NEW_WHITEBOARD_MODE,
+      embedded: "boolean",
+      agent: askAgentIds,
+    },
   },
   remote_host_installed: {
     event: "review_remote_host_installed",

package/dist/agent-cli-C6SPSII0.js

@@ -1,2 +0,0 @@
-import { n as runReviewAgentCli } from "./agent-cli-CThN7Q59.js";
-export { runReviewAgentCli };

package/dist/profile-CYPmvBoA.js

@@ -1,2 +0,0 @@
-import { t as openReviewProfile } from "./profile-DokFw782.js";
-export { openReviewProfile };

package/dist/runtime-CKiWhGrf.js

@@ -1,52 +0,0 @@
-import path from "node:path";
-import { spawn } from "node:child_process";
-//#region src/runtime.ts
-async function resolveReviewRoot(cwd, execFile = execFilePromise) {
-	const initialCwd = path.resolve(cwd);
-	try {
-		const { stdout } = await execFile("jj", ["root"], { cwd: initialCwd });
-		const root = stdout.trim();
-		if (root) return path.resolve(root);
-	} catch {}
-	try {
-		const { stdout } = await execFile("git", [
-			"-C",
-			initialCwd,
-			"rev-parse",
-			"--show-toplevel"
-		]);
-		const root = stdout.trim();
-		if (root) return path.resolve(root);
-	} catch {}
-	return initialCwd;
-}
-function execFilePromise(file, args, options = {}) {
-	return execFileUntraced(file, args, options);
-}
-function execFileUntraced(file, args, options = {}) {
-	return new Promise((resolve, reject) => {
-		const child = spawn(file, args, {
-			cwd: options.cwd,
-			stdio: [
-				"ignore",
-				"pipe",
-				"pipe"
-			]
-		});
-		let stdout = "";
-		let stderr = "";
-		child.stdout?.on("data", (chunk) => {
-			stdout += String(chunk);
-		});
-		child.stderr?.on("data", (chunk) => {
-			stderr += String(chunk);
-		});
-		child.on("error", reject);
-		child.on("exit", (code) => {
-			if (code === 0) resolve({ stdout });
-			else reject(new Error(stderr.trim() || `${file} exited with ${code}`));
-		});
-	});
-}
-//#endregion
-export { resolveReviewRoot as t };

package/instructions/scratchpad.md

@@ -1,23 +0,0 @@
-# Scratchpad
-
-The scratchpad is one document in Whiteboard that is not a session for any change. It has no target, base, head or lifecycle. You draw on it the way you would sketch an explanation on a whiteboard: a short paragraph, a sequence or flow diagram, a call tree, a code peek, and the smallest view that makes the point. The user reads it in the app and copies blocks back to you.
-
-Its id is fixed: `scratchpad`. While it is turned on in Whiteboard Settings it always exists; never create, rename, trash, delete or share it.
-
-## When to draw here
-
-- The user asks to be shown how something works, wants a picture of a flow, a call path, a data shape or a layout, or is thinking out loud with you before there is a concrete plan.
-- The explanation spans more than one file or more than one repository, or would be an ASCII diagram in chat.
-
-Answer in chat when one sentence or one code line does it. Do not use the scratchpad to review a change; author a session instead (`session_get_instructions({})`).
-
-## How
-
-1. `session_capabilities({})`. Draw only when `desktopAvailable` and `scratchpadEnabled` are true. Otherwise answer in chat; if the pad is off, say once that it can be turned on in Whiteboard Settings.
-2. Every source reference needs pins. For each repository you will quote, `session_register_repository({path})` for its `repositoryId`, and `git rev-parse HEAD` (or the commit the user is looking at) for a commit id. Put `pins: {repositoryId, head}` on each block that quotes code (`code_peek`, `sequence`, `flow_diagram`, `call_stack_diff`, `database_lens` and `markdown` with `review-source:` links); a step, frame, attachment or operation that quotes other commits than its block takes its own `pins`. Add `base` only when an anchor reads the base side. A reference without pins is rejected, since the scratchpad has none to lend.
-3. Read what you cite at those commits, for example `git show <head>:<path>` in the repository, so line numbers match the pins.
-4. Call `session_activity_begin` and pass the `activityId` it returns on each `session_edit` as you append blocks. Omitted placement puts the block at the top of the pad, and the response's `targetId` names it. A thought that spans several blocks reads top-down only if you insert it bottom-up (last block first) or give each following block `afterId` of the block you just inserted. Draw a diagram whole in one insert; fix one you drew earlier by patching its nodes, edges or steps by ID, and `replace` a block only when the whole picture was wrong. Each block's fields are in the Components section below; read `session_get_instructions({topic:"authoring"})` for choosing components. End the activity when finished.
-5. After your first insert in a session, `session_open({sessionId: "scratchpad"})` once so the pad is showing. Do not call it again for later edits; they appear live.
-6. In chat, say in one line what you drew. Do not repeat the diagram there.
-
-Keep it a log, not a document: the newest thought sits at the top, above older ones. Do not build sections, outlines or status markers unless the user asks for structure. When the user asks to clear the pad, `replace` or `remove` its blocks; history keeps what was there.

package/src/review-preferences.ts

@@ -1,88 +0,0 @@
-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/server/legacy-tutorial-cleanup.ts

@@ -1,38 +0,0 @@
-import { rm } from "node:fs/promises";
-import path from "node:path";
-
-import type { LocalReviewData } from "@review/review-api/local-data";
-import type { ReviewStore } from "@review/review-api/store";
-import { devReviewHome } from "@review/review-home-paths";
-
-/**
- * Earlier versions shipped a three-minute tutorial: a managed review over a
- * sample checkout under ~/.dev/tutorial. Whiteboard no longer has one, so
- * remove what an earlier version left behind. Best effort: a failure leaves
- * it for the next start.
- */
-export async function removeLegacyTutorial(input: {
-  store: ReviewStore;
-  data: LocalReviewData;
-  root?: string;
-}): Promise<void> {
-  const tutorialRoot = input.root ?? path.join(devReviewHome(), "tutorial");
-
-  try {
-    for (const reviewId of input.store.legacyTutorialIds())
-      await input.store.execute({ operation: { type: "delete", reviewId } });
-
-    for (const repository of input.store.repositories()) {
-      const relative = path.relative(tutorialRoot, repository.path);
-
-      if (relative && !relative.startsWith("..") && !path.isAbsolute(relative))
-        await input.data.forgetRepository(repository.id);
-    }
-
-    // Windows cannot delete a checkout while its Git reader or watchers
-    // hold it open, and handles can outlive their close briefly.
-    await rm(tutorialRoot, { recursive: true, force: true, maxRetries: 10 });
-  } catch (error) {
-    console.warn("[Whiteboard] Removing the old tutorial failed:", error);
-  }
-}