@imgly/codesign-mcp 0.1.0

package/dist/tools/export.js

@@ -0,0 +1,179 @@
+// packages/codesign-mcp/src/tools/export.ts
+//
+// `export` — spec §6.2. Writes a revision-pinned artifact into
+// `exports/<shard>/<rev>/<format>.<ext>` and returns a workspace URI envelope:
+// `uri` (the durable `workspace://` handle) plus `httpUrl` (the `/r/` fetch
+// link). `path` (an absolute disk path) is returned ONLY when the caller
+// passes an explicit `outPath` — a normal workspace export never discloses
+// the workspace's on-disk location.
+//
+// `target=video` is deferred to Phase 4.
+import { promises as nodeFs } from 'node:fs';
+import { dirname } from 'node:path';
+const TARGET_MIME = {
+    pdf: { pdf: 'application/pdf' },
+    image: { png: 'image/png', jpeg: 'image/jpeg', webp: 'image/webp' }
+};
+const FORMAT_EXT = {
+    pdf: 'pdf',
+    png: 'png',
+    jpeg: 'jpg',
+    webp: 'webp',
+    mp4: 'mp4'
+};
+const DESCRIPTION = [
+    'Export a revision to pdf/image. Renders `blockId` and writes the result into the workspace under `exports/<shard>/<rev>/<target>.<ext>` (revision-pinned, deterministic).',
+    '',
+    'Returns JSON: `{ uri, httpUrl?, path?, bytes, format, revision }`. `uri` (a `workspace://` URI) is the durable handle. `httpUrl` is a fetch link for opening the artifact now — present for workspace exports, tied to this process. `path` (absolute disk path) is returned ONLY when you passed `outPath`.',
+    '',
+    '`target=video` is deferred to Phase 4.'
+].join('\n');
+// The schema is built per-backend: `outPath` is advertised ONLY when the
+// backend honours it (Local). On Hosted the property is omitted entirely, so
+// an agent never sees an affordance it can't use — it can't try a local path
+// and hit a runtime rejection. The runtime guard in `call` stays as a backstop.
+function buildExportInputSchema(allowOutPath) {
+    const properties = {
+        target: { enum: ['pdf', 'image', 'video'] },
+        format: { enum: ['pdf', 'png', 'jpeg', 'webp', 'mp4'] },
+        revision: { type: 'string' },
+        blockId: {
+            type: 'integer',
+            description: 'Required for pdf and image targets.'
+        }
+    };
+    if (allowOutPath) {
+        properties.outPath = {
+            type: 'string',
+            description: 'Local-only escape hatch; absolute path.'
+        };
+    }
+    return {
+        type: 'object',
+        properties,
+        required: ['target', 'format', 'revision'],
+        additionalProperties: false
+    };
+}
+export function createExportTool(opts) {
+    const { fs, store, session, urlBuilder, allowOutPath = false, engineLock } = opts;
+    return {
+        name: 'export',
+        description: DESCRIPTION,
+        inputSchema: buildExportInputSchema(allowOutPath),
+        call: async (rawArgs) => {
+            const args = (rawArgs ?? {});
+            if (typeof args.target !== 'string' ||
+                typeof args.format !== 'string' ||
+                typeof args.revision !== 'string') {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'export: target, format, and revision are required.'
+                        }
+                    ]
+                };
+            }
+            if (args.target === 'video') {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'export: target=video is deferred to Phase 4.'
+                        }
+                    ]
+                };
+            }
+            if (args.outPath !== undefined && !allowOutPath) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'export: `outPath` is not supported on this (hosted) backend. Omit it — the artifact is written to the workspace and returned as `httpUrl`; fetch that URL to download the bytes to disk.'
+                        }
+                    ]
+                };
+            }
+            const rev = await store.read(args.revision);
+            if (typeof args.blockId !== 'number') {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: `export: target=${args.target} requires \`blockId\`.`
+                        }
+                    ]
+                };
+            }
+            const mimeMap = TARGET_MIME[args.target];
+            const mime = mimeMap?.[args.format];
+            if (!mime) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: `export: invalid format=${args.format} for target=${args.target}.`
+                        }
+                    ]
+                };
+            }
+            // Capture validated args into locals so the locked closure keeps the
+            // type narrowing the top-level guards established.
+            const revision = args.revision;
+            const blockId = args.blockId;
+            const sceneBytes = rev.scene;
+            // load-into-engine then export reads the shared engine across awaits —
+            // serialize against any concurrent engine-touching tool call.
+            const bytes = await engineLock.runExclusive(async () => {
+                await session.populate(revision, sceneBytes);
+                const slot = await session.acquire(revision);
+                const eng = slot.engine;
+                const blob = await eng.block.export(blockId, mime, {});
+                return new Uint8Array(await blob.arrayBuffer());
+            });
+            const shard = args.revision.slice(0, 2);
+            const rest = args.revision.slice(2);
+            const ext = FORMAT_EXT[args.format];
+            const relPath = `exports/${shard}/${rest}/${args.target}.${ext}`;
+            let absPath;
+            let httpUrl;
+            if (args.outPath !== undefined) {
+                // Local-only escape hatch: write through real disk fs, NOT through
+                // the workspace abstraction. The caller chose this path explicitly,
+                // so echoing it back is a confirmation, not a workspace-path leak.
+                await nodeFs.mkdir(dirname(args.outPath), { recursive: true });
+                await nodeFs.writeFile(args.outPath, bytes);
+                absPath = args.outPath;
+            }
+            else {
+                // Workspace write — goes through the WorkspaceFS abstraction. The
+                // artifact is reachable over HTTP via the `/r/` route; the absolute
+                // disk path is deliberately NOT disclosed.
+                await fs.writeFile(relPath, bytes);
+                httpUrl = await urlBuilder.forDownload(relPath);
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            uri: `workspace://${relPath}`,
+                            ...(httpUrl ? { httpUrl } : {}),
+                            ...(absPath ? { path: absPath } : {}),
+                            bytes: bytes.byteLength,
+                            format: args.format,
+                            revision: args.revision
+                        })
+                    }
+                ]
+            };
+        }
+    };
+}
+//# sourceMappingURL=export.js.map

