@eventcatalog/core 5.0.0-beta.9 → 5.0.0

package/eventcatalog/src/features/studio/pages/webmcp-relay.ts

@@ -1,27 +1,24 @@
 import type { APIRoute } from 'astro';
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { createRequire } from 'node:module';
+import embed from '../webmcp-relay/embed.js?raw';
+import widgetHtml from '../webmcp-relay/widget.html?raw';
+import widgetJs from '../webmcp-relay/widget.js?raw';
 
 /**
  * Serves the WebMCP local relay's browser files (embed.js loads widget.html next to it), so the canvas page
  * can hand its WebMCP tools to desktop MCP clients (Claude Code, Cursor...) running
- * `npx -y @mcp-b/webmcp-local-relay@5.1.0`. Served from the installed package, so the version is pinned.
+ * `npx -y @mcp-b/webmcp-local-relay@5.1.0`. The files are copies of that version's (see webmcp-relay/README.md),
+ * bundled with the page, so the version is pinned.
  */
-const FILES: Record<string, string> = {
-  'embed.js': 'text/javascript',
-  'widget.html': 'text/html',
-  'widget.js': 'text/javascript',
+const FILES: Record<string, { body: string; contentType: string }> = {
+  'embed.js': { body: embed, contentType: 'text/javascript' },
+  'widget.html': { body: widgetHtml, contentType: 'text/html' },
+  'widget.js': { body: widgetJs, contentType: 'text/javascript' },
 };
 
-const browserDirectory = path.join(path.dirname(createRequire(import.meta.url).resolve('@mcp-b/webmcp-local-relay')), 'browser');
-
 export const GET: APIRoute = async ({ params }) => {
-  const file = params.file ?? '';
-  const contentType = FILES[file];
-  if (!contentType) return new Response('Not found', { status: 404 });
-  const body = await fs.readFile(path.join(browserDirectory, file), 'utf-8');
-  return new Response(body, { headers: { 'Content-Type': contentType, 'Cache-Control': 'no-cache' } });
+  const file = FILES[params.file ?? ''];
+  if (!file) return new Response('Not found', { status: 404 });
+  return new Response(file.body, { headers: { 'Content-Type': file.contentType, 'Cache-Control': 'no-cache' } });
 };
 
 export const prerender = false;

package/eventcatalog/src/features/studio/server/canvas-mcp.ts

@@ -21,10 +21,10 @@ import {
   setCanvasStatus,
   setThreadResolved,
   type Author,
-} from '../canvas-doc';
+  getLayoutPositions,
+} from '@eventcatalog/visualiser/studio';
 import { ADD_TO_CANVAS_DESCRIPTION, describeCanvas, edgeSpecsSchema, indexCatalog, nodeSpecsSchema } from '../canvas-actions';
 import { getCatalogResources } from '../catalog-resources';
