pmx-canvas 0.1.36 → 0.2.1

package/src/server/operations/ops/query.ts

@@ -0,0 +1,281 @@
+/**
+ * Slice 3 operations (plan-005, migration item 4): pin.set / search /
+ * history.get / canvas.undo / canvas.redo / spatial.get / summary.get.
+ *
+ * Event notes (matching the legacy HTTP handlers exactly):
+ * - pin.set: legacy POST /api/canvas/context-pins emitted ONLY
+ *   context-pins-changed (no canvas-layout-update), so mutates: false with a
+ *   manual ctx.emit. The injected emitter adds the sessionId/timestamp fields
+ *   the legacy handler set explicitly. (The SDK's setContextPins emits a
+ *   layout update instead — that local/remote drift is erased here in favor of
+ *   the HTTP wire behavior.)
+ * - canvas.undo / canvas.redo: legacy handlers emitted canvas-viewport-update
+ *   then canvas-layout-update only after an entry was actually undone/redone,
+ *   so mutates: false with conditional manual emits. (The SDK's undo/redo also
+ *   emit ax-state-changed; that was never part of the HTTP wire and the SDK
+ *   methods are untouched.)
+ *
+ * This module must never import server.ts or index.ts.
+ */
+import { z } from 'zod';
+import { canvasState } from '../../canvas-state.js';
+import {
+  setCanvasContextPins,
+  syncCanvasRuntimeBackends,
+} from '../../canvas-operations.js';
+import { buildCanvasSummary } from '../../canvas-serialization.js';
+import { mutationHistory } from '../../mutation-history.js';
+import { buildSpatialContext, searchNodes } from '../../spatial-analysis.js';
+import { defineOperation, type Operation, type OperationMcpToolHost } from '../types.js';
+import { isRecord } from './nodes.js';
+
+// ── pin.set ───────────────────────────────────────────────────
+
+/** Legacy server.ts handleContextPinsUpdate capped the requested list at 20. */
+const MAX_PINS = 20;
+
+const pinShape = {
+  nodeIds: z.unknown().optional().describe('Array of node IDs to pin'),
+  mode: z.unknown().optional().describe('set: replace all pins, add: add to existing pins, remove: unpin these nodes (default: set)'),
+};
+
+const pinSchema = z.looseObject(pinShape);
+
+const pinOperation = defineOperation<z.infer<typeof pinSchema>, Record<string, unknown>>({
+  name: 'pin.set',
+  mutates: false,
+  input: pinSchema,
+  inputShape: pinShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/context-pins',
+  },
+  mcp: {
+    toolName: 'canvas_pin_nodes',
+    description: 'Pin nodes to include them in the agent context. Pinned nodes appear in the canvas://pinned-context resource. The human can also pin nodes by clicking in the browser.',
+    extraShape: {
+      nodeIds: z.array(z.string()).describe('Array of node IDs to pin'),
+      mode: z.enum(['set', 'add', 'remove']).optional()
+        .describe('set: replace all pins, add: add to existing pins, remove: unpin these nodes (default: set)'),
+    },
+    // The wire body is { ok, count } (legacy HTTP shape); the tool reports the
+    // resulting pin list, so re-read it from the host. (Legacy RemoteCanvasAccess
+    // computed the list client-side; the server state is authoritative now.)
+    formatResult: async (_result, _input, host) => ({
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify({ ok: true, pinnedNodeIds: await host.getPinnedNodeIds() }),
+      }],
+    }),
+  },
+  handler: (input, ctx) => {
+    const body: Record<string, unknown> = input;
+    const mode = body.mode === 'add' || body.mode === 'remove' ? body.mode : 'set';
+    const nodeIds = Array.isArray(body.nodeIds)
+      ? body.nodeIds.filter((id): id is string => typeof id === 'string')
+      : [];
+    // Legacy 'set' capped at MAX_PINS BEFORE setCanvasContextPins dedupes —
+    // replicated as-is. add/remove (formerly client-side in the MCP access
+    // layer) pass through; setCanvasContextPins normalizes them.
+    const result = setCanvasContextPins(mode === 'set' ? nodeIds.slice(0, MAX_PINS) : nodeIds, mode);
+    ctx.emit('context-pins-changed', { count: result.count, nodeIds: result.nodeIds });
+    return { ok: true, count: result.count };
+  },
+});
+
+// ── search ────────────────────────────────────────────────────
+
+const searchShape = {
+  q: z.unknown().optional().describe('Search query — matches against node titles, content, and file paths'),
+  limit: z.unknown().optional().describe('Max results to return (default: 10). Applied by the MCP tool only; the HTTP route returns all matches.'),
+};
+
+const searchSchema = z.looseObject(searchShape);
+
+const searchOperation = defineOperation<z.infer<typeof searchSchema>, Record<string, unknown>>({
+  name: 'search',
+  mutates: false,
+  input: searchSchema,
+  inputShape: searchShape,
+  http: {
+    method: 'GET',
+    path: '/api/canvas/search',
+  },
+  mcp: {
+    toolName: 'canvas_search',
+    description: 'Search for nodes by title or content keywords. Returns matching nodes ranked by relevance with snippets. Much faster than reading the full layout when you need to find specific nodes.',
+    extraShape: {
+      query: z.string().describe('Search query — matches against node titles, content, and file paths'),
+      limit: z.number().optional().describe('Max results to return (default: 10)'),
+    },
+    // The HTTP route only reads ?q= (legacy behavior); map the MCP-facing
+    // `query` arg onto it. The limit cap stays MCP-side, like the legacy tool.
+    buildInput: (input) => ({ q: typeof input.query === 'string' ? input.query : '' }),
+    formatResult: (result, input) => {
+      const body = isRecord(result) ? result : {};
+      const results = Array.isArray(body.results) ? body.results : [];
+      const limit = typeof input.limit === 'number' ? input.limit : 10;
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            query: input.query,
+            resultCount: results.length,
+            results: results.slice(0, limit),
+          }, null, 2),
+        }],
+      };
+    },
+  },
+  handler: (input) => {
+    const q = typeof input.q === 'string' ? input.q : '';
+    if (!q.trim()) {
+      return { results: [], query: q };
+    }
+    return { results: searchNodes(canvasState.getLayout().nodes, q), query: q };
+  },
+});
+
+// ── history.get (HTTP/CLI only — canvas://history stays a resource) ──
+
+const historyGetShape = {};
+
+const historyGetSchema = z.looseObject(historyGetShape);
+
+const historyGetOperation = defineOperation<z.infer<typeof historyGetSchema>, Record<string, unknown>>({
+  name: 'history.get',
+  mutates: false,
+  input: historyGetSchema,
+  inputShape: historyGetShape,
+  http: {
+    method: 'GET',
+    path: '/api/canvas/history',
+  },
+  handler: () => ({
+    text: mutationHistory.toHumanReadable(),
+    entries: mutationHistory.getSummaries(),
+    canUndo: mutationHistory.canUndo(),
+    canRedo: mutationHistory.canRedo(),
+  }),
+});
+
+// ── canvas.undo / canvas.redo ─────────────────────────────────
+
+async function formatUndoRedoResult(result: unknown, host: OperationMcpToolHost) {
+  // Legacy MCP tools appended canUndo/canRedo from a follow-up history read.
+  const history = await host.invoker().invoke('history.get', {});
+  const historyBody = isRecord(history) ? history : {};
+  const body = isRecord(result) ? result : {};
+  return {
+    content: [{
+      type: 'text' as const,
+      text: JSON.stringify({ ...body, canUndo: historyBody.canUndo, canRedo: historyBody.canRedo }),
+    }],
+  };
+}
+
+const undoRedoShape = {};
+
+const undoRedoSchema = z.looseObject(undoRedoShape);
+
+const undoOperation = defineOperation<z.infer<typeof undoRedoSchema>, Record<string, unknown>>({
+  name: 'canvas.undo',
+  mutates: false,
+  input: undoRedoSchema,
+  inputShape: undoRedoShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/undo',
+  },
+  mcp: {
+    toolName: 'canvas_undo',
+    description: 'Undo the last canvas mutation. Returns a description of what was undone. Use this to backtrack when an approach is wrong — explore without fear.',
+    formatResult: (result, _input, host) => formatUndoRedoResult(result, host),
+  },
+  handler: async (_input, ctx) => {
+    const entry = mutationHistory.undo();
+    if (!entry) return { ok: false, description: 'Nothing to undo' };
+    await syncCanvasRuntimeBackends();
+    ctx.emit('canvas-viewport-update', { viewport: canvasState.viewport });
+    ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
+    return { ok: true, description: `Undid: ${entry.description}` };
+  },
+});
+
+const redoOperation = defineOperation<z.infer<typeof undoRedoSchema>, Record<string, unknown>>({
+  name: 'canvas.redo',
+  mutates: false,
+  input: undoRedoSchema,
+  inputShape: undoRedoShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/redo',
+  },
+  mcp: {
+    toolName: 'canvas_redo',
+    description: 'Redo the last undone canvas mutation. Use after undo to re-apply a change.',
+    formatResult: (result, _input, host) => formatUndoRedoResult(result, host),
+  },
+  handler: async (_input, ctx) => {
+    const entry = mutationHistory.redo();
+    if (!entry) return { ok: false, description: 'Nothing to redo' };
+    await syncCanvasRuntimeBackends();
+    ctx.emit('canvas-viewport-update', { viewport: canvasState.viewport });
+    ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
+    return { ok: true, description: `Redid: ${entry.description}` };
+  },
+});
+
+// ── spatial.get (HTTP only — canvas://spatial-context stays a resource) ──
+
+const spatialGetShape = {};
+
+const spatialGetSchema = z.looseObject(spatialGetShape);
+
+const spatialGetOperation = defineOperation<z.infer<typeof spatialGetSchema>, Record<string, unknown>>({
+  name: 'spatial.get',
+  mutates: false,
+  input: spatialGetSchema,
+  inputShape: spatialGetShape,
+  http: {
+    method: 'GET',
+    path: '/api/canvas/spatial-context',
+  },
+  handler: () => {
+    const layout = canvasState.getLayout();
+    return buildSpatialContext(
+      layout.nodes,
+      layout.edges,
+      canvasState.contextPinnedNodeIds,
+      layout.annotations,
+    ) as unknown as Record<string, unknown>;
+  },
+});
+
+// ── summary.get (HTTP only — canvas://summary stays a resource) ──
+
+const summaryGetShape = {};
+
+const summaryGetSchema = z.looseObject(summaryGetShape);
+
+const summaryGetOperation = defineOperation<z.infer<typeof summaryGetSchema>, Record<string, unknown>>({
+  name: 'summary.get',
+  mutates: false,
+  input: summaryGetSchema,
+  inputShape: summaryGetShape,
+  http: {
+    method: 'GET',
+    path: '/api/canvas/summary',
+  },
+  handler: () => buildCanvasSummary() as unknown as Record<string, unknown>,
+});
+
+export const queryOperations: Operation[] = [
+  pinOperation,
+  searchOperation,
+  historyGetOperation,
+  undoOperation,
+  redoOperation,
+  spatialGetOperation,
+  summaryGetOperation,
+];