package/dist/tools/export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.js","sourceRoot":"","sources":["../../src/tools/export.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,EAAE;AACF,+DAA+D;AAC/D,+EAA+E;AAC/E,4EAA4E;AAC5E,yEAAyE;AACzE,2EAA2E;AAC3E,oCAAoC;AACpC,EAAE;AACF,yCAAyC;AACzC,OAAO,EAAE,QAAQ,IAAI,MAAM,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAyBpC,MAAM,WAAW,GAAoD;IACnE,GAAG,EAAE,EAAE,GAAG,EAAE,iBAAiB,EAAE;IAC/B,KAAK,EAAE,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE;CACpE,CAAC;AAEF,MAAM,UAAU,GAA2B;IACzC,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,IAAI,EAAE,KAAK;IACX,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,KAAK;CACX,CAAC;AAEF,MAAM,WAAW,GAAG;IAClB,2KAA2K;IAC3K,EAAE;IACF,8SAA8S;IAC9S,EAAE;IACF,wCAAwC;CACzC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,yEAAyE;AACzE,6EAA6E;AAC7E,6EAA6E;AAC7E,gFAAgF;AAChF,SAAS,sBAAsB,CAAC,YAAqB;IACnD,MAAM,UAAU,GAA4B;QAC1C,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAC3C,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE;QACvD,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAiB,EAAE;QACrC,OAAO,EAAE;YACP,IAAI,EAAE,SAAkB;YACxB,WAAW,EAAE,qCAAqC;SACnD;KACF,CAAC;IACF,IAAI,YAAY,EAAE,CAAC;QACjB,UAAU,CAAC,OAAO,GAAG;YACnB,IAAI,EAAE,QAAiB;YACvB,WAAW,EAAE,yCAAyC;SACvD,CAAC;IACJ,CAAC;IACD,OAAO;QACL,IAAI,EAAE,QAAiB;QACvB,UAAU;QACV,QAAQ,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,CAAC;QAC1C,oBAAoB,EAAE,KAAK;KAC5B,CAAC;AACJ,CAAC;AAcD,MAAM,UAAU,gBAAgB,CAC9B,IAAgC;IAEhC,MAAM,EACJ,EAAE,EACF,KAAK,EACL,OAAO,EACP,UAAU,EACV,YAAY,GAAG,KAAK,EACpB,UAAU,EACX,GAAG,IAAI,CAAC;IACT,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,WAAW;QACxB,WAAW,EAAE,sBAAsB,CAAC,YAAY,CAAC;QACjD,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YACtB,MAAM,IAAI,GAAG,CAAC,OAAO,IAAI,EAAE,CAAwB,CAAC;YACpD,IACE,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ;gBAC/B,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ;gBAC/B,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,EACjC,CAAC;gBACD,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,oDAAoD;yBAC3D;qBACF;iBACF,CAAC;YACJ,CAAC;YACD,IAAI,IAAI,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;gBAC5B,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,8CAA8C;yBACrD;qBACF;iBACF,CAAC;YACJ,CAAC;YACD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,YAAY,EAAE,CAAC;gBAChD,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,0LAA0L;yBACjM;qBACF;iBACF,CAAC;YACJ,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC5C,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;gBACrC,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,kBAAkB,IAAI,CAAC,MAAM,wBAAwB;yBAC5D;qBACF;iBACF,CAAC;YACJ,CAAC;YACD,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,MAAyB,CAAC,CAAC;YAC5D,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACpC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,0BAA0B,IAAI,CAAC,MAAM,eAAe,IAAI,CAAC,MAAM,GAAG;yBACzE;qBACF;iBACF,CAAC;YACJ,CAAC;YACD,qEAAqE;YACrE,mDAAmD;YACnD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;YAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;YAC7B,MAAM,UAAU,GAAG,GAAG,CAAC,KAAK,CAAC;YAC7B,uEAAuE;YACvE,8DAA8D;YAC9D,MAAM,KAAK,GAAG,MAAM,UAAU,CAAC,YAAY,CAAC,KAAK,IAAI,EAAE;gBACrD,MAAM,OAAO,CAAC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;gBAC7C,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAC7C,MAAM,GAAG,GAAG,IAAI,CAAC,MAAuB,CAAC;gBACzC,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;gBACvD,OAAO,IAAI,UAAU,CAAC,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;YAClD,CAAC,CAAC,CAAC;YACH,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YACxC,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACpC,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACpC,MAAM,OAAO,GAAG,WAAW,KAAK,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;YACjE,IAAI,OAA2B,CAAC;YAChC,IAAI,OAA2B,CAAC;YAChC,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC/B,mEAAmE;gBACnE,oEAAoE;gBACpE,mEAAmE;gBACnE,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC/D,MAAM,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;gBAC5C,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;YACzB,CAAC;iBAAM,CAAC;gBACN,kEAAkE;gBAClE,oEAAoE;gBACpE,2CAA2C;gBAC3C,MAAM,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;gBACnC,OAAO,GAAG,MAAM,UAAU,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YAClD,CAAC;YACD,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;4BACnB,GAAG,EAAE,eAAe,OAAO,EAAE;4BAC7B,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;4BAC/B,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;4BACrC,KAAK,EAAE,KAAK,CAAC,UAAU;4BACvB,MAAM,EAAE,IAAI,CAAC,MAAM;4BACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;yBACxB,CAAC;qBACH;iBACF;aACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["// packages/codesign-mcp/src/tools/export.ts\n//\n// `export` — spec §6.2. Writes a revision-pinned artifact into\n// `exports/<shard>/<rev>/<format>.<ext>` and returns a workspace URI envelope:\n// `uri` (the durable `workspace://` handle) plus `httpUrl` (the `/r/` fetch\n// link). `path` (an absolute disk path) is returned ONLY when the caller\n// passes an explicit `outPath` — a normal workspace export never discloses\n// the workspace's on-disk location.\n//\n// `target=video` is deferred to Phase 4.\nimport { promises as nodeFs } from 'node:fs';\nimport { dirname } from 'node:path';\nimport type { Mutex } from '../engine/mutex.js';\nimport type { EngineSession } from '../engine/session.js';\nimport type { RevisionStore } from '../revisions/store.js';\nimport type { CodesignMcpToolRegistration } from '../server.js';\nimport type { ViewerUrlBuilder } from '../viewer/url-builder.js';\nimport type { WorkspaceFS } from '../workspace/types.js';\n\ntype Target = 'pdf' | 'image' | 'video';\ntype Format = 'pdf' | 'png' | 'jpeg' | 'webp' | 'mp4';\n\ninterface MinimalEngine {\n  block: {\n    export(blockId: number, mimeType: string, options?: unknown): Promise<Blob>;\n  };\n}\n\ninterface ExportArgs {\n  target: Target;\n  format: Format;\n  revision: string;\n  blockId?: number;\n  outPath?: string;\n}\n\nconst TARGET_MIME: Record<'pdf' | 'image', Record<string, string>> = {\n  pdf: { pdf: 'application/pdf' },\n  image: { png: 'image/png', jpeg: 'image/jpeg', webp: 'image/webp' }\n};\n\nconst FORMAT_EXT: Record<Format, string> = {\n  pdf: 'pdf',\n  png: 'png',\n  jpeg: 'jpg',\n  webp: 'webp',\n  mp4: 'mp4'\n};\n\nconst DESCRIPTION = [\n  'Export a revision to pdf/image. Renders `blockId` and writes the result into the workspace under `exports/<shard>/<rev>/<target>.<ext>` (revision-pinned, deterministic).',\n  '',\n  'Returns JSON: `{ uri, httpUrl?, path?, bytes, format, revision }`. `uri` (a `workspace://` URI) is the durable handle. `httpUrl` is a fetch link for opening the artifact now — present for workspace exports, tied to this process. `path` (absolute disk path) is returned ONLY when you passed `outPath`.',\n  '',\n  '`target=video` is deferred to Phase 4.'\n].join('\\n');\n\n// The schema is built per-backend: `outPath` is advertised ONLY when the\n// backend honours it (Local). On Hosted the property is omitted entirely, so\n// an agent never sees an affordance it can't use — it can't try a local path\n// and hit a runtime rejection. The runtime guard in `call` stays as a backstop.\nfunction buildExportInputSchema(allowOutPath: boolean) {\n  const properties: Record<string, unknown> = {\n    target: { enum: ['pdf', 'image', 'video'] },\n    format: { enum: ['pdf', 'png', 'jpeg', 'webp', 'mp4'] },\n    revision: { type: 'string' as const },\n    blockId: {\n      type: 'integer' as const,\n      description: 'Required for pdf and image targets.'\n    }\n  };\n  if (allowOutPath) {\n    properties.outPath = {\n      type: 'string' as const,\n      description: 'Local-only escape hatch; absolute path.'\n    };\n  }\n  return {\n    type: 'object' as const,\n    properties,\n    required: ['target', 'format', 'revision'],\n    additionalProperties: false\n  };\n}\n\nexport interface CreateExportToolOptions<E = unknown> {\n  fs: WorkspaceFS;\n  store: RevisionStore;\n  session: EngineSession<E>;\n  /** Builds the `httpUrl` for workspace-written artifacts (the `/r/` route). */\n  urlBuilder: ViewerUrlBuilder;\n  /** Whether to honour an `outPath` argument (Local: yes; Hosted/sandbox: no). */\n  allowOutPath?: boolean;\n  /** Guards the shared engine — load-then-export must not interleave with another session's edit (see engine/mutex.ts). */\n  engineLock: Mutex;\n}\n\nexport function createExportTool<E = unknown>(\n  opts: CreateExportToolOptions<E>\n): CodesignMcpToolRegistration {\n  const {\n    fs,\n    store,\n    session,\n    urlBuilder,\n    allowOutPath = false,\n    engineLock\n  } = opts;\n  return {\n    name: 'export',\n    description: DESCRIPTION,\n    inputSchema: buildExportInputSchema(allowOutPath),\n    call: async (rawArgs) => {\n      const args = (rawArgs ?? {}) as Partial<ExportArgs>;\n      if (\n        typeof args.target !== 'string' ||\n        typeof args.format !== 'string' ||\n        typeof args.revision !== 'string'\n      ) {\n        return {\n          isError: true,\n          content: [\n            {\n              type: 'text' as const,\n              text: 'export: target, format, and revision are required.'\n            }\n          ]\n        };\n      }\n      if (args.target === 'video') {\n        return {\n          isError: true,\n          content: [\n            {\n              type: 'text' as const,\n              text: 'export: target=video is deferred to Phase 4.'\n            }\n          ]\n        };\n      }\n      if (args.outPath !== undefined && !allowOutPath) {\n        return {\n          isError: true,\n          content: [\n            {\n              type: 'text' as const,\n              text: 'export: `outPath` is not supported on this (hosted) backend. Omit it — the artifact is written to the workspace and returned as `httpUrl`; fetch that URL to download the bytes to disk.'\n            }\n          ]\n        };\n      }\n      const rev = await store.read(args.revision);\n      if (typeof args.blockId !== 'number') {\n        return {\n          isError: true,\n          content: [\n            {\n              type: 'text' as const,\n              text: `export: target=${args.target} requires \\`blockId\\`.`\n            }\n          ]\n        };\n      }\n      const mimeMap = TARGET_MIME[args.target as 'pdf' | 'image'];\n      const mime = mimeMap?.[args.format];\n      if (!mime) {\n        return {\n          isError: true,\n          content: [\n            {\n              type: 'text' as const,\n              text: `export: invalid format=${args.format} for target=${args.target}.`\n            }\n          ]\n        };\n      }\n      // Capture validated args into locals so the locked closure keeps the\n      // type narrowing the top-level guards established.\n      const revision = args.revision;\n      const blockId = args.blockId;\n      const sceneBytes = rev.scene;\n      // load-into-engine then export reads the shared engine across awaits —\n      // serialize against any concurrent engine-touching tool call.\n      const bytes = await engineLock.runExclusive(async () => {\n        await session.populate(revision, sceneBytes);\n        const slot = await session.acquire(revision);\n        const eng = slot.engine as MinimalEngine;\n        const blob = await eng.block.export(blockId, mime, {});\n        return new Uint8Array(await blob.arrayBuffer());\n      });\n      const shard = args.revision.slice(0, 2);\n      const rest = args.revision.slice(2);\n      const ext = FORMAT_EXT[args.format];\n      const relPath = `exports/${shard}/${rest}/${args.target}.${ext}`;\n      let absPath: string | undefined;\n      let httpUrl: string | undefined;\n      if (args.outPath !== undefined) {\n        // Local-only escape hatch: write through real disk fs, NOT through\n        // the workspace abstraction. The caller chose this path explicitly,\n        // so echoing it back is a confirmation, not a workspace-path leak.\n        await nodeFs.mkdir(dirname(args.outPath), { recursive: true });\n        await nodeFs.writeFile(args.outPath, bytes);\n        absPath = args.outPath;\n      } else {\n        // Workspace write — goes through the WorkspaceFS abstraction. The\n        // artifact is reachable over HTTP via the `/r/` route; the absolute\n        // disk path is deliberately NOT disclosed.\n        await fs.writeFile(relPath, bytes);\n        httpUrl = await urlBuilder.forDownload(relPath);\n      }\n      return {\n        content: [\n          {\n            type: 'text' as const,\n            text: JSON.stringify({\n              uri: `workspace://${relPath}`,\n              ...(httpUrl ? { httpUrl } : {}),\n              ...(absPath ? { path: absPath } : {}),\n              bytes: bytes.byteLength,\n              format: args.format,\n              revision: args.revision\n            })\n          }\n        ]\n      };\n    }\n  };\n}\n"]}

