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

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

@@ -0,0 +1,154 @@
+import type {
+  SoftwareDataStoreFieldSchema,
+  SoftwareModelInput,
+} from "@review/software-map-model.js";
+import { z } from "zod";
+
+// Decode the existing map authoring format at the HTTP boundary. The existing
+// defineSoftwareMap normalizer remains responsible for relationships/coverage.
+const label = z.string().trim().min(1);
+
+const nonEmptyStringSchema = z
+  .string()
+  .refine((value) => value.trim().length > 0, "Must not be empty");
+
+const optionalNonEmptyStringSchema = nonEmptyStringSchema.optional();
+
+const softwareDataStoreForeignKeyRefSchema = z.union([
+  nonEmptyStringSchema,
+  z.strictObject({
+    store: optionalNonEmptyStringSchema,
+    table: nonEmptyStringSchema,
+    field: nonEmptyStringSchema,
+    label: optionalNonEmptyStringSchema,
+    cardinality: z.enum(["one-to-one", "many-to-one"]).optional(),
+    onDelete: optionalNonEmptyStringSchema,
+    onUpdate: optionalNonEmptyStringSchema,
+  }),
+]);
+
+const softwareDataStoreFieldSchema: z.ZodType<SoftwareDataStoreFieldSchema> =
+  z.lazy(() =>
+    z.record(
+      nonEmptyStringSchema,
+      z.union([
+        z.strictObject({
+          type: nonEmptyStringSchema,
+          example: z.unknown().optional(),
+          pk: z.boolean().optional(),
+          fk: softwareDataStoreForeignKeyRefSchema.optional(),
+          schema: softwareDataStoreFieldSchema.optional(),
+        }),
+        softwareDataStoreFieldSchema,
+      ]),
+    ),
+  );
+
+const softwareDataStoreCollectionInputSchema = z.strictObject({
+  label: optionalNonEmptyStringSchema,
+  key: optionalNonEmptyStringSchema,
+  schema: softwareDataStoreFieldSchema,
+});
+
+const endpoint = label.describe(
+  'Existing element or data-store schema path. Resolution order: relative to the containing element, relative to its parent, then full path. "." means the containing element. At model root use full paths. Cross-level endpoints are allowed.',
+);
+
+const range = z.strictObject({
+  fromLine: z.number().int().positive(),
+  toLine: z.number().int().positive(),
+});
+
+const relationship = z.union([
+  z.strictObject({
+    kind: z.literal("call"),
+    from: endpoint,
+    to: endpoint,
+    label: z.string().optional(),
+    description: z.string().optional(),
+    nthCallSite: z.number().int().nonnegative().optional(),
+  }),
+  z.strictObject({
+    kind: z.literal("semantic"),
+    from: endpoint,
+    to: endpoint,
+    label: z.string().optional(),
+    description: z.string().optional(),
+    semanticKind: z.string().optional(),
+    sourceRanges: z.array(range).optional(),
+  }),
+]);
+
+const base = z.strictObject({
+  id: label
+    .optional()
+    .describe(
+      "Local ID, unique among siblings; defaults to the object key (or array index). Give array entries explicit IDs for stable paths. Nesting builds the full path: api under app becomes app.api. Do not repeat the parent path in the ID.",
+    ),
+  label: label.optional(),
+  description: z.string().optional(),
+  changeStatus: z
+    .enum(["added", "removed", "modified", "unchanged"])
+    .optional(),
+  relationships: z
+    .array(relationship)
+    .optional()
+    .describe(
+      "Relationships scoped to this element. Endpoints may use relative names or full paths; they need not be direct children.",
+    ),
+});
+
+const coverage = z.strictObject({
+  files: z
+    .array(
+      z.union([
+        label,
+        z.strictObject({ path: label, ranges: z.array(range).optional() }),
+      ]),
+    )
+    .optional(),
+  globs: z.array(label).optional(),
+});
+
+const collection = <T extends z.ZodType>(schema: T) =>
+  z.union([z.record(label, schema), z.array(schema)]);
+
+const code = base.extend({
+  sourceRanges: z.array(range.extend({ file: label })).optional(),
+});
+
+const component = base.extend({
+  coverage: coverage.optional(),
+  codeElements: collection(code).optional(),
+});
+
+const container = base.extend({
+  coverage: coverage.optional(),
+  components: collection(component).optional(),
+});
+
+const store = container.extend({
+  kind: z
+    .enum(["database", "objectStore", "bucket", "artifactStore", "fileStore"])
+    .optional(),
+  tables: z.record(label, softwareDataStoreCollectionInputSchema).optional(),
+  documents: z.record(label, softwareDataStoreCollectionInputSchema).optional(),
+});
+
+const system = base.extend({
+  coverage: coverage.optional(),
+  external: z.boolean().optional(),
+  containers: collection(container).optional(),
+  dataStores: collection(store).optional(),
+});
+
+export const mapInputSchema: z.ZodType<SoftwareModelInput> = z.strictObject({
+  people: collection(base).optional(),
+  systems: collection(system).optional(),
+  relationships: z
+    .array(relationship)
+    .optional()
+    .describe(
+      "Model-level relationships, including people and systems. Use full endpoint paths; external systems are systems with external: true.",
+    ),
+});