package/src/server/operations/ops/snapshots.ts

@@ -0,0 +1,366 @@
+/**
+ * Slice 3 operations (plan-005, migration item 5): snapshot.list /
+ * snapshot.save / snapshot.gc / snapshot.diff (+ query-param variant) /
+ * snapshot.restore / snapshot.delete.
+ *
+ * Wire notes:
+ * - snapshot.list serves the bare-array body (tests/e2e clearSnapshots reads
+ *   GET /api/canvas/snapshots?all=true and expects an array, not an envelope).
+ * - snapshot.restore relies on the DEFERRED canvas-layout-update that
+ *   restoreCanvasSnapshot itself schedules via setCanvasLayoutUpdateEmitter
+ *   once async ext-app rehydration finishes. The handler must not emit that
+ *   frame; `mutates: true` produces only the single immediate frame the legacy
+ *   route broadcast.
+ * - Legacy save/restore/delete error responses were plain-text
+ *   (responseText); they are now the registry's JSON `{ ok:false, error }`
+ *   envelope (save's unreachable disk-failure case also moves 500 → 400).
+ *
+ * Route-order note: snapshot.gc (POST /api/canvas/snapshots/gc) MUST be
+ * registered before snapshot.restore (POST /api/canvas/snapshots/:id) — the
+ * dispatcher checks routes in registration order and ':id' would otherwise
+ * swallow the literal 'gc' segment, exactly like the legacy if-chain ordering.
+ *
+ * This module must never import server.ts or index.ts.
+ */
+import { z } from 'zod';
+import { canvasState } from '../../canvas-state.js';
+import {
+  deleteCanvasSnapshot,
+  gcCanvasSnapshots,
+  listCanvasSnapshots,
+  restoreCanvasSnapshot,
+  saveCanvasSnapshot,
+} from '../../canvas-operations.js';
+import { diffLayouts, formatDiff } from '../../mutation-history.js';
+import { defineOperation, OperationError, type Operation } from '../types.js';
+import { isRecord } from './nodes.js';
+
+/** Legacy server.ts parsePositiveIntegerParam, tolerant of in-process numbers. */
+function parsePositiveIntegerParam(value: unknown): number | undefined {
+  if (typeof value !== 'string' && typeof value !== 'number') return undefined;
+  const text = String(value);
+  if (!text) return undefined;
+  const parsed = Number(text);
+  if (!Number.isFinite(parsed) || parsed <= 0) return undefined;
+  return Math.floor(parsed);
+}
+
+// ── snapshot.list ─────────────────────────────────────────────
+
+const snapshotListShape = {
+  limit: z.unknown().optional().describe('Maximum snapshots to return (default: 20)'),
+  q: z.unknown().optional().describe('Query alias used by the HTTP/CLI surface'),
+  query: z.unknown().optional().describe('Optional case-insensitive ID/name filter'),
+  before: z.unknown().optional().describe('Only return snapshots created at or before this ISO timestamp'),
+  after: z.unknown().optional().describe('Only return snapshots created at or after this ISO timestamp'),
+  all: z.unknown().optional().describe('Return all snapshots instead of the default limit'),
+};
+
+const snapshotListSchema = z.looseObject(snapshotListShape);
+
+const snapshotListOperation = defineOperation<z.infer<typeof snapshotListSchema>, unknown>({
+  name: 'snapshot.list',
+  mutates: false,
+  input: snapshotListSchema,
+  inputShape: snapshotListShape,
+  http: {
+    method: 'GET',
+    path: '/api/canvas/snapshots',
+  },
+  mcp: {
+    toolName: 'canvas_list_snapshots',
+    description: 'List saved canvas snapshots with IDs, names, timestamps, and node/edge counts. Defaults to the 20 newest snapshots; pass all=true to return every snapshot.',
+    extraShape: {
+      limit: z.number().optional().describe('Maximum snapshots to return (default: 20)'),
+      query: z.string().optional().describe('Optional case-insensitive ID/name filter'),
+      before: z.string().optional().describe('Only return snapshots created at or before this ISO timestamp'),
+      after: z.string().optional().describe('Only return snapshots created at or after this ISO timestamp'),
+      all: z.boolean().optional().describe('Return all snapshots instead of the default limit'),
+    },
+    formatResult: (result) => ({
+      content: [{ type: 'text' as const, text: JSON.stringify({ snapshots: result }, null, 2) }],
+    }),
+  },
+  handler: (input) => {
+    const body: Record<string, unknown> = input;
+    // Legacy precedence: ?q= wins over ?query= even when empty.
+    const query = typeof body.q === 'string'
+      ? body.q
+      : typeof body.query === 'string' ? body.query : undefined;
+    const limit = parsePositiveIntegerParam(body.limit);
+    return listCanvasSnapshots({
+      ...(limit !== undefined ? { limit } : {}),
+      ...(query !== undefined ? { query } : {}),
+      ...(typeof body.before === 'string' ? { before: body.before } : {}),
+      ...(typeof body.after === 'string' ? { after: body.after } : {}),
+      all: body.all === true || body.all === 'true',
+    });
+  },
+});
+
+// ── snapshot.save ─────────────────────────────────────────────
+
+const snapshotSaveShape = {
+  name: z.unknown().optional().describe('Name for this snapshot (e.g., "before refactor", "investigation v2")'),
+};
+
+const snapshotSaveSchema = z.looseObject(snapshotSaveShape);
+
+const snapshotSaveOperation = defineOperation<z.infer<typeof snapshotSaveSchema>, Record<string, unknown>>({
+  name: 'snapshot.save',
+  mutates: false,
+  input: snapshotSaveSchema,
+  inputShape: snapshotSaveShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/snapshots',
+  },
+  mcp: {
+    toolName: 'canvas_snapshot',
+    description: 'Save the current canvas state as a named snapshot. Snapshots persist to disk and can be restored later.',
+    extraShape: {
+      name: z.string().describe('Name for this snapshot (e.g., "before refactor", "investigation v2")'),
+    },
+    formatResult: (result) => ({
+      content: [{ type: 'text' as const, text: JSON.stringify(result) }],
+    }),
+  },
+  handler: (input) => {
+    const name = typeof input.name === 'string' ? input.name.trim() : '';
+    if (!name) throw new OperationError('Missing snapshot name');
+    const snapshot = saveCanvasSnapshot(name);
+    if (!snapshot) throw new OperationError('Failed to save snapshot');
+    return { ok: true, id: snapshot.id, snapshot };
+  },
+});
+
+// ── snapshot.gc ───────────────────────────────────────────────
+
+const snapshotGcShape = {
+  keep: z.unknown().optional().describe('Number of newest snapshots to keep (default: 20)'),
+  dryRun: z.unknown().optional().describe('Preview deletions without removing snapshot files'),
+};
+
+const snapshotGcSchema = z.looseObject(snapshotGcShape);
+
+const snapshotGcOperation = defineOperation<z.infer<typeof snapshotGcSchema>, Record<string, unknown>>({
+  name: 'snapshot.gc',
+  mutates: false,
+  input: snapshotGcSchema,
+  inputShape: snapshotGcShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/snapshots/gc',
+  },
+  mcp: {
+    toolName: 'canvas_gc_snapshots',
+    description: 'Delete old saved canvas snapshots, keeping the newest N snapshots. Use dryRun=true to preview deletions.',
+    extraShape: {
+      keep: z.number().optional().describe('Number of newest snapshots to keep (default: 20)'),
+      dryRun: z.boolean().optional().describe('Preview deletions without removing snapshot files'),
+    },
+    formatResult: (result) => ({
+      content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+    }),
+  },
+  handler: (input) => {
+    const body: Record<string, unknown> = input;
+    const keepValue = body.keep;
+    // Legacy coercion replicated as-is, including the Number('junk') → NaN
+    // pass-through (gcCanvasSnapshots falls back to its own default).
+    const keep = typeof keepValue === 'number'
+      ? keepValue
+      : typeof keepValue === 'string'
+        ? Number(keepValue)
+        : undefined;
+    const dryRun = body.dryRun === true || body['dry-run'] === true;
+    return gcCanvasSnapshots({
+      ...(keep !== undefined ? { keep } : {}),
+      dryRun,
+    }) as unknown as Record<string, unknown>;
+  },
+});
+
+// ── snapshot.diff ─────────────────────────────────────────────
+
+function diffSnapshotCore(idOrName: string): Record<string, unknown> {
+  const snapshot = canvasState.getSnapshotData(idOrName);
+  if (!snapshot) throw new OperationError(`Snapshot "${idOrName}" not found.`, 404);
+  const diff = diffLayouts(snapshot.name, snapshot, canvasState.getLayout());
+  return { ok: true, text: formatDiff(diff), diff };
+}
+
+const snapshotDiffShape = {
+  id: z.string().optional().catch(undefined).describe('Snapshot ID or name to compare against'),
+};
+
+const snapshotDiffSchema = z.looseObject(snapshotDiffShape);
+
+const snapshotDiffOperation = defineOperation<z.infer<typeof snapshotDiffSchema>, Record<string, unknown>>({
+  name: 'snapshot.diff',
+  mutates: false,
+  input: snapshotDiffSchema,
+  inputShape: snapshotDiffShape,
+  http: {
+    method: 'GET',
+    path: '/api/canvas/snapshots/:id/diff',
+  },
+  mcp: {
+    toolName: 'canvas_diff',
+    description: 'Compare the current canvas state against a saved snapshot. Shows added/removed/modified nodes and edges. Pass either a snapshot name or ID.',
+    extraShape: {
+      snapshot: z.string().describe('Snapshot name or ID to compare against'),
+    },
+    buildInput: (input) => ({ id: typeof input.snapshot === 'string' ? input.snapshot : '' }),
+    // Legacy success output was the human-readable diff text, not JSON.
+    formatResult: (result) => {
+      const body = isRecord(result) ? result : {};
+      return {
+        content: [{ type: 'text' as const, text: typeof body.text === 'string' ? body.text : '' }],
+      };
+    },
+  },
+  handler: ({ id }) => diffSnapshotCore(id ?? ''),
+});
+
+// Query-param variant: GET /api/canvas/snapshots/diff?name=… (HTTP only).
+const snapshotDiffQueryShape = {
+  name: z.unknown().optional().describe('Snapshot name to compare against'),
+  id: z.unknown().optional().describe('Snapshot ID alias for name'),
+};
+
+const snapshotDiffQuerySchema = z.looseObject(snapshotDiffQueryShape);
+
+const snapshotDiffQueryOperation = defineOperation<z.infer<typeof snapshotDiffQuerySchema>, Record<string, unknown>>({
+  name: 'snapshot.diff.query',
+  mutates: false,
+  input: snapshotDiffQuerySchema,
+  inputShape: snapshotDiffQueryShape,
+  http: {
+    method: 'GET',
+    path: '/api/canvas/snapshots/diff',
+  },
+  handler: (input) => {
+    // Legacy precedence: ?name= wins over ?id= even when empty.
+    const name = typeof input.name === 'string'
+      ? input.name
+      : typeof input.id === 'string' ? input.id : '';
+    if (!name.trim()) throw new OperationError('Missing snapshot name or id.');
+    return diffSnapshotCore(name);
+  },
+});
+
+// ── snapshot.restore ──────────────────────────────────────────
+
+/** Legacy mcp/server.ts buildSnapshotRestoreSummary, fed from the wire layout. */
+function buildSnapshotRestoreSummary(layout: unknown): Record<string, unknown> {
+  const body = isRecord(layout) ? layout : {};
+  const nodes = Array.isArray(body.nodes) ? body.nodes : [];
+  const edges = Array.isArray(body.edges) ? body.edges : [];
+  const annotations = Array.isArray(body.annotations) ? body.annotations : [];
+  const nodesByType: Record<string, number> = {};
+  for (const node of nodes) {
+    const type = isRecord(node) && typeof node.type === 'string' ? node.type : 'unknown';
+    nodesByType[type] = (nodesByType[type] ?? 0) + 1;
+  }
+  return {
+    nodeCount: nodes.length,
+    edgeCount: edges.length,
+    annotationCount: annotations.length,
+    nodesByType,
+    viewport: body.viewport,
+  };
+}
+
+const snapshotRestoreShape = {
+  id: z.string().optional().catch(undefined).describe('Snapshot ID or name to restore (from canvas_snapshot or snapshot list)'),
+};
+
+const snapshotRestoreSchema = z.looseObject(snapshotRestoreShape);
+
+const snapshotRestoreOperation = defineOperation<z.infer<typeof snapshotRestoreSchema>, Record<string, unknown>>({
+  name: 'snapshot.restore',
+  mutates: true,
+  input: snapshotRestoreSchema,
+  inputShape: snapshotRestoreShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/snapshots/:id',
+  },
+  mcp: {
+    toolName: 'canvas_restore',
+    description: 'Restore the canvas to a previously saved snapshot. Use canvas_snapshot to save first. Pass either the snapshot ID or name to restore.',
+    extraShape: {
+      id: z.string().describe('Snapshot ID or name to restore (from canvas_snapshot or snapshot list)'),
+    },
+    formatResult: async (_result, input, host) => {
+      const layout = await host.invoker().invoke('layout.get', { includeBlobs: true });
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            ok: true,
+            restored: input.id,
+            summary: buildSnapshotRestoreSummary(layout),
+          }, null, 2),
+        }],
+      };
+    },
+  },
+  handler: async ({ id }) => {
+    // Awaits only the synchronous restore; restoreCanvasSnapshot fires the
+    // async ext-app rehydration itself and schedules a deferred
+    // canvas-layout-update through setCanvasLayoutUpdateEmitter when it
+    // finishes. mutates: true contributes the single immediate frame — do NOT
+    // add a manual emit here or the frame is doubled.
+    const result = await restoreCanvasSnapshot(id ?? '');
+    if (!result.ok) throw new OperationError('Snapshot not found', 404);
+    return { ok: true };
+  },
+});
+
+// ── snapshot.delete ───────────────────────────────────────────
+
+const snapshotDeleteShape = {
+  id: z.string().optional().catch(undefined).describe('Snapshot ID to delete'),
+};
+
+const snapshotDeleteSchema = z.looseObject(snapshotDeleteShape);
+
+const snapshotDeleteOperation = defineOperation<z.infer<typeof snapshotDeleteSchema>, Record<string, unknown>>({
+  name: 'snapshot.delete',
+  mutates: false,
+  input: snapshotDeleteSchema,
+  inputShape: snapshotDeleteShape,
+  http: {
+    method: 'DELETE',
+    path: '/api/canvas/snapshots/:id',
+  },
+  mcp: {
+    toolName: 'canvas_delete_snapshot',
+    description: 'Delete a saved snapshot by ID.',
+    extraShape: {
+      id: z.string().describe('Snapshot ID to delete'),
+    },
+    formatResult: (_result, input) => ({
+      content: [{ type: 'text' as const, text: JSON.stringify({ ok: true, deleted: input.id }) }],
+    }),
+  },
+  handler: ({ id }) => {
+    const result = deleteCanvasSnapshot(id ?? '');
+    if (!result.ok) throw new OperationError('Snapshot not found', 404);
+    return { ok: true };
+  },
+});
+
+export const snapshotOperations: Operation[] = [
+  snapshotListOperation,
+  snapshotSaveOperation,
+  // gc before restore: POST /api/canvas/snapshots/gc must match before
+  // POST /api/canvas/snapshots/:id (registration order = dispatch order).
+  snapshotGcOperation,
+  snapshotDiffQueryOperation,
+  snapshotDiffOperation,
+  snapshotRestoreOperation,
+  snapshotDeleteOperation,
+];