package/dist/tools/history.d.ts

@@ -0,0 +1,7 @@
+import type { RevisionStore } from '../revisions/store.js';
+import type { CodesignMcpToolRegistration } from '../server.js';
+export interface CreateHistoryToolOptions {
+    store: RevisionStore;
+}
+export declare function createHistoryTool(opts: CreateHistoryToolOptions): CodesignMcpToolRegistration;
+//# sourceMappingURL=history.d.ts.map

package/dist/tools/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/tools/history.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAEhE,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,wBAAwB,GAC7B,2BAA2B,CAsD7B"}

package/dist/tools/history.js

@@ -0,0 +1,54 @@
+export function createHistoryTool(opts) {
+    return {
+        name: 'history',
+        description: 'Walk back from `revision` to the root, returning the chain (root first). Each entry has `{ revision, parent, note?, createdAt }`. Use this to re-ground after a rewind: read the notes, pick the revision you want to continue from, pass it as `parent` to your next `edit`.',
+        inputSchema: {
+            type: 'object',
+            properties: { revision: { type: 'string' } },
+            required: ['revision'],
+            additionalProperties: false
+        },
+        call: async (rawArgs) => {
+            const args = (rawArgs ?? {});
+            if (typeof args.revision !== 'string') {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'history: `revision` (string) is required.'
+                        }
+                    ]
+                };
+            }
+            try {
+                const chain = await opts.store.historyOf(args.revision);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(chain.map((r) => ({
+                                revision: r.id,
+                                parent: r.meta.parent,
+                                note: r.meta.note,
+                                createdAt: r.meta.createdAt
+                            })))
+                        }
+                    ]
+                };
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: `history: ${err instanceof Error ? err.message : String(err)}`
+                        }
+                    ]
+                };
+            }
+        }
+    };
+}
+//# sourceMappingURL=history.js.map