-import { getLayoutPositions } from '../layout';
 import {
   playAddToCanvas,
   playComment,
@@ -35,7 +35,8 @@ import {
   playUpdateNode,
   type AgentStage,
 } from '../agent-choreography';
-import { STUDIO_SOCKET_PATH, findStudioRuntime, type AgentIdentity } from './runtime';
+import { STUDIO_SOCKET_PATH, findStudioRuntime } from './runtime';
+import { getAgent } from '../agents';
 import { addToolIcons } from './tool-icons';
 
 /**
@@ -46,21 +47,11 @@ import { addToolIcons } from './tool-icons';
 
 const loadCanvasView = getMcpAppViewLoader('canvas');
 
-const AGENT_COLORS: Record<string, string> = { ChatGPT: '#10a37f', Claude: '#d97757' };
-
 // The canvases entrypoint's icon (OpenAI MCP extensions: a 20x20, monochrome SVG in currentColor, 1.33px strokes)
 const CANVAS_ICON_SVG =
   '<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.33" stroke-linecap="round" stroke-linejoin="round"><rect x="2.5" y="3.5" width="5.5" height="4.5" rx="1"/><rect x="12" y="3.5" width="5.5" height="4.5" rx="1"/><rect x="12" y="12" width="5.5" height="4.5" rx="1"/><path d="M8 5.75h4M14.75 8v4"/></svg>';
 const CANVAS_ICON = { src: `data:image/svg+xml;base64,${btoa(CANVAS_ICON_SVG)}`, mimeType: 'image/svg+xml', sizes: ['20x20'] };
 
-/** Who the agent is, from what it tells us or its client's user agent */
-const getAgent = (agentName: string | undefined, userAgent = ''): AgentIdentity => {
-  const name =
-    agentName?.trim() ||
-    (/openai|chatgpt/i.test(userAgent) ? 'ChatGPT' : /claude|anthropic/i.test(userAgent) ? 'Claude' : 'AI agent');
-  return { name, color: AGENT_COLORS[name] ?? '#8b5cf6' };
-};
-
 const text = (value: unknown, isError = false) => ({
   content: [{ type: 'text' as const, text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }],
   ...(isError && { isError }),
@@ -151,12 +142,6 @@ export function registerCanvasTools(server: McpServer, { catalogUrl, userAgent }
       input: {
         canvasId: canvasId.optional(),
         title: z.string().optional().describe('For a new canvas: what it is for'),
-        userName: z
-          .string()
-          .optional()
-          .describe(
-            'The name of the person you are working with, if you know it: others on the canvas see them by this name. Leave it out if you do not know it.'
-          ),
         agentName,
       },
     },
@@ -170,7 +155,7 @@ export function registerCanvasTools(server: McpServer, { catalogUrl, userAgent }
     annotations: writes,
     errorMessage: 'Failed to open the canvas',
     load: async (params) => {
-      const { title: newTitle, agentName: name, userName } = params as { title?: string; agentName?: string; userName?: string };
+      const { title: newTitle, agentName: name } = params as { title?: string; agentName?: string };
 
       // Opened without a canvas (e.g. from an entrypoint): the canvases to pick from, or start one
       if (!params.canvasId && !newTitle) {
@@ -207,7 +192,7 @@ export function registerCanvasTools(server: McpServer, { catalogUrl, userAgent }
         socketUrl,
         canvasUrl: canvasUrl(id),
         mcpUrl: `${catalogUrl}${buildUrl('/docs/mcp', true)}`,
-        userName,
+        agent: getAgent(name, userAgent),
       };
       return {
         forModel: {
@@ -418,7 +403,7 @@ export function registerCanvasTools(server: McpServer, { catalogUrl, userAgent }
     {
       title: 'Tidy a canvas',
       description:
-        "Lays the whole canvas out again with EventCatalog's visualiser layout (left to right, connections routed around nodes); everyone on it sees the nodes glide into place. It moves everything, including what people placed themselves, so only use it when the user asks to tidy up: addToCanvas already places what you add next to what it connects to.",
+        "Lays the whole canvas out again with EventCatalog's visualiser layout (left to right, connections routed around nodes); everyone on it sees the nodes glide into place. Call it once when you finish a round of changes, before you hand back to the user, so the canvas is tidy for everyone, and whenever the user asks to tidy up. Don't call it after every change (addToCanvas already places what you add next to what it connects to while you work), and skip it if the user asked to keep the layout as it is: it moves everything, including what people placed themselves.",
       inputSchema: z.object({ canvasId, agentName }),
       annotations: writes,
     },
@@ -427,7 +412,7 @@ export function registerCanvasTools(server: McpServer, { catalogUrl, userAgent }
       const { nodes, edges } = await runtime.withCanvas(id, readCanvas);
       const positions = await getLayoutPositions(nodes, edges);
       await playLayout(asAgent(id, name).stage, positions);
-      return text({ laidOut: positions.size });
+      return text({ laidOut: positions.nodes.size });
     }
   );
 

package/eventcatalog/src/features/studio/server/runtime.ts

@@ -5,27 +5,34 @@ import { Awareness, applyAwarenessUpdate, encodeAwarenessUpdate, removeAwareness
 import type { XYPosition } from '@xyflow/react';
 import type { AgentPresence } from '../agent-choreography';
 import {
-  canvasDocumentName,
-  canvasIdFromDocumentName,
+  addCanvasContent,
   getCanvasMaps,
   readMeta,
   setMeta,
   getCanvasStatus,
+  type CanvasContent,
   type CanvasStatus,
-} from '../canvas-doc';
+} from '@eventcatalog/visualiser/studio';
+import { CANVAS_DELETED_REASON, canvasDocumentName, canvasIdFromDocumentName } from '../document-name';
 import { getCanvasPreview, type CanvasPreview } from '../canvas-preview';
+import { MAX_TITLE_LENGTH } from '../limits';
 import { fromBase64, toBase64, type SyncRequest, type SyncResponse } from '../tool-sync';
 import config from '../../../utils/eventcatalog-config/source';
 import { isAuthEnabled } from '../../../utils/feature';
-import { createStorage, memoryStorage, type CanvasStorage, type StudioStorageConfig } from './storage';
+import { createStorage, memoryStorage, type CanvasStorage } from './storage';
+import type { StorageConfig } from '../../storage/database';
+import { isDatabaseTooNew } from '../../storage/migrations';
 
 export const STUDIO_SOCKET_PATH = '/_eventcatalog/studio';
 const SOCKET_PATH_PATTERN = /\/_eventcatalog\/studio\/?$/;
 // Agents show as present while they work, and leave a while after their last change (before awareness's own
 // 30 second timeout would drop them anyway)
 const AGENT_PRESENCE_TTL_MS = 25_000;
+// Application close codes are 4000-4999
+const CANVAS_DELETED_CLOSE_CODE = 4410;
 
-export type AgentIdentity = { name: string; color: string };
+import type { AgentIdentity } from '../agents';
+export type { AgentIdentity };
 export type CanvasSummary = {
   canvasId: string;
   title?: string;
@@ -53,6 +60,8 @@ type RuntimeState = {
   snapshots: Map<string, Uint8Array>;
   /** When each canvas last changed (kept with it in storage) */
   updatedAt: Map<string, number>;
+  /** Canvases deleted (by document name): refused from then on, so a browser still holding one can't bring it back */
+  deleted: Set<string>;
   agents: Map<string, { awareness: Awareness; expires: ReturnType<typeof setTimeout> }>;
   attached: WeakSet<HttpServer>;
   storage: CanvasStorage;
@@ -74,6 +83,7 @@ const createState = (): RuntimeState => {
   const state: RuntimeState = {
     snapshots: new Map(),
     updatedAt: new Map(),
+    deleted: new Set(),
     agents: new Map(),
     attached: new WeakSet(),
     storage: memoryStorage(),
@@ -82,9 +92,13 @@ const createState = (): RuntimeState => {
     server: new Server({
       quiet: true,
       // With sign-in on, only signed-in people can open a canvas (refused until the pages have said how to check)
-      onConnect: async ({ request }) => {
-        if (!isAuthEnabled()) return;
-        if (!(await state.isSignedIn?.(request).catch(() => false))) throw new Error('Sign in to open this canvas');
+      onConnect: async ({ request, documentName }) => {
+        if (isAuthEnabled() && !(await state.isSignedIn?.(request).catch(() => false))) {
+          throw new Error('Sign in to open this canvas');
+        }
+        if (state.deleted.has(documentName)) {
+          throw Object.assign(new Error('This canvas was deleted'), { reason: CANVAS_DELETED_REASON });
+        }
       },
       onLoadDocument: async ({ documentName, document }) => {
         // A hook that throws leaves the document half loaded in Hocuspocus (ueberdosis/hocuspocus#1156)
@@ -106,8 +120,18 @@ const createState = (): RuntimeState => {
   return state;
 };
 
+/** A canvas just started: its title, and when and by whom (a person, or an agent) */
+const setStarted = (doc: Y.Doc, { title, createdBy }: { title?: string; createdBy?: string }) =>
+  setMeta(doc, { ...(title && { title }), createdAt: Date.now(), ...(createdBy && { createdBy }) });
+
+/** Nothing on it, no title, and nobody on it */
+const isBlank = (canvas: CanvasSummary) =>
+  canvas.nodeCount === 0 && canvas.openComments === 0 && !canvas.title && canvas.people.length === 0;
+
 /** Keeps a canvas's snapshot, and writes it to storage (failing to store it doesn't lose it from memory) */
 const saveSnapshot = (state: RuntimeState, documentName: string, document: Y.Doc) => {
+  // Deleted while it was still open (e.g. waiting to be stored)
+  if (state.deleted.has(documentName)) return;
   const snapshot = Y.encodeStateAsUpdate(document);
   state.snapshots.set(documentName, snapshot);
   try {
@@ -121,7 +145,7 @@ const saveSnapshot = (state: RuntimeState, documentName: string, document: Y.Doc
  * The collaboration server, shared (through globalThis) by the WebSocket upgrade handler and server code such
  * as MCP tools, which edit canvases as agents. Only the state is shared, so code changes apply without a restart.
  */
-class StudioRuntime {
+export class StudioRuntime {
   constructor(private readonly state: RuntimeState) {}
 
   get server() {
@@ -144,19 +168,20 @@ class StudioRuntime {
   }
 
   /**
-   * Keeps canvases in the storage configured (`studio.storage`, memory by default), and loads the ones
+   * Keeps canvases in the storage configured (the catalog's `storage`, memory by default), and loads the ones
    * stored there. Set once when the server starts; calling it again with the same config does nothing.
    */
-  async useStorage(config: StudioStorageConfig | undefined, projectDirectory: string) {
+  async useStorage(config: StorageConfig | undefined, projectDirectory: string) {
     const key = JSON.stringify({ config: config ?? null, projectDirectory });
     if (this.state.storageKey === key) return this.state.ready;
     const storage = createStorage(config, projectDirectory);
     this.state.storageKey = key;
     this.state.storage = storage;
-    this.state.ready = storage.loadAll().then((stored) => {
+    this.state.ready = storage.loadAll().then(({ canvases, deleted }) => {
+      deleted.forEach((name) => this.state.deleted.add(name));
       // Canvases already open here (e.g. the dev server reloading) are kept as they are
-      stored.forEach(({ state, updatedAt }, name) => {
-        if (this.snapshots.has(name)) return;
+      canvases.forEach(({ state, updatedAt }, name) => {
+        if (this.snapshots.has(name) || this.state.deleted.has(name)) return;
         this.snapshots.set(name, state);
         if (updatedAt) this.state.updatedAt.set(name, updatedAt);
       });
@@ -173,8 +198,13 @@ class StudioRuntime {
     this.state.started ??= (async () => {
       const projectDirectory = process.env.PROJECT_DIR || process.cwd();
       try {
-        await this.useStorage(config.studio?.storage, projectDirectory);
+        await this.useStorage(config.storage, projectDirectory);
       } catch (error) {
+        // Not kept in memory instead: everyone's changes would quietly stop being saved
+        if (isDatabaseTooNew(error)) {
+          console.error(`[studio] Studio isn't available: ${(error as Error).message}`);
+          throw error;
+        }
         console.error(
           `[studio] Could not use the Studio storage configured, keeping canvases in memory: ${(error as Error).message}`
         );
@@ -186,7 +216,7 @@ class StudioRuntime {
         const { type, location } = this.storage;
         console.log(
           type === 'memory'
-            ? `[studio] Collaboration server ready at ${STUDIO_SOCKET_PATH}. Canvases are kept in memory and lost when the server restarts or redeploys: set studio.storage in eventcatalog.config.js to keep them.`
+            ? `[studio] Collaboration server ready at ${STUDIO_SOCKET_PATH}. Canvases are kept in memory and lost when the server restarts or redeploys: set storage in eventcatalog.config.js to keep them.`
             : `[studio] Collaboration server ready at ${STUDIO_SOCKET_PATH} (canvases stored in ${location})`
         );
       }
@@ -232,18 +262,77 @@ class StudioRuntime {
 
   exists(canvasId: string) {
     const name = canvasDocumentName(canvasId);
-    return this.server.hocuspocus.documents.has(name) || this.snapshots.has(name);
+    return !this.state.deleted.has(name) && (this.server.hocuspocus.documents.has(name) || this.snapshots.has(name));
   }
 
-  /** Starts a canvas with a title, recording when and by whom (a person, or an agent). Returns its id. */
-  async createCanvas({ title, createdBy }: { title?: string; createdBy?: string }) {
+  isDeleted(canvasId: string) {
+    return this.state.deleted.has(canvasDocumentName(canvasId));
+  }
+
+  /**
+   * Deletes a canvas for everyone: from storage, and from the browsers that have it open (they're disconnected, told
+   * why, and refused from then on, so their copy can't bring it back). Returns false if there's no such canvas.
+   * Throws if storage can't delete it, leaving it as it was.
+   */
+  deleteCanvas(canvasId: string) {
+    if (!this.exists(canvasId)) return false;
+    const name = canvasDocumentName(canvasId);
+    this.state.storage.remove(name);
+    this.state.deleted.add(name);
+    this.snapshots.delete(name);
+    this.state.updatedAt.delete(name);
+    this.agents.forEach(({ awareness, expires }, key) => {
+      if (!key.startsWith(`${name}::`)) return;
+      clearTimeout(expires);
+      awareness.destroy();
+      this.agents.delete(key);
+    });
+    const { hocuspocus } = this.server;
+    const document = hocuspocus.documents.get(name);
+    if (document) {
+      // Told why, so they can say so (Hocuspocus's closeConnections only says it reset them)
+      document.connections.forEach((_clients, connection) =>
+        connection.close({ code: CANVAS_DELETED_CLOSE_CODE, reason: CANVAS_DELETED_REASON })
+      );
+      // Unloaded now, or once it's done storing (which skips deleted canvases)
+      void hocuspocus.unloadDocument(document);
+    }
+    return true;
+  }
+
+  /**
+   * Starts a canvas with a title, recording when and by whom (a person, or an agent), and what's on it to begin
+   * with, if anything. Returns its id.
+   */
+  async createCanvas(started: { title?: string; createdBy?: string }, content?: CanvasContent) {
     const canvasId = crypto.randomUUID();
-    await this.withCanvas(canvasId, (doc) =>
-      setMeta(doc, { ...(title && { title }), createdAt: Date.now(), ...(createdBy && { createdBy }) })
-    );
+    await this.withCanvas(canvasId, (doc) => {
+      setStarted(doc, started);
+      if (content) addCanvasContent(doc, content);
+    });
     return canvasId;
   }
 
+  /**
+   * Makes a copy of a canvas's design (its nodes and connections, not its comments or status) as a new draft, called
+   * "Copy of" the original unless given a title. Returns the copy's id, or undefined if there's no such canvas.
+   */
+  async copyCanvas(canvasId: string, { title, createdBy }: { title?: string; createdBy?: string } = {}) {
+    if (!this.exists(canvasId)) return undefined;
+    const original = await this.withCanvas(canvasId, (doc) => {
+      const { nodes, edges } = getCanvasMaps(doc);
+      return { title: readMeta(doc).title, nodes: [...nodes.entries()], edges: [...edges.entries()] };
+    });
+    const copyId = crypto.randomUUID();
+    await this.withCanvas(copyId, (doc) => {
+      const { nodes, edges } = getCanvasMaps(doc);
+      setStarted(doc, { title: title ?? `Copy of ${original.title ?? 'Untitled canvas'}`.slice(0, MAX_TITLE_LENGTH), createdBy });
+      original.nodes.forEach(([id, node]) => nodes.set(id, structuredClone(node)));
+      original.edges.forEach(([id, edge]) => edges.set(id, structuredClone(edge)));
+    });
+    return copyId;
+  }
+
   /** Read or change a canvas as the server. Changes sync to everyone on it, like anyone else's. */
   async withCanvas<T>(canvasId: string, fn: (doc: Y.Doc) => T): Promise<T> {
     const connection = await this.server.hocuspocus.openDirectConnection(canvasDocumentName(canvasId));
@@ -286,32 +375,46 @@ class StudioRuntime {
     return response;
   }
 
+  /**
+   * The canvases, the most recently changed first. Ones started and left empty (e.g. a made-up link opened, then left)
+   * aren't listed: they can still be opened by their link.
+   */
   listCanvases({ withPreview = false }: { withPreview?: boolean } = {}): CanvasSummary[] {
     const names = new Set([...this.server.hocuspocus.documents.keys(), ...this.snapshots.keys()]);
-    return [...names].flatMap((name) => {
-      const canvasId = canvasIdFromDocumentName(name);
-      if (!canvasId) return [];
-      const live = this.server.hocuspocus.documents.get(name);
-      const doc = live ?? new Y.Doc();
-      if (!live) Y.applyUpdate(doc, this.snapshots.get(name)!);
-      const { nodes, edges, threads } = getCanvasMaps(doc);
-      const meta = readMeta(doc);
-      return [
-        {
-          canvasId,
-          title: meta.title,
-          status: getCanvasStatus(meta),
-          createdAt: meta.createdAt,
-          ...(meta.createdBy && { createdBy: meta.createdBy }),
-          updatedAt: this.state.updatedAt.get(name) ?? meta.createdAt,
-          nodeCount: nodes.size,
-          edgeCount: edges.size,
-          openComments: Array.from(threads.values()).filter((thread) => !thread.get('resolved')).length,
-          people: live ? this.peopleOn(canvasId) : [],
-          ...(withPreview && { preview: getCanvasPreview(Array.from(nodes.values()), Array.from(edges.values())) }),
-        },
-      ];
-    });
+    return [...names]
+      .flatMap((name) => {
+        const canvasId = canvasIdFromDocumentName(name);
+        return canvasId && this.exists(canvasId) ? [this.summarize(canvasId, { withPreview })] : [];
+      })
+      .filter((canvas) => !isBlank(canvas))
+      .sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0));
+  }
+
+  /** One canvas, as listed (undefined if there's no such canvas) */
+  getCanvas(canvasId: string): CanvasSummary | undefined {
+    return this.exists(canvasId) ? this.summarize(canvasId) : undefined;
+  }
+
+  private summarize(canvasId: string, { withPreview = false }: { withPreview?: boolean } = {}): CanvasSummary {
+    const name = canvasDocumentName(canvasId);
+    const live = this.server.hocuspocus.documents.get(name);
+    const doc = live ?? new Y.Doc();
+    if (!live) Y.applyUpdate(doc, this.snapshots.get(name)!);
+    const { nodes, edges, threads } = getCanvasMaps(doc);
+    const meta = readMeta(doc);
+    return {
+      canvasId,
+      title: meta.title,
+      status: getCanvasStatus(meta),
+      createdAt: meta.createdAt,
+      ...(meta.createdBy && { createdBy: meta.createdBy }),
+      updatedAt: this.state.updatedAt.get(name) ?? meta.createdAt,
+      nodeCount: nodes.size,
+      edgeCount: edges.size,
+      openComments: Array.from(threads.values()).filter((thread) => !thread.get('resolved')).length,
+      people: live ? this.peopleOn(canvasId) : [],
+      ...(withPreview && { preview: getCanvasPreview(Array.from(nodes.values()), Array.from(edges.values())) }),
+    };
   }
 
   /** Names of the people and agents on a canvas right now */
@@ -364,6 +467,7 @@ const store = globalThis as typeof globalThis & { [RUNTIME_KEY]?: RuntimeState }
  */
 const upgrade = (state: RuntimeState) => {
   state.updatedAt ??= new Map();
+  state.deleted ??= new Set();
   return state;
 };
 

package/eventcatalog/src/features/studio/server/sql/storage.sql

@@ -0,0 +1,18 @@
+-- The statements Studio's SQLite storage runs (see storage.ts), each named by the `-- name:` line above it. The tables
+-- are made by the catalog's migrations (features/storage/sql/migrations).
+
+-- name: saveCanvas
+INSERT INTO studio_canvases (name, state, updated_at) VALUES (?, ?, ?)
+ON CONFLICT (name) DO UPDATE SET state = excluded.state, updated_at = excluded.updated_at;
+
+-- name: removeCanvas
+DELETE FROM studio_canvases WHERE name = ?;
+
+-- name: recordDeleted
+INSERT OR IGNORE INTO studio_deleted_canvases (name, deleted_at) VALUES (?, ?);
+
+-- name: allCanvases
+SELECT name, state, updated_at FROM studio_canvases;
+
+-- name: allDeleted
+SELECT name FROM studio_deleted_canvases;

package/eventcatalog/src/features/studio/server/storage.ts

@@ -1,110 +1,90 @@
-import fs from 'node:fs';
-import path from 'node:path';
+import { getDatabasePath, openDatabase, type Database, type StorageConfig, type StorageType } from '../../storage/database';
+import { namedStatements } from '../../storage/sql';
+import storageSql from './sql/storage.sql?raw';
 
 /**
- * Where Studio keeps canvases (`studio.storage` in eventcatalog.config.js). People and agents always work on the copy
- * the collaboration server holds in memory, so storage is only read when the server starts, and written a moment
- * after a canvas changes: it doesn't slow down editing. Canvases are stored as their whole Yjs document
- * (Y.encodeStateAsUpdate), so nothing is lost between restarts.
+ * Where Studio keeps canvases: the catalog's storage (`storage` in eventcatalog.config.js). People and agents always
+ * work on the copy the collaboration server holds in memory, so storage is only read when the server starts, and
+ * written a moment after a canvas changes: it doesn't slow down editing. Canvases are stored as their whole Yjs
+ * document (Y.encodeStateAsUpdate), so nothing is lost between restarts.
  */
-export type StudioStorageConfig =
-  /** Kept only while the server runs: canvases are lost when it restarts or redeploys (the default) */
-  | { type: 'memory' }
-  /**
-   * One SQLite database file (default `.eventcatalog/studio.db` in the catalog). Needs Node.js 22.13 or later. In a
-   * container, put it on a volume so it survives redeploys.
-   */
-  | { type: 'sqlite'; path?: string };
-
-export type StorageType = StudioStorageConfig['type'];
-
-export const DEFAULT_STORAGE: StudioStorageConfig = { type: 'memory' };
-const DEFAULT_SQLITE_PATH = '.eventcatalog/studio.db';
 
 /** A canvas as stored: its whole document, and when it last changed */
 export type StoredCanvas = { state: Uint8Array; updatedAt?: number };
 
+/** What's stored: every canvas, and the canvases deleted (so a browser still holding one can't bring it back) */
+export type StoredCanvases = { canvases: Map<string, StoredCanvas>; deleted: Set<string> };
+
 export type CanvasStorage = {
   type: StorageType;
   /** Where it is, for logs (e.g. the database file) */
   location?: string;
-  /** Every stored canvas, by document name (read once, when the server starts) */
-  loadAll: () => Promise<Map<string, StoredCanvas>>;
+  /** Every stored canvas by document name, and the deleted ones (read once, when the server starts) */
+  loadAll: () => Promise<StoredCanvases>;
   /**
    * Stores a canvas's document, with when it last changed (now when not known). Synchronous, so canvases can still
    * be saved as the process exits.
    */
   save: (documentName: string, state: Uint8Array, updatedAt?: number) => void;
+  /** Deletes a canvas, and records that it was deleted */
+  remove: (documentName: string) => void;
 };
 
 export const memoryStorage = (): CanvasStorage => ({
   type: 'memory',
-  loadAll: async () => new Map(),
+  loadAll: async () => ({ canvases: new Map(), deleted: new Set() }),
   save: () => {},
+  remove: () => {},
 });
 
-type SqliteDatabase = {
-  exec: (sql: string) => void;
-  prepare: (sql: string) => { run: (...values: unknown[]) => unknown; all: () => unknown[] };
-};
+/** The queries Studio runs, from ./sql/storage.sql (its tables are made by the catalog's migrations) */
+const QUERIES = ['saveCanvas', 'removeCanvas', 'recordDeleted', 'allCanvases', 'allDeleted'] as const;
+const SQL = namedStatements(storageSql, QUERIES);
 
+type Statements = Record<(typeof QUERIES)[number], ReturnType<Database['prepare']>>;
+
+/** Canvases in the catalog's SQLite database, in `file` */
 export const sqliteStorage = (file: string): CanvasStorage => {
-  let database: SqliteDatabase | undefined;
-  let upsert: ReturnType<SqliteDatabase['prepare']> | undefined;
+  let opened: { database: Database; statements: Statements } | undefined;
+  const use = () => {
+    if (!opened) throw new Error('SQLite storage was used before it was opened');
+    return opened;
+  };
   return {
     type: 'sqlite',
     location: file,
     loadAll: async () => {
-      // Node's built-in SQLite (no native package to install), asked of Node itself: the dev server loads this
-      // through Vite, which doesn't know node:sqlite and fails to import it
-      type Sqlite = { DatabaseSync: new (file: string) => SqliteDatabase };
-      const getBuiltinModule = (process as { getBuiltinModule?: (id: string) => unknown }).getBuiltinModule;
-      let sqlite: Sqlite | undefined;
+      const database = await openDatabase(file);
+      const statements = Object.fromEntries(QUERIES.map((name) => [name, database.prepare(SQL[name])])) as Statements;
+      opened = { database, statements };
+
+      const rows = statements.allCanvases.all() as { name: string; state: Uint8Array; updated_at: number }[];
+      const deleted = statements.allDeleted.all() as { name: string }[];
+      return {
+        canvases: new Map(rows.map((row) => [row.name, { state: new Uint8Array(row.state), updatedAt: Number(row.updated_at) }])),
+        deleted: new Set(deleted.map((row) => row.name)),
+      };
+    },
+    save: (documentName, state, updatedAt = Date.now()) => {
+      use().statements.saveCanvas.run(documentName, state, updatedAt);
+    },
+    remove: (documentName) => {
+      const { database, statements } = use();
+      database.exec('BEGIN');
       try {
-        sqlite = getBuiltinModule
-          ? (getBuiltinModule('node:sqlite') as Sqlite | undefined)
-          : await import(/* @vite-ignore */ ['node', 'sqlite'].join(':'));
+        statements.recordDeleted.run(documentName, Date.now());
+        statements.removeCanvas.run(documentName);
+        database.exec('COMMIT');
       } catch (error) {
-        throw new Error(`Could not load node:sqlite (${(error as Error).message})`);
+        database.exec('ROLLBACK');
+        throw error;
       }
-      if (!sqlite?.DatabaseSync) {
-        throw new Error(
-          `SQLite storage needs Node.js 22.13 or later (it uses node:sqlite); this is Node.js ${process.versions.node}`
-        );
-      }
-      fs.mkdirSync(path.dirname(file), { recursive: true });
-      database = new sqlite.DatabaseSync(file);
-      database.exec('PRAGMA journal_mode = WAL');
-      database.exec(
-        'CREATE TABLE IF NOT EXISTS canvases (name TEXT PRIMARY KEY, state BLOB NOT NULL, updated_at INTEGER NOT NULL)'
-      );
-      upsert = database.prepare(
-        'INSERT INTO canvases (name, state, updated_at) VALUES (?, ?, ?) ON CONFLICT(name) DO UPDATE SET state = excluded.state, updated_at = excluded.updated_at'
-      );
-      const rows = database.prepare('SELECT name, state, updated_at FROM canvases').all() as {
-        name: string;
-        state: Uint8Array;
-        updated_at: number;
-      }[];
-      return new Map(rows.map((row) => [row.name, { state: new Uint8Array(row.state), updatedAt: Number(row.updated_at) }]));
-    },
-    save: (documentName, state, updatedAt = Date.now()) => {
-      if (!upsert) throw new Error('SQLite storage was used before it was opened');
-      upsert.run(documentName, state, updatedAt);
     },
   };
 };
 
-/** The storage a config asks for, with paths relative to the catalog. Unknown types are an error. */
-export const createStorage = (config: StudioStorageConfig | undefined, projectDirectory: string): CanvasStorage => {
-  const chosen = config ?? DEFAULT_STORAGE;
-  const resolve = (location: string | undefined, fallback: string) => path.resolve(projectDirectory, location ?? fallback);
-  switch (chosen.type) {
-    case 'memory':
-      return memoryStorage();
-    case 'sqlite':
-      return sqliteStorage(resolve(chosen.path, DEFAULT_SQLITE_PATH));
-    default:
-      throw new Error(`Unknown studio.storage type "${(chosen as { type?: string }).type}": use "memory" or "sqlite"`);
-  }
+/** Canvases in the storage a config asks for (paths relative to the catalog). Unknown types are an error. */
+export const createStorage = (config: StorageConfig | undefined, projectDirectory: string): CanvasStorage => {
+  const file = getDatabasePath(config, projectDirectory);
+  return file ? sqliteStorage(file) : memoryStorage();
 };

package/eventcatalog/src/features/studio/webmcp-relay/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 mcp-b contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.