package/src/review-api/mcp-client-agent.ts

@@ -0,0 +1,32 @@
+import type { ReviewSessionAgent } from "@review/ui-telemetry-events.js";
+
+/**
+ * The agent behind an MCP client, from the name it sends in `initialize`.
+ * Names seen on 2026-10-02: Claude Code `claude-code`, Codex
+ * `codex-mcp-client`, the Cursor CLI `Cursor`, OpenCode `opencode`, Pi `pi`
+ * and Oh My Pi `omp-coding-agent`. Undefined for
+ * a client this does not recognize, so the caller can fall back to the
+ * session environment. Codex strips its `CODEX_*` variables from the MCP
+ * server's environment, so for Codex the handshake is the only signal.
+ */
+export function mcpClientAgent(
+  name: string | undefined,
+): ReviewSessionAgent | undefined {
+  const normalized = name?.trim().toLowerCase();
+
+  if (!normalized) return undefined;
+
+  if (normalized.startsWith("codex")) return "codex";
+
+  if (normalized.startsWith("claude")) return "claude";
+
+  if (normalized.startsWith("cursor")) return "cursor";
+
+  if (normalized.startsWith("opencode")) return "opencode";
+
+  if (/^omp(?:$|[-_ ])/.test(normalized)) return "omp";
+
+  if (/^pi(?:$|[-_ ])/.test(normalized)) return "pi";
+
+  return undefined;
+}

package/src/review-api/mcp.ts