package/src/server/operations/ops/validate.ts

@@ -0,0 +1,37 @@
+/**
+ * Board validation read op (plan-008 Wave 1): validate.get.
+ *
+ * Pure read — no mutation, no emit. Serializes the same shape the legacy
+ * GET /api/canvas/validate handler and the canvas_validate MCP tool returned.
+ *
+ * This module must never import server.ts or index.ts.
+ */
+import { z } from 'zod';
+import { canvasState } from '../../canvas-state.js';
+import { validateCanvasLayout, type CanvasValidationResult } from '../../canvas-validation.js';
+import { defineOperation, type Operation } from '../types.js';
+
+const validateGetShape = {};
+
+const validateGetSchema = z.looseObject(validateGetShape);
+
+const validateGetOperation = defineOperation<z.infer<typeof validateGetSchema>, CanvasValidationResult>({
+  name: 'validate.get',
+  mutates: false,
+  input: validateGetSchema,
+  inputShape: validateGetShape,
+  http: {
+    method: 'GET',
+    path: '/api/canvas/validate',
+  },
+  mcp: {
+    toolName: 'canvas_validate',
+    description: 'Validate the current canvas layout. Distinguishes true node collisions from expected group-child containment and reports missing edge endpoints.',
+    formatResult: (result) => ({
+      content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+    }),
+  },
+  handler: () => validateCanvasLayout(canvasState.getLayout()),
+});
+
+export const validateOperations: Operation[] = [validateGetOperation];