package/dist/tools/history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.js","sourceRoot":"","sources":["../../src/tools/history.ts"],"names":[],"mappings":"AAOA,MAAM,UAAU,iBAAiB,CAC/B,IAA8B;IAE9B,OAAO;QACL,IAAI,EAAE,SAAS;QACf,WAAW,EACT,+QAA+Q;QACjR,WAAW,EAAE;YACX,IAAI,EAAE,QAAiB;YACvB,UAAU,EAAE,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAiB,EAAE,EAAE;YACrD,QAAQ,EAAE,CAAC,UAAU,CAAC;YACtB,oBAAoB,EAAE,KAAK;SAC5B;QACD,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YACtB,MAAM,IAAI,GAAG,CAAC,OAAO,IAAI,EAAE,CAA0B,CAAC;YACtD,IAAI,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBACtC,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,2CAA2C;yBAClD;qBACF;iBACF,CAAC;YACJ,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACxD,OAAO;oBACL,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAClB,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gCAChB,QAAQ,EAAE,CAAC,CAAC,EAAE;gCACd,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM;gCACrB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI;gCACjB,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS;6BAC5B,CAAC,CAAC,CACJ;yBACF;qBACF;iBACF,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,YAAY,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;yBACrE;qBACF;iBACF,CAAC;YACJ,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type { RevisionStore } from '../revisions/store.js';\nimport type { CodesignMcpToolRegistration } from '../server.js';\n\nexport interface CreateHistoryToolOptions {\n  store: RevisionStore;\n}\n\nexport function createHistoryTool(\n  opts: CreateHistoryToolOptions\n): CodesignMcpToolRegistration {\n  return {\n    name: 'history',\n    description:\n      'Walk back from `revision` to the root, returning the chain (root first). Each entry has `{ revision, parent, note?, createdAt }`. Use this to re-ground after a rewind: read the notes, pick the revision you want to continue from, pass it as `parent` to your next `edit`.',\n    inputSchema: {\n      type: 'object' as const,\n      properties: { revision: { type: 'string' as const } },\n      required: ['revision'],\n      additionalProperties: false\n    },\n    call: async (rawArgs) => {\n      const args = (rawArgs ?? {}) as { revision?: string };\n      if (typeof args.revision !== 'string') {\n        return {\n          isError: true,\n          content: [\n            {\n              type: 'text' as const,\n              text: 'history: `revision` (string) is required.'\n            }\n          ]\n        };\n      }\n      try {\n        const chain = await opts.store.historyOf(args.revision);\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: JSON.stringify(\n                chain.map((r) => ({\n                  revision: r.id,\n                  parent: r.meta.parent,\n                  note: r.meta.note,\n                  createdAt: r.meta.createdAt\n                }))\n              )\n            }\n          ]\n        };\n      } catch (err) {\n        return {\n          isError: true,\n          content: [\n            {\n              type: 'text' as const,\n              text: `history: ${err instanceof Error ? err.message : String(err)}`\n            }\n          ]\n        };\n      }\n    }\n  };\n}\n"]}

package/dist/tools/index.d.ts

@@ -0,0 +1,35 @@
+import type { Mutex } from '../engine/mutex.js';
+import type { EngineSession } from '../engine/session.js';
+import type { GatewayClient } from '../gateway/types.js';
+import type { RevisionStore } from '../revisions/store.js';
+import type { CodesignMcpToolRegistration } from '../server.js';
+import type { ViewerUrlBuilder } from '../viewer/url-builder.js';
+import type { WorkspaceFS } from '../workspace/types.js';
+export interface BuildDesignToolRegistrationsOptions<E = unknown> {
+    fs: WorkspaceFS;
+    store: RevisionStore;
+    session: EngineSession<E>;
+    /**
+     * Serializes access to the shared CE.SDK engine across the edit/preview/
+     * export tools. One engine today (process singleton) ⇒ one lock shared by
+     * every session. See engine/mutex.ts and the bootstrap (cli/http.ts,
+     * cli/stdio.ts) for where it is created.
+     */
+    engineLock: Mutex;
+    gateway: GatewayClient;
+    urlBuilder: ViewerUrlBuilder;
+    /** True on Local (the `outPath?` escape hatch is allowed); false on Hosted/sandbox. */
+    allowOutPath: boolean;
+    /** Called when `edit` writes a new leaf revision (viewer SSE hook). */
+    onLeafWritten?: (event: {
+        revision: string;
+        rootRevision: string;
+    }) => void | Promise<void>;
+    /** Render a thumbnail for a newly committed revision. Optional; best-effort. */
+    renderThumbnail?: (event: {
+        revision: string;
+        engine: E;
+    }) => Promise<Uint8Array>;
+}
+export declare function buildDesignToolRegistrations<E = unknown>(opts: BuildDesignToolRegistrationsOptions<E>): CodesignMcpToolRegistration[];
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAazD,MAAM,WAAW,mCAAmC,CAAC,CAAC,GAAG,OAAO;IAC9D,EAAE,EAAE,WAAW,CAAC;IAChB,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAC1B;;;;;OAKG;IACH,UAAU,EAAE,KAAK,CAAC;IAClB,OAAO,EAAE,aAAa,CAAC;IACvB,UAAU,EAAE,gBAAgB,CAAC;IAC7B,uFAAuF;IACvF,YAAY,EAAE,OAAO,CAAC;IACtB,uEAAuE;IACvE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;KACtB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,gFAAgF;IAChF,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,CAAC,CAAC;KACX,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CAC3B;AAED,wBAAgB,4BAA4B,CAAC,CAAC,GAAG,OAAO,EACtD,IAAI,EAAE,mCAAmC,CAAC,CAAC,CAAC,GAC3C,2BAA2B,EAAE,CAsD/B"}

package/dist/tools/index.js

@@ -0,0 +1,72 @@
+// packages/codesign-mcp/src/tools/index.ts
+//
+// Builds the design + workspace tool registrations from a fully-DI'd set of
+// primitives: nine always-on tools, plus `asset_generate` only when the
+// gateway is actually usable (Local: API_KEY set). A hidden tool never shows
+// up in tools/list, so the model won't attempt a call that can only fail.
+// Each variant's CLI bootstrap (cli/stdio.ts, cli/http.ts)
+// constructs these primitives once and passes them in; this file owns no
+// engine bootstrap, no FS bootstrap, no gateway selection.
+import { createAssetGenerateTool } from './asset-generate.js';
+import { createAssetSearchTool } from './asset-search.js';
+import { createEditTool } from './edit.js';
+import { createExportTool } from './export.js';
+import { createHistoryTool } from './history.js';
+import { createInspectTool } from './inspect.js';
+import { createListTool } from './list.js';
+import { createOpenEditorTool } from './open-editor.js';
+import { createPreviewTool } from './preview.js';
+import { createRenameTool } from './rename.js';
+import { createSaveTool } from './save.js';
+export function buildDesignToolRegistrations(opts) {
+    const registrations = [
+        createEditTool({
+            store: opts.store,
+            session: opts.session,
+            engineLock: opts.engineLock,
+            onLeafWritten: opts.onLeafWritten,
+            renderThumbnail: opts.renderThumbnail,
+            fs: opts.fs
+        }),
+        createPreviewTool({
+            store: opts.store,
+            session: opts.session,
+            engineLock: opts.engineLock
+        }),
+        createExportTool({
+            fs: opts.fs,
+            store: opts.store,
+            session: opts.session,
+            engineLock: opts.engineLock,
+            urlBuilder: opts.urlBuilder,
+            allowOutPath: opts.allowOutPath
+        }),
+        createSaveTool({
+            fs: opts.fs,
+            store: opts.store,
+            session: opts.session,
+            engineLock: opts.engineLock,
+            urlBuilder: opts.urlBuilder,
+            allowOutPath: opts.allowOutPath
+        }),
+        createListTool({ store: opts.store }),
+        createHistoryTool({ store: opts.store }),
+        createInspectTool({ store: opts.store }),
+        createRenameTool({ store: opts.store }),
+        createOpenEditorTool({ urlBuilder: opts.urlBuilder, store: opts.store }),
+        createAssetSearchTool({
+            session: opts.session,
+            engineLock: opts.engineLock
+        })
+    ];
+    // Opt-in: only expose asset_generate when the gateway can fulfil a request.
+    if (opts.gateway.available) {
+        registrations.push(createAssetGenerateTool({
+            gateway: opts.gateway,
+            fs: opts.fs,
+            urlBuilder: opts.urlBuilder
+        }));
+    }
+    return registrations;
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"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","sourcesContent":["// packages/codesign-mcp/src/tools/index.ts\n//\n// Builds the design + workspace tool registrations from a fully-DI'd set of\n// primitives: nine always-on tools, plus `asset_generate` only when the\n// gateway is actually usable (Local: API_KEY set). A hidden tool never shows\n// up in tools/list, so the model won't attempt a call that can only fail.\n// Each variant's CLI bootstrap (cli/stdio.ts, cli/http.ts)\n// constructs these primitives once and passes them in; this file owns no\n// engine bootstrap, no FS bootstrap, no gateway selection.\n\nimport type { Mutex } from '../engine/mutex.js';\nimport type { EngineSession } from '../engine/session.js';\nimport type { GatewayClient } from '../gateway/types.js';\nimport type { RevisionStore } from '../revisions/store.js';\nimport type { CodesignMcpToolRegistration } from '../server.js';\nimport type { ViewerUrlBuilder } from '../viewer/url-builder.js';\nimport type { WorkspaceFS } from '../workspace/types.js';\nimport { createAssetGenerateTool } from './asset-generate.js';\nimport { createAssetSearchTool } from './asset-search.js';\nimport { createEditTool } from './edit.js';\nimport { createExportTool } from './export.js';\nimport { createHistoryTool } from './history.js';\nimport { createInspectTool } from './inspect.js';\nimport { createListTool } from './list.js';\nimport { createOpenEditorTool } from './open-editor.js';\nimport { createPreviewTool } from './preview.js';\nimport { createRenameTool } from './rename.js';\nimport { createSaveTool } from './save.js';\n\nexport interface BuildDesignToolRegistrationsOptions<E = unknown> {\n  fs: WorkspaceFS;\n  store: RevisionStore;\n  session: EngineSession<E>;\n  /**\n   * Serializes access to the shared CE.SDK engine across the edit/preview/\n   * export tools. One engine today (process singleton) ⇒ one lock shared by\n   * every session. See engine/mutex.ts and the bootstrap (cli/http.ts,\n   * cli/stdio.ts) for where it is created.\n   */\n  engineLock: Mutex;\n  gateway: GatewayClient;\n  urlBuilder: ViewerUrlBuilder;\n  /** True on Local (the `outPath?` escape hatch is allowed); false on Hosted/sandbox. */\n  allowOutPath: boolean;\n  /** Called when `edit` writes a new leaf revision (viewer SSE hook). */\n  onLeafWritten?: (event: {\n    revision: string;\n    rootRevision: string;\n  }) => void | Promise<void>;\n  /** Render a thumbnail for a newly committed revision. Optional; best-effort. */\n  renderThumbnail?: (event: {\n    revision: string;\n    engine: E;\n  }) => Promise<Uint8Array>;\n}\n\nexport function buildDesignToolRegistrations<E = unknown>(\n  opts: BuildDesignToolRegistrationsOptions<E>\n): CodesignMcpToolRegistration[] {\n  const registrations: CodesignMcpToolRegistration[] = [\n    createEditTool({\n      store: opts.store,\n      session: opts.session,\n      engineLock: opts.engineLock,\n      onLeafWritten: opts.onLeafWritten,\n      renderThumbnail: opts.renderThumbnail,\n      fs: opts.fs\n    }),\n    createPreviewTool({\n      store: opts.store,\n      session: opts.session,\n      engineLock: opts.engineLock\n    }),\n    createExportTool({\n      fs: opts.fs,\n      store: opts.store,\n      session: opts.session,\n      engineLock: opts.engineLock,\n      urlBuilder: opts.urlBuilder,\n      allowOutPath: opts.allowOutPath\n    }),\n    createSaveTool({\n      fs: opts.fs,\n      store: opts.store,\n      session: opts.session,\n      engineLock: opts.engineLock,\n      urlBuilder: opts.urlBuilder,\n      allowOutPath: opts.allowOutPath\n    }),\n    createListTool({ store: opts.store }),\n    createHistoryTool({ store: opts.store }),\n    createInspectTool({ store: opts.store }),\n    createRenameTool({ store: opts.store }),\n    createOpenEditorTool({ urlBuilder: opts.urlBuilder, store: opts.store }),\n    createAssetSearchTool({\n      session: opts.session,\n      engineLock: opts.engineLock\n    })\n  ];\n\n  // Opt-in: only expose asset_generate when the gateway can fulfil a request.\n  if (opts.gateway.available) {\n    registrations.push(\n      createAssetGenerateTool({\n        gateway: opts.gateway,\n        fs: opts.fs,\n        urlBuilder: opts.urlBuilder\n      })\n    );\n  }\n\n  return registrations;\n}\n"]}

package/dist/tools/inspect.d.ts

@@ -0,0 +1,7 @@
+import type { RevisionStore } from '../revisions/store.js';
+import type { CodesignMcpToolRegistration } from '../server.js';
+export interface CreateInspectToolOptions {
+    store: RevisionStore;
+}
+export declare function createInspectTool(opts: CreateInspectToolOptions): CodesignMcpToolRegistration;
+//# sourceMappingURL=inspect.d.ts.map

package/dist/tools/inspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../src/tools/inspect.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAEhE,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,aAAa,CAAC;CACtB;AAwBD,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,wBAAwB,GAC7B,2BAA2B,CAsD7B"}

package/dist/tools/inspect.js

@@ -0,0 +1,80 @@
+// `inspect` — single-revision counterpart to `history`. Returns one revision's
+// metadata plus the JS code that produced it (when the revision was written
+// through `edit`). The companion read to the note field — where `history`
+// gives you the chain of summaries, `inspect` gives you one revision in full.
+//
+// Why a separate tool and not a field on `history`: code blobs can be 100s of
+// lines, and the dominant `history` use ("skim the notes, pick a revision")
+// shouldn't pay for that on every call.
+const DESCRIPTION = [
+    'Read one revision in full: parent, note, createdAt, title (root only), and the JS code that produced it (when written via `edit`).',
+    '',
+    "Use this after `history` when you've picked a revision and want to know HOW it got there — the code is the precise operation; `note` is the agent's summary.",
+    '',
+    'Returns JSON `{ revision, parent, note?, createdAt, title?, code? }`. `code` is omitted for revisions not produced by `edit` (e.g. future import paths).',
+    '',
+    "⚠ Past code reveals the PATTERN of an edit (which APIs were called, what kind of block was targeted), NOT the block ids. Block ids are session-scoped — re-discover them in the current engine; don't replay the literal numeric ids."
+].join('\n');
+const INSPECT_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        revision: {
+            type: 'string',
+            description: 'Revision id to inspect.'
+        }
+    },
+    required: ['revision'],
+    additionalProperties: false
+};
+export function createInspectTool(opts) {
+    return {
+        name: 'inspect',
+        description: DESCRIPTION,
+        inputSchema: INSPECT_INPUT_SCHEMA,
+        call: async (rawArgs) => {
+            const args = (rawArgs ?? {});
+            if (typeof args.revision !== 'string') {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'inspect: `revision` (string) is required.'
+                        }
+                    ]
+                };
+            }
+            try {
+                const rev = await opts.store.read(args.revision);
+                const code = await opts.store.readCode(args.revision);
+                const body = {
+                    revision: rev.id,
+                    parent: rev.meta.parent,
+                    createdAt: rev.meta.createdAt
+                };
+                if (rev.meta.note !== undefined)
+                    body.note = rev.meta.note;
+                if (rev.meta.title !== undefined)
+                    body.title = rev.meta.title;
+                if (code !== undefined)
+                    body.code = code;
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(body) }]
+                };
+            }
+            catch (err) {
+                const code = err.code;
+                const msg = code === 'ENOENT'
+                    ? `unknown revision ${args.revision}`
+                    : err instanceof Error
+                        ? err.message
+                        : String(err);
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: `inspect: ${msg}` }]
+                };
+            }
+        }
+    };
+}
+//# sourceMappingURL=inspect.js.map

package/dist/tools/inspect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.js","sourceRoot":"","sources":["../../src/tools/inspect.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,4EAA4E;AAC5E,0EAA0E;AAC1E,8EAA8E;AAC9E,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,wCAAwC;AASxC,MAAM,WAAW,GAAG;IAClB,oIAAoI;IACpI,EAAE;IACF,8JAA8J;IAC9J,EAAE;IACF,0JAA0J;IAC1J,EAAE;IACF,uOAAuO;CACxO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,oBAAoB,GAAG;IAC3B,IAAI,EAAE,QAAiB;IACvB,UAAU,EAAE;QACV,QAAQ,EAAE;YACR,IAAI,EAAE,QAAiB;YACvB,WAAW,EAAE,yBAAyB;SACvC;KACF;IACD,QAAQ,EAAE,CAAC,UAAU,CAAC;IACtB,oBAAoB,EAAE,KAAK;CAC5B,CAAC;AAEF,MAAM,UAAU,iBAAiB,CAC/B,IAA8B;IAE9B,OAAO;QACL,IAAI,EAAE,SAAS;QACf,WAAW,EAAE,WAAW;QACxB,WAAW,EAAE,oBAAoB;QACjC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YACtB,MAAM,IAAI,GAAG,CAAC,OAAO,IAAI,EAAE,CAA0B,CAAC;YACtD,IAAI,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBACtC,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,2CAA2C;yBAClD;qBACF;iBACF,CAAC;YACJ,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACjD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACtD,MAAM,IAAI,GAON;oBACF,QAAQ,EAAE,GAAG,CAAC,EAAE;oBAChB,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,MAAM;oBACvB,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS;iBAC9B,CAAC;gBACF,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS;oBAAE,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;gBAC3D,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS;oBAAE,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC;gBAC9D,IAAI,IAAI,KAAK,SAAS;oBAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;gBACzC,OAAO;oBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;iBACjE,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,IAAI,GAAI,GAAyB,CAAC,IAAI,CAAC;gBAC7C,MAAM,GAAG,GACP,IAAI,KAAK,QAAQ;oBACf,CAAC,CAAC,oBAAoB,IAAI,CAAC,QAAQ,EAAE;oBACrC,CAAC,CAAC,GAAG,YAAY,KAAK;wBACpB,CAAC,CAAC,GAAG,CAAC,OAAO;wBACb,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACpB,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,YAAY,GAAG,EAAE,EAAE,CAAC;iBAC9D,CAAC;YACJ,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["// `inspect` — single-revision counterpart to `history`. Returns one revision's\n// metadata plus the JS code that produced it (when the revision was written\n// through `edit`). The companion read to the note field — where `history`\n// gives you the chain of summaries, `inspect` gives you one revision in full.\n//\n// Why a separate tool and not a field on `history`: code blobs can be 100s of\n// lines, and the dominant `history` use (\"skim the notes, pick a revision\")\n// shouldn't pay for that on every call.\n\nimport type { RevisionStore } from '../revisions/store.js';\nimport type { CodesignMcpToolRegistration } from '../server.js';\n\nexport interface CreateInspectToolOptions {\n  store: RevisionStore;\n}\n\nconst DESCRIPTION = [\n  'Read one revision in full: parent, note, createdAt, title (root only), and the JS code that produced it (when written via `edit`).',\n  '',\n  \"Use this after `history` when you've picked a revision and want to know HOW it got there — the code is the precise operation; `note` is the agent's summary.\",\n  '',\n  'Returns JSON `{ revision, parent, note?, createdAt, title?, code? }`. `code` is omitted for revisions not produced by `edit` (e.g. future import paths).',\n  '',\n  \"⚠ Past code reveals the PATTERN of an edit (which APIs were called, what kind of block was targeted), NOT the block ids. Block ids are session-scoped — re-discover them in the current engine; don't replay the literal numeric ids.\"\n].join('\\n');\n\nconst INSPECT_INPUT_SCHEMA = {\n  type: 'object' as const,\n  properties: {\n    revision: {\n      type: 'string' as const,\n      description: 'Revision id to inspect.'\n    }\n  },\n  required: ['revision'],\n  additionalProperties: false\n};\n\nexport function createInspectTool(\n  opts: CreateInspectToolOptions\n): CodesignMcpToolRegistration {\n  return {\n    name: 'inspect',\n    description: DESCRIPTION,\n    inputSchema: INSPECT_INPUT_SCHEMA,\n    call: async (rawArgs) => {\n      const args = (rawArgs ?? {}) as { revision?: string };\n      if (typeof args.revision !== 'string') {\n        return {\n          isError: true,\n          content: [\n            {\n              type: 'text' as const,\n              text: 'inspect: `revision` (string) is required.'\n            }\n          ]\n        };\n      }\n      try {\n        const rev = await opts.store.read(args.revision);\n        const code = await opts.store.readCode(args.revision);\n        const body: {\n          revision: string;\n          parent: string | null;\n          note?: string;\n          createdAt: number;\n          title?: string;\n          code?: string;\n        } = {\n          revision: rev.id,\n          parent: rev.meta.parent,\n          createdAt: rev.meta.createdAt\n        };\n        if (rev.meta.note !== undefined) body.note = rev.meta.note;\n        if (rev.meta.title !== undefined) body.title = rev.meta.title;\n        if (code !== undefined) body.code = code;\n        return {\n          content: [{ type: 'text' as const, text: JSON.stringify(body) }]\n        };\n      } catch (err) {\n        const code = (err as { code?: string }).code;\n        const msg =\n          code === 'ENOENT'\n            ? `unknown revision ${args.revision}`\n            : err instanceof Error\n              ? err.message\n              : String(err);\n        return {\n          isError: true,\n          content: [{ type: 'text' as const, text: `inspect: ${msg}` }]\n        };\n      }\n    }\n  };\n}\n"]}

package/dist/tools/list.d.ts

@@ -0,0 +1,7 @@
+import type { RevisionStore } from '../revisions/store.js';
+import type { CodesignMcpToolRegistration } from '../server.js';
+export interface CreateListToolOptions {
+    store: RevisionStore;
+}
+export declare function createListTool(opts: CreateListToolOptions): CodesignMcpToolRegistration;
+//# sourceMappingURL=list.d.ts.map

package/dist/tools/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/tools/list.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAEhE,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,qBAAqB,GAC1B,2BAA2B,CAiB7B"}

package/dist/tools/list.js

@@ -0,0 +1,18 @@
+export function createListTool(opts) {
+    return {
+        name: 'list',
+        description: 'List designs in the workspace. Returns an array of `{ rootRevision, title, latestLeaf, updatedAt }` sorted newest-first. The re-grounding entry point after a process restart.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false
+        },
+        call: async () => {
+            const roots = await opts.store.listRoots();
+            return {
+                content: [{ type: 'text', text: JSON.stringify(roots) }]
+            };
+        }
+    };
+}
+//# sourceMappingURL=list.js.map

package/dist/tools/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../src/tools/list.ts"],"names":[],"mappings":"AAOA,MAAM,UAAU,cAAc,CAC5B,IAA2B;IAE3B,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,WAAW,EACT,gLAAgL;QAClL,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,EAAE;YACd,oBAAoB,EAAE,KAAK;SAC5B;QACD,IAAI,EAAE,KAAK,IAAI,EAAE;YACf,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;YAC3C,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;aAClE,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type { RevisionStore } from '../revisions/store.js';\nimport type { CodesignMcpToolRegistration } from '../server.js';\n\nexport interface CreateListToolOptions {\n  store: RevisionStore;\n}\n\nexport function createListTool(\n  opts: CreateListToolOptions\n): CodesignMcpToolRegistration {\n  return {\n    name: 'list',\n    description:\n      'List designs in the workspace. Returns an array of `{ rootRevision, title, latestLeaf, updatedAt }` sorted newest-first. The re-grounding entry point after a process restart.',\n    inputSchema: {\n      type: 'object',\n      properties: {},\n      additionalProperties: false\n    },\n    call: async () => {\n      const roots = await opts.store.listRoots();\n      return {\n        content: [{ type: 'text' as const, text: JSON.stringify(roots) }]\n      };\n    }\n  };\n}\n"]}

package/dist/tools/metrics.d.ts

@@ -0,0 +1,11 @@
+import type { MetricsRecorder } from '../metrics/recorder.js';
+import type { CodesignMcpToolRegistration } from '../server.js';
+export interface CreateMetricsToolOptions {
+    recorder: MetricsRecorder;
+    /** Live active-session count, read at call time (mirrors metrics/mount.ts). */
+    activeSessions: () => number;
+    /** The session/RAM cap (ServerConfig.maxEngines) — the gauge denominator. */
+    maxSessions: number;
+}
+export declare function createMetricsTool(opts: CreateMetricsToolOptions): CodesignMcpToolRegistration;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/tools/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/tools/metrics.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAEhE,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,eAAe,CAAC;IAC1B,+EAA+E;IAC/E,cAAc,EAAE,MAAM,MAAM,CAAC;IAC7B,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;CACrB;AAOD,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,wBAAwB,GAC7B,2BAA2B,CAuB7B"}

package/dist/tools/metrics.js

@@ -0,0 +1,28 @@
+const DESCRIPTION = 'Performance metrics of this MCP server process: per-tool call counts, error counts and ' +
+    'duration percentiles (ms), recent tool calls, process memory, session usage, and uptime. ' +
+    'Use when the human asks how the server is performing or how long tool calls take.';
+export function createMetricsTool(opts) {
+    return {
+        name: 'metrics',
+        description: DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false
+        },
+        call: async () => ({
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        ...opts.recorder.snapshot(),
+                        activeSessions: opts.activeSessions(),
+                        maxSessions: opts.maxSessions,
+                        uptimeMs: Math.round(process.uptime() * 1000)
+                    })
+                }
+            ]
+        })
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/tools/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/tools/metrics.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,GACf,yFAAyF;IACzF,2FAA2F;IAC3F,mFAAmF,CAAC;AAEtF,MAAM,UAAU,iBAAiB,CAC/B,IAA8B;IAE9B,OAAO;QACL,IAAI,EAAE,SAAS;QACf,WAAW,EAAE,WAAW;QACxB,WAAW,EAAE;YACX,IAAI,EAAE,QAAiB;YACvB,UAAU,EAAE,EAAE;YACd,oBAAoB,EAAE,KAAK;SAC5B;QACD,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;YACjB,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;wBACnB,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE;wBAC3B,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE;wBACrC,WAAW,EAAE,IAAI,CAAC,WAAW;wBAC7B,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC;qBAC9C,CAAC;iBACH;aACF;SACF,CAAC;KACH,CAAC;AACJ,CAAC","sourcesContent":["// packages/codesign-mcp/src/tools/metrics.ts\n//\n// `metrics` MCP tool — returns the same merged snapshot the GET /metrics route\n// serves (metrics/mount.ts), inline over MCP. This is how a hosted MCP client\n// reads server metrics without a hosted dashboard: on Cloudflare each session\n// has its own container, so the snapshot describes THIS session's server\n// process. Registered only when IMGLY_METRICS_ENABLED is on.\nimport type { MetricsRecorder } from '../metrics/recorder.js';\nimport type { CodesignMcpToolRegistration } from '../server.js';\n\nexport interface CreateMetricsToolOptions {\n  recorder: MetricsRecorder;\n  /** Live active-session count, read at call time (mirrors metrics/mount.ts). */\n  activeSessions: () => number;\n  /** The session/RAM cap (ServerConfig.maxEngines) — the gauge denominator. */\n  maxSessions: number;\n}\n\nconst DESCRIPTION =\n  'Performance metrics of this MCP server process: per-tool call counts, error counts and ' +\n  'duration percentiles (ms), recent tool calls, process memory, session usage, and uptime. ' +\n  'Use when the human asks how the server is performing or how long tool calls take.';\n\nexport function createMetricsTool(\n  opts: CreateMetricsToolOptions\n): CodesignMcpToolRegistration {\n  return {\n    name: 'metrics',\n    description: DESCRIPTION,\n    inputSchema: {\n      type: 'object' as const,\n      properties: {},\n      additionalProperties: false\n    },\n    call: async () => ({\n      content: [\n        {\n          type: 'text' as const,\n          text: JSON.stringify({\n            ...opts.recorder.snapshot(),\n            activeSessions: opts.activeSessions(),\n            maxSessions: opts.maxSessions,\n            uptimeMs: Math.round(process.uptime() * 1000)\n          })\n        }\n      ]\n    })\n  };\n}\n"]}

package/dist/tools/open-editor.d.ts

@@ -0,0 +1,10 @@
+import type { RevisionStore } from '../revisions/store.js';
+import type { CodesignMcpToolRegistration } from '../server.js';
+import type { ViewerUrlBuilder } from '../viewer/url-builder.js';
+export interface CreateOpenEditorToolOptions {
+    urlBuilder: ViewerUrlBuilder;
+    /** Resolves a revision to its design root (the root revision id). */
+    store: RevisionStore;
+}
+export declare function createOpenEditorTool(opts: CreateOpenEditorToolOptions): CodesignMcpToolRegistration;
+//# sourceMappingURL=open-editor.d.ts.map

package/dist/tools/open-editor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-editor.d.ts","sourceRoot":"","sources":["../../src/tools/open-editor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,MAAM,WAAW,2BAA2B;IAC1C,UAAU,EAAE,gBAAgB,CAAC;IAC7B,qEAAqE;IACrE,KAAK,EAAE,aAAa,CAAC;CACtB;AASD,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,2BAA2B,GAChC,2BAA2B,CAyD7B"}