@@ -0,0 +1,240 @@
+import type { Readable, Writable } from "node:stream";
+
+import type { JsonValue } from "@dev.fast/json";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import type { ReviewToolCall } from "@review/review-telemetry.js";
+import type { ReviewSessionAgent } from "@review/ui-telemetry-events.js";
+
+import {
+  type AuthoringTool,
+  type ConnectedReview,
+  toolResultText,
+} from "./agent-client.js";
+import { authoringTools } from "./authoring-tools.js";
+import type { ReviewApiClient } from "./client.js";
+import { ReviewApiError } from "./client.js";
+import { ReviewInputError } from "./input-error.js";
+import { mcpClientAgent } from "./mcp-client-agent.js";
+import { callPublicTool, publicTool } from "./public-tools.js";
+import { RECOVERY } from "./recovery.js";
+import { REVIEW_STATUS_TOOL } from "./status-tool.js";
+import { type ToolFailure, toolFailure } from "./tool-failure.js";
+
+// Some hosts ignore tools/list_changed, so the agent itself has to reload.
+const RELOAD_TOOLS =
+  "Whiteboard is running now, but this session listed Whiteboard's tools before it started, so you may see only session_get_instructions. Before authoring, reload the `whiteboard` MCP server's tools (reconnect it in your agent, or start a new agent session). If you can already see tools such as session_create, carry on.";
+
+function mcpAuthoringGuidance(context: {
+  scratchpadAvailable: boolean;
+  traceEnabled: boolean;
+}): string {
+  return [
+    "Whiteboard explains code in documents the user reads in Whiteboard Desktop. Call session_get_instructions before creating or editing a Whiteboard and follow it. Read session_capabilities before authoring; session_create opens the new review in Desktop when it is available, so call session_open only for an existing review, and generate software maps only when softwareMapEnabled is true. When the user asks for a Whiteboard or to use Whiteboard (for example to review a branch, a change or a pull request, or to explain a system in Whiteboard), author a Whiteboard with the default topic.",
+    ...(context.scratchpadAvailable
+      ? [
+          'When the user asks in conversation to be shown how code works or wants a diagram, without asking for a Whiteboard, call session_capabilities; if it reports scratchpadEnabled and desktopAvailable, draw on the Whiteboard scratchpad rather than answering only in chat, starting with session_get_instructions({topic:"scratchpad"}).',
+        ]
+      : []),
+    ...(context.traceEnabled
+      ? [
+          'For why code exists, what an agent was thinking, or whether an agent solved something before, call session_get_instructions({topic:"trace-archaeology"}).',
+        ]
+      : []),
+    "Never read or write Whiteboard files or SQL.",
+  ].join(" ");
+}
+
+export async function serveReviewMcp(
+  /** Connects to `key` once one is latched, else selects one, as `agentKind`. */
+  connect: (
+    key?: string,
+    agentKind?: ReviewSessionAgent,
+  ) => Promise<ConnectedReview>,
+  stdin: Readable,
+  stdout: Writable,
+  stderr: Writable = process.stderr,
+  traceEnabled = false,
+  /** What whiteboard_status reports when the Desktop cannot be reached, and why. */
+  offlineStatus?: (problem: string) => Promise<JsonValue>,
+  onToolCall?: (call: ReviewToolCall) => Promise<void> | void,
+  /** The agent from the session environment, when the handshake names none. */
+  environmentAgent?: ReviewSessionAgent,
+) {
+  const instructionsTool = {
+    ...authoringTools(false, traceEnabled).find(
+      (tool) => tool.name === "review_get_instructions",
+    )!,
+    name: "session_get_instructions",
+  };
+
+  const server = new Server(
+    { name: "whiteboard", version: "1.0.0" },
+    {
+      capabilities: { tools: { listChanged: true } },
+    },
+  );
+
+  // Hosts list tools once, right after initialize, often before Desktop is up.
+  // Answer from the last catalog (or none) instead of failing, and announce a
+  // changed list once the host can be reached.
+  let catalog: AuthoringTool[] = [];
+  let announceCatalog = false;
+  let listedWhileDown = false;
+  // One session follows one instance key, through that Desktop's restarts;
+  // it never hops to another key once others start.
+  let latched: string | undefined;
+
+  const agentKind = () =>
+    mcpClientAgent(server.getClientVersion()?.name) ?? environmentAgent;
+
+  const load = async (signal?: AbortSignal) => {
+    const { client, instance } = await connect(latched, agentKind());
+    latched ??= instance?.key;
+
+    catalog = (await client.read<AuthoringTool[]>("/authoring", signal)).map(
+      publicTool,
+    );
+
+    if (announceCatalog) {
+      announceCatalog = false;
+      void server.sendToolListChanged().catch(() => {});
+    }
+
+    return { client, tools: catalog };
+  };
+
+  server.setRequestHandler(ListToolsRequestSchema, async (_request, extra) => {
+    let tools = catalog;
+
+    try {
+      ({ tools } = await load(extra.signal));
+      listedWhileDown = false;
+    } catch (error) {
+      announceCatalog = true;
+      listedWhileDown = true;
+      stderr.write(
+        `whiteboard mcp: ${error instanceof Error ? error.message : String(error)}\n`,
+      );
+    }
+
+    const always = [instructionsTool, REVIEW_STATUS_TOOL].map(
+      (fallback) =>
+        tools.find((tool) => tool.name === fallback.name) ?? fallback,
+    );
+
+    return {
+      tools: [...always, ...tools.filter((tool) => !always.includes(tool))].map(
+        ({ name, description, inputSchema }) => ({
+          name,
+          // Some clients prepend server instructions to every tool. Keep shared
+          // guidance on the discovery tool instead, including before Desktop starts.
+          description:
+            name === instructionsTool.name
+              ? `${mcpAuthoringGuidance({ scratchpadAvailable: true, traceEnabled })}\n\n${description}`
+              : description,
+          inputSchema,
+        }),
+      ),
+    };
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    const startedAt = Date.now();
+    // The requested name is agent input; only a catalog name is reported.
+    let tool: AuthoringTool | undefined;
+
+    let phase: "connect" | "call" = "connect";
+
+    const report = (failure?: ToolFailure) =>
+      void onToolCall?.({
+        tool: tool?.name ?? "other",
+        via: "mcp",
+        ok: !failure,
+        durationMs: Date.now() - startedAt,
+        agentKind: agentKind(),
+        ...failure,
+      });
+
+    try {
+      let client: ReviewApiClient;
+      let tools: AuthoringTool[];
+
+      try {
+        ({ client, tools } = await load(extra.signal));
+      } catch (error) {
+        announceCatalog = true;
+
+        if (
+          request.params.name === instructionsTool.name &&
+          !(error instanceof ReviewApiError)
+        )
+          return { content: [{ type: "text" as const, text: RECOVERY }] };
+
+        if (request.params.name === REVIEW_STATUS_TOOL.name && offlineStatus)
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: JSON.stringify(
+                  await offlineStatus(
+                    error instanceof Error ? error.message : String(error),
+                  ),
+                ),
+              },
+            ],
+          };
+
+        throw error;
+      }
+
+      phase = "call";
+      tool = tools.find((tool) => tool.name === request.params.name);
+
+      if (!tool)
+        throw new ReviewInputError(
+          `Unknown Whiteboard tool: ${request.params.name}`,
+        );
+
+      const result = await callPublicTool(
+        client,
+        tool,
+        request.params.arguments ?? {},
+        extra.signal,
+      );
+
+      const text = toolResultText(tool, result);
+      report();
+
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              listedWhileDown && tool.name === instructionsTool.name
+                ? `${RELOAD_TOOLS}\n\n${text}`
+                : text,
+          },
+        ],
+      };
+    } catch (error) {
+      report(toolFailure(error, phase));
+
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: error instanceof Error ? error.message : String(error),
+          },
+        ],
+      };
+    }
+  });
+  await server.connect(new StdioServerTransport(stdin, stdout));
+
+  return server;
+}

package/src/review-api/origin.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+
+import type { Snapshot } from "./store.js";
+
+export const pullRequestUrl = z
+  .string()
+  .regex(
+    /^https:\/\/[a-z0-9.-]+\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/pull\/[1-9]\d*$/,
+    "Use a canonical GitHub PR URL: https://github.com/owner/repository/pull/123, or the same path on a GitHub Enterprise host.",
+  )
+  .refine(
+    (url) => Number.isSafeInteger(Number(url.split("/").at(-1))),
+    "PR number is too large.",
+  );
+
+/** One key per PR: GitHub owner and repository names are case-insensitive,
+ * and the URL pattern admits only ASCII, so lowercasing is canonical. */
+export function pullRequestKey(url: string): string {
+  return url.toLowerCase();
+}
+
+/** Omission preserves identity; null detaches it without changing import metadata. */
+export function setPullRequest(
+  snapshot: Pick<Snapshot, "origin">,
+  url: string | null | undefined,
+) {
+  if (url === undefined) return;
+
+  if (url === null) {
+    if (snapshot.origin) {
+      delete snapshot.origin.pullRequestUrl;
+      delete snapshot.origin.pullRequestNumber;
+    }
+
+    return;
+  }
+
+  snapshot.origin = {
+    ...snapshot.origin,
+    pullRequestUrl: url,
+    pullRequestNumber: Number(url.split("/").at(-1)),
+  };
+}

package/src/review-api/profile.ts

@@ -0,0 +1,146 @@
+import { access, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+
+import { withFileLock } from "@dev.fast/trace-core";
+
+import { openLocalReviewStore } from "./local-data.js";
+import { initializeReviewStoreSchema } from "./store-schema.js";
+
+const lockOptions = {
+  retryMs: 50,
+  timeoutMs: 10_000,
+  staleMs: Infinity,
+  unownedGraceMs: 1_000,
+};
+
+export async function openReviewProfile(
+  home: string,
+  options: { manageWorkspaces: boolean },
+) {
+  await mkdir(home, { recursive: true, mode: 0o700 });
+
+  const outcome = await withFileLock(
+    path.join(home, ".review-profile-startup"),
+    lockOptions,
+    async () => {
+      for (const source of [
+        path.join(home, "review-server", "reviews.db"),
+        path.join(home, "reviews.db"),
+      ])
+        await importHeadlessStore(home, source);
+
+      return openLocalReviewStore(path.join(home, "review-api.db"), options);
+    },
+  );
+
+  if (!outcome.acquired)
+    throw new Error(
+      "Another Review process is initializing this profile. Retry shortly.",
+    );
+
+  return outcome.result;
+}
+
+/** Preserve preview headless IDs, history and resources; leave originals as backups. */
+async function importHeadlessStore(home: string, source: string) {
+  try {
+    await access(source);
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT")
+      return;
+    throw error;
+  }
+
+  const database = new DatabaseSync(path.join(home, "review-api.db"), {
+    timeout: 5000,
+  });
+
+  try {
+    database.exec(
+      "PRAGMA foreign_keys=ON; CREATE TABLE IF NOT EXISTS headless_imports(path TEXT PRIMARY KEY)",
+    );
+
+    if (
+      database
+        .prepare("SELECT 1 FROM headless_imports WHERE path=?")
+        .get(source)
+    )
+      return;
+
+    initializeReviewStoreSchema(database);
+
+    const outcome = await withFileLock(
+      path.join(path.dirname(source), "server.lock"),
+      { ...lockOptions, timeoutMs: 0 },
+      async () => {
+        database.prepare("ATTACH DATABASE ? AS headless").run(source);
+        database.exec("BEGIN IMMEDIATE");
+
+        try {
+          if (
+            database
+              .prepare(
+                "SELECT 1 FROM headless.reviews s JOIN reviews t ON s.id=t.id LIMIT 1",
+              )
+              .get()
+          )
+            throw new Error(
+              `Cannot merge ${source}: the shared store already contains one of its review IDs. Both databases are unchanged.`,
+            );
+          database.exec(`
+          INSERT INTO repositories SELECT s.* FROM headless.repositories s WHERE NOT EXISTS (SELECT 1 FROM repositories t WHERE t.path=s.path);
+          CREATE TEMP TABLE repository_ids AS SELECT s.id old_id,t.id new_id FROM headless.repositories s JOIN repositories t ON s.path=t.path;
+        `);
+
+          if (
+            database
+              .prepare(
+                `SELECT 1 FROM headless.versions s LEFT JOIN repository_ids r ON json_extract(s.snapshot,'$.pins.repositoryId')=r.old_id WHERE r.old_id IS NULL LIMIT 1`,
+              )
+              .get()
+          )
+            throw new Error(
+              `Cannot merge ${source}: a version refers to an unregistered repository. Both databases are unchanged.`,
+            );
+
+          if (
+            database
+              .prepare(`SELECT 1 FROM headless.resources s JOIN resources t ON s.id=t.id JOIN repository_ids r ON s.repository_id=r.old_id
+          WHERE t.repository_id!=r.new_id OR t.kind!=s.kind OR t.mime_type!=s.mime_type OR t.data IS NOT s.data LIMIT 1`)
+              .get()
+          )
+            throw new Error(
+              `Cannot merge ${source}: a resource ID has different content. Both databases are unchanged.`,
+            );
+
+          database.exec(`
+          INSERT OR IGNORE INTO resources SELECT s.id,r.new_id,s.kind,s.mime_type,s.data FROM headless.resources s JOIN repository_ids r ON s.repository_id=r.old_id;
+          INSERT INTO reviews SELECT * FROM headless.reviews;
+          INSERT INTO versions SELECT s.review_id,s.version,
+            CASE WHEN json_type(s.snapshot,'$.target')='object'
+              THEN json_set(s.snapshot,'$.pins.repositoryId',r.new_id,'$.target.repositoryId',r.new_id)
+              ELSE json_set(s.snapshot,'$.pins.repositoryId',r.new_id) END
+            FROM headless.versions s JOIN repository_ids r ON json_extract(s.snapshot,'$.pins.repositoryId')=r.old_id;
+          INSERT INTO review_attention SELECT * FROM headless.review_attention;
+        `);
+
+          database
+            .prepare("INSERT INTO headless_imports VALUES(?)")
+            .run(source);
+          database.exec("COMMIT");
+        } catch (error) {
+          database.exec("ROLLBACK");
+          throw error;
+        }
+      },
+    );
+
+    if (!outcome.acquired)
+      throw new Error(
+        `Stop the old headless server using ${path.dirname(source)}, then retry. Its reviews will be moved into the shared profile automatically.`,
+      );
+  } finally {
+    database.close();
+  }
+}