@dev.fast/whiteboard 0.3.3 → 0.3.4-preview.20261019.126

package/src/sharing/repository.ts

@@ -2,12 +2,25 @@ import { mkdir, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 
-import { gitAt } from "@dev.fast/local-vcs";
+import { type VcsArg, gitAt } from "@dev.fast/local-vcs";
 import { normalizeGitHubRemote } from "@dev.fast/review-share-protocol";
 import { type Pins, ReviewInputError } from "@review/review-api/document.js";
 
+/** A full commit id, SHA-1 or SHA-256. */
+export const COMMIT_ID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+
+/** Refuses anything but full commit ids, before any of them reaches git:
+ * a shared board's commits come from someone else, and one spelled as an
+ * option or a refspec would make git do something else. */
+export function assertCommitIds(commits: readonly string[]) {
+  if (!commits.every((commit) => COMMIT_ID.test(commit)))
+    throw new ReviewInputError(
+      "The shared whiteboard names a commit that isn't a full commit id.",
+    );
+}
+
 /** Keep credential helpers but prevent the calling shell from redirecting Git's object store. */
-export function sharedGit(cwd: string, args: string[]) {
+export function sharedGit(cwd: string, args: VcsArg[]) {
   const env = Object.fromEntries(
     Object.entries(process.env).filter(
       ([key]) =>
@@ -25,7 +38,7 @@ export function sharedGit(cwd: string, args: string[]) {
     cwd,
     ["-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", ...args],
     {
-      env: { ...env, GIT_TERMINAL_PROMPT: "0" },
+      env,
       timeout: 300_000,
     },
   );
@@ -46,18 +59,28 @@ function fetchError(stderr: string, publishing: boolean): ReviewInputError {
   );
 }
 
-/** Recipients need complete history; publication only checks that the commits exist. */
+/** Recipients need complete history; publication only checks that the commits exist.
+ * `commits` are other commits the board's references read at; a plan has
+ * only those. */
 export async function fetchPinnedRepository(
   root: string,
   url: string,
-  pins: Pick<Pins, "base" | "head">,
+  pins: Pick<Pins, "base" | "head"> | undefined,
   publishing = false,
+  commits: readonly string[] = [],
 ) {
-  if (
-    ![pins.base, pins.head].every((commit) =>
-      /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(commit),
-    )
-  )
+  // Each commit and the ref it is fetched to.
+  const named = [
+    ...(pins
+      ? [
+          { commit: pins.base, ref: "base" },
+          { commit: pins.head, ref: "head" },
+        ]
+      : []),
+    ...commits.map((commit) => ({ commit, ref: `commits/${commit}` })),
+  ];
+
+  if (!named.every(({ commit }) => COMMIT_ID.test(commit)))
     throw new ReviewInputError(
       "Sharing requires immutable base and head commits.",
     );
@@ -67,7 +90,7 @@ export async function fetchPinnedRepository(
   if (!publishing) {
     await sharedGit(root, ["config", "core.hooksPath", "/dev/null"]);
     await sharedGit(root, ["config", "core.fsmonitor", "false"]);
-    await sharedGit(root, ["remote", "add", "origin", url]);
+    await sharedGit(root, ["remote", "add", "origin", { remote: url }]);
   }
 
   // Branch refs make Git reject non-commit objects during the fetch itself.
@@ -79,9 +102,10 @@ export async function fetchPinnedRepository(
       "--no-tags",
       "--force",
       ...(publishing ? ["--depth=1", "--filter=tree:0"] : []),
-      publishing ? url : "origin",
-      `${pins.base}:${refs}/base`,
-      `${pins.head}:${refs}/head`,
+      { remote: publishing ? url : "origin" },
+      ...named.map(({ commit, ref }) => ({
+        refspec: { from: commit, to: `${refs}/${ref}` },
+      })),
     ]);
   } catch (error) {
     throw fetchError(
@@ -91,21 +115,104 @@ export async function fetchPinnedRepository(
   }
 
   if (!publishing)
-    for (const commit of [pins.base, pins.head])
-      await sharedGit(root, ["cat-file", "-e", `${commit}^{commit}`]);
+    for (const { commit } of named)
+      await sharedGit(root, ["cat-file", "-e", { rev: `${commit}^{commit}` }]);
+}
+
+/** Fetches the commits a shared board's links read at into a checkout of
+ * its repository, from its origin unless it has them, and keeps each under
+ * `refs/review/shared/<share>/<commit>`, so `git gc` can't prune one the
+ * board still quotes. */
+export async function fetchSharedCommits(
+  root: string,
+  commits: readonly string[],
+  share: string,
+) {
+  assertCommitIds(commits);
+
+  const ref = (commit: string) => `refs/review/shared/${share}/${commit}`;
+  const missing: string[] = [];
+
+  for (const commit of commits)
+    try {
+      await sharedGit(root, ["cat-file", "-e", { rev: `${commit}^{commit}` }]);
+      await sharedGit(root, ["update-ref", { ref: ref(commit) }, { commit }]);
+    } catch {
+      missing.push(commit);
+    }
+
+  if (!missing.length) return;
+
+  try {
+    await sharedGit(root, [
+      "fetch",
+      "--no-tags",
+      "origin",
+      ...missing.map((commit) => ({
+        refspec: { from: commit, to: ref(commit), force: true },
+      })),
+    ]);
+  } catch (error) {
+    throw fetchError(
+      error instanceof Error && "stderr" in error ? String(error.stderr) : "",
+      false,
+    );
+  }
+}
+
+/** Drops the refs `fetchSharedCommits` kept for a share, once the share is
+ * gone, so `git gc` can prune what only it quoted. */
+export async function forgetSharedCommits(root: string, share: string) {
+  const { stdout } = await sharedGit(root, [
+    "for-each-ref",
+    "--format=%(refname)",
+    { ref: `refs/review/shared/${share}/` },
+  ]);
+
+  for (const ref of stdout.split("\n").filter(Boolean))
+    await sharedGit(root, ["update-ref", "-d", { ref }]);
+}
+
+/** A managed clone of a repository's default branch, for a shared board
+ * with no pins whose repository the receiver has no checkout of. */
+export async function cloneSharedRepository(root: string, url: string) {
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  await sharedGit(root, ["init", "--quiet"]);
+  await sharedGit(root, ["config", "core.hooksPath", "/dev/null"]);
+  await sharedGit(root, ["config", "core.fsmonitor", "false"]);
+  await sharedGit(root, ["remote", "add", "origin", { remote: url }]);
+
+  try {
+    await sharedGit(root, ["fetch", "--no-tags", "origin", "HEAD"]);
+  } catch (error) {
+    throw fetchError(
+      error instanceof Error && "stderr" in error ? String(error.stderr) : "",
+      false,
+    );
+  }
+
+  await sharedGit(root, ["checkout", "--detach", "FETCH_HEAD"]);
 }
 
 export async function repositoryReady(
   root: string,
   pins: Pick<Pins, "base" | "head">,
+  commits: readonly string[] = [],
 ): Promise<boolean> {
+  if (
+    ![pins.base, pins.head, ...commits].every((commit) =>
+      COMMIT_ID.test(commit),
+    )
+  )
+    return false;
+
   try {
     const head = await sharedGit(root, ["rev-parse", "HEAD"]);
 
     if (head.stdout.trim() !== pins.head) return false;
 
-    for (const commit of [pins.base, pins.head])
-      await sharedGit(root, ["cat-file", "-e", `${commit}^{commit}`]);
+    for (const commit of [pins.base, pins.head, ...commits])
+      await sharedGit(root, ["cat-file", "-e", { rev: `${commit}^{commit}` }]);
 
     return true;
   } catch {
@@ -129,14 +236,15 @@ export async function readShareRepository(root: string) {
 
 export async function verifyShareRepository(
   root: string,
-  pins: Pins,
+  pins: Pins | undefined,
   repository?: { cloneUrl: string },
+  commits: readonly string[] = [],
 ) {
   const { cloneUrl } = repository ?? (await readShareRepository(root));
   const temporary = await mkdtemp(path.join(tmpdir(), "review-share-check-"));
 
   try {
-    await fetchPinnedRepository(temporary, cloneUrl, pins, true);
+    await fetchPinnedRepository(temporary, cloneUrl, pins, true, commits);
   } finally {
     await rm(temporary, { recursive: true, force: true });
   }

package/src/startup-trace.ts

@@ -221,9 +221,9 @@ if (traceEnabled) {
   // Every git/jj spawn inside @dev.fast/local-vcs becomes a `$ …` span under
   // whatever span is active in the caller's async context.
   setLocalVcsCommandObserver({
-    start({ file, args, cwd }) {
-      const handle = startSpan(commandSpanName(file, args), {
-        detail: commandDetail(file, args, cwd),
+    start({ tool, args, cwd }) {
+      const handle = startSpan(commandSpanName(tool, args), {
+        detail: commandDetail(tool, args, cwd),
       });
 
       return ({ ok }) => (ok ? handle.end() : handle.fail());

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

@@ -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,6 @@ export const SETTING_NAME = [
   "telemetry_enabled",
   "keymap",
   "software_map_enabled",
-  "scratchpad_enabled",
   "diffr_config",
   "theme",
   "ctrl_tab",
@@ -149,12 +156,8 @@ export const SETTING_NAME = [
 
 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 +249,7 @@ export const INSTALL_LOCATION = [
 
 export const DIFF_OPENED_VIA = [
   "topbar",
+  "sidebar",
   "lens",
   "locate",
   "file_picker",
@@ -254,6 +258,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 +290,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;
 
@@ -594,7 +609,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 +631,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 +670,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-DeCrUC2s.js

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

package/dist/profile-Cz7L781D.js

@@ -1,2 +0,0 @@
-import { t as openReviewProfile } from "./profile-DaqmODhc.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;
-}