callman-mcp 0.1.0

package/dist-cjs/run/summarize.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summarizeRun = exports.summarizeResult = void 0;
+const mask_js_1 = require("../lib/mask.js");
+const truncate_js_1 = require("../lib/truncate.js");
+const executeCollection_js_1 = require("./executeCollection.js");
+// What a local run reports back to the model: enough to judge and debug
+// (status, timing, tests, a bounded body preview, the request as SENT with
+// sensitive headers masked) and nothing that leaks credentials — variable
+// VALUES never appear, only the keys scripts changed.
+const KEEP_RESPONSE_HEADERS = new Set([
+    "content-type",
+    "content-length",
+    "location",
+    "cache-control",
+    "x-request-id",
+    "x-correlation-id",
+    "retry-after",
+    "www-authenticate",
+]);
+const responseHeadersOf = (response) => {
+    const headers = response?.headers;
+    if (!headers || typeof headers !== "object")
+        return {};
+    const out = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (KEEP_RESPONSE_HEADERS.has(key.toLowerCase()))
+            out[key] = Array.isArray(value) ? value.join(", ") : String(value);
+    }
+    return out;
+};
+const bodyOf = (response) => {
+    if (!response || typeof response !== "object")
+        return null;
+    const record = response;
+    return record.data !== undefined ? record.data : record.body !== undefined ? record.body : null;
+};
+const summarizeResult = (result, maxBodyBytes) => {
+    const body = bodyOf(result.response);
+    const bodyText = body === null || body === undefined ? "" : typeof body === "string" ? body : (0, truncate_js_1.safeStringify)(body);
+    const clipped = (0, truncate_js_1.clipBytes)(bodyText, maxBodyBytes);
+    const sent = result.request;
+    return {
+        requestId: result.requestId,
+        name: result.requestName ?? result.requestId,
+        passed: !(0, executeCollection_js_1.requestFailed)(result),
+        status: result.status,
+        durationMs: result.duration,
+        request: sent
+            ? {
+                method: sent.method,
+                url: (0, truncate_js_1.clip)(sent.url, 2048),
+                headers: (0, mask_js_1.maskHeaderRecord)(sent.headers),
+                ...(sent.body !== undefined && sent.body !== null ? { body: (0, truncate_js_1.clip)(typeof sent.body === "string" ? sent.body : (0, truncate_js_1.safeStringify)(sent.body), truncate_js_1.LIMITS.BODY_PREVIEW) } : {}),
+            }
+            : null,
+        response: {
+            headers: responseHeadersOf(result.response),
+            body: clipped.text || null,
+            ...(clipped.truncated ? { bodyTruncated: true, bodyBytes: clipped.totalBytes } : {}),
+        },
+        tests: result.scriptResults.map((test) => ({ name: test.name, status: test.status, ...(test.message ? { message: (0, truncate_js_1.clip)(test.message, 300) } : {}) })),
+        contracts: result.contractResults.map((test) => ({ name: test.name, status: test.status, ...(test.message ? { message: (0, truncate_js_1.clip)(test.message, 300) } : {}) })),
+    };
+};
+exports.summarizeResult = summarizeResult;
+const summarizeRun = (outcome, maxBodyBytes, extra = {}) => ({
+    ...extra,
+    summary: { ...outcome.summary, bailed: outcome.bailed },
+    results: outcome.results.map((result) => (0, exports.summarizeResult)(result, maxBodyBytes)),
+    env: outcome.envChanges,
+});
+exports.summarizeRun = summarizeRun;

package/dist-cjs/run/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist-cjs/server.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCallmanMcpServer = exports.SERVER_INSTRUCTIONS = exports.SERVER_NAME = void 0;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const context_js_1 = require("./context.js");
+const index_js_1 = require("./prompts/index.js");
+const index_js_2 = require("./resources/index.js");
+const index_js_3 = require("./tools/index.js");
+exports.SERVER_NAME = "callman";
+exports.SERVER_INSTRUCTIONS = `Callman is an API client and test platform: collections of HTTP requests, environments with variables, multi-step test scenarios, and system-design diagrams. You act as the user whose token is configured, within that token's permissions and the user's workspace role.
+Start with whoami. Names work as references (collection, folder, request, environment, scenario, diagram, workspace); ambiguous names return candidates. List before creating — duplicate collection names are refused. Preview large writes with dryRun: true; deletions need confirm: true and the user's agreement. Environment values are masked unless the token holds environments:reveal and you pass reveal: true; never write a masked value back. Read callman://docs/overview for the conventions, callman://docs/request-schema before creating requests, callman://docs/scenario-nodes before scenarios, and callman://diagram/components before diagrams.`;
+const createCallmanMcpServer = (options) => {
+    const version = options.version ?? "0.0.0";
+    const context = (0, context_js_1.createToolContext)({
+        config: options.config,
+        version,
+        fetch: options.fetch,
+        logger: options.logger,
+        cacheTtlMs: options.cacheTtlMs,
+        pollDelaysMs: options.pollDelaysMs,
+    });
+    const server = new mcp_js_1.McpServer({ name: exports.SERVER_NAME, version, title: "Callman" }, { capabilities: { tools: {}, resources: {}, prompts: {} }, instructions: exports.SERVER_INSTRUCTIONS });
+    (0, index_js_3.registerAllTools)(server, context);
+    (0, index_js_2.registerResources)(server, context);
+    (0, index_js_1.registerPrompts)(server, context);
+    return { server, context };
+};
+exports.createCallmanMcpServer = createCallmanMcpServer;

package/dist-cjs/tools/catalog.js

@@ -0,0 +1,69 @@
+"use strict";
+// The tool ↔ scope catalog: what a token needs for each tool. Used by
+// `whoami` to tell the model up front which tools will work with the current
+// token, by the README/in-app guide (kept in sync by hand), and by the
+// backend host later to advertise the same list.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolAvailability = exports.TOOL_CATALOG = void 0;
+exports.TOOL_CATALOG = [
+    { name: "whoami", group: "meta", scopes: [] },
+    { name: "list_workspaces", group: "workspaces", scopes: ["workspaces:read"] },
+    { name: "list_workspace_members", group: "workspaces", scopes: ["workspaces:read"] },
+    { name: "add_workspace_member", group: "workspaces", scopes: ["members:manage"] },
+    { name: "remove_workspace_member", group: "workspaces", scopes: ["members:manage"], destructive: true },
+    { name: "list_collections", group: "collections", scopes: ["collections:read"] },
+    { name: "get_collection_tree", group: "collections", scopes: ["collections:read", "requests:read"] },
+    { name: "export_collection", group: "collections", scopes: ["collections:read"] },
+    { name: "create_collection", group: "collections", scopes: ["collections:write"] },
+    { name: "update_collection", group: "collections", scopes: ["collections:write"] },
+    { name: "create_folder", group: "collections", scopes: ["collections:write"] },
+    { name: "update_folder", group: "collections", scopes: ["collections:write"] },
+    { name: "delete_collection", group: "collections", scopes: ["collections:delete"], destructive: true },
+    { name: "delete_folder", group: "collections", scopes: ["collections:delete"], destructive: true },
+    { name: "search_requests", group: "requests", scopes: ["requests:read"] },
+    { name: "get_request", group: "requests", scopes: ["requests:read"] },
+    { name: "create_request", group: "requests", scopes: ["requests:write"] },
+    // Existing collection → POST /requests (requests:write); new collection → the
+    // atomic POST /import/json (import:write). Either makes the tool usable.
+    { name: "create_requests_bulk", group: "requests", scopes: ["requests:write", "import:write"], anyOf: true },
+    { name: "update_request", group: "requests", scopes: ["requests:write"] },
+    { name: "move_requests", group: "requests", scopes: ["requests:write"] },
+    { name: "delete_requests", group: "requests", scopes: ["requests:delete"], destructive: true },
+    { name: "run_request", group: "run", scopes: ["requests:run"], localRun: true },
+    { name: "run_collection", group: "run", scopes: ["requests:run"], localRun: true },
+    // Documents and new collections → import:write; cURL/.http into an existing
+    // collection → requests:write.
+    { name: "import_content", group: "import", scopes: ["import:write", "requests:write"], anyOf: true },
+    { name: "import_scenario", group: "import", scopes: ["import:write"] },
+    { name: "list_environments", group: "environments", scopes: ["environments:read"] },
+    { name: "get_environment", group: "environments", scopes: ["environments:read"] },
+    { name: "create_environment", group: "environments", scopes: ["environments:write"] },
+    { name: "set_environment_variables", group: "environments", scopes: ["environments:write"] },
+    { name: "delete_environment", group: "environments", scopes: ["environments:delete"], destructive: true },
+    { name: "list_scenarios", group: "scenarios", scopes: ["scenarios:read"] },
+    { name: "get_scenario", group: "scenarios", scopes: ["scenarios:read"] },
+    { name: "get_scenario_report", group: "scenarios", scopes: ["scenarios:read"] },
+    { name: "create_scenario", group: "scenarios", scopes: ["scenarios:write"] },
+    { name: "update_scenario", group: "scenarios", scopes: ["scenarios:write"] },
+    { name: "delete_scenario", group: "scenarios", scopes: ["scenarios:delete"], destructive: true },
+    { name: "run_scenario", group: "scenarios", scopes: ["scenarios:run"] },
+    { name: "list_diagrams", group: "diagrams", scopes: ["diagrams:read"] },
+    { name: "get_diagram", group: "diagrams", scopes: ["diagrams:read"] },
+    { name: "create_diagram", group: "diagrams", scopes: ["diagrams:write"] },
+    { name: "update_diagram", group: "diagrams", scopes: ["diagrams:write"] },
+    { name: "patch_diagram", group: "diagrams", scopes: ["diagrams:write"] },
+    { name: "delete_diagram", group: "diagrams", scopes: ["diagrams:delete"], destructive: true },
+    { name: "share_diagram", group: "diagrams", scopes: ["diagrams:share"] },
+];
+const toolAvailability = (tokenScopes, allowLocalRun) => {
+    const held = new Set(tokenScopes);
+    return exports.TOOL_CATALOG.map((entry) => {
+        if (entry.localRun && !allowLocalRun) {
+            return { name: entry.name, available: false, missingScopes: [], reason: "local runs are disabled (CALLMAN_ALLOW_RUN=0)" };
+        }
+        const missing = entry.scopes.filter((scope) => !held.has(scope));
+        const available = entry.anyOf ? missing.length < entry.scopes.length : missing.length === 0;
+        return { name: entry.name, available, missingScopes: available ? [] : missing };
+    });
+};
+exports.toolAvailability = toolAvailability;

package/dist-cjs/tools/collections.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCollectionTools = void 0;
+const zod_1 = require("zod");
+const errors_js_1 = require("../client/errors.js");
+const requestShape_js_1 = require("../domain/requestShape.js");
+const resolve_js_1 = require("../domain/resolve.js");
+const pagination_js_1 = require("../lib/pagination.js");
+const truncate_js_1 = require("../lib/truncate.js");
+const lookups_js_1 = require("./lookups.js");
+const shared_js_1 = require("./shared.js");
+const EXPORT_MAX_BYTES = 1024 * 1024;
+const registerCollectionTools = (server, ctx) => {
+    server.registerTool("list_collections", {
+        title: "List collections",
+        description: "List the collections in a workspace with request/folder counts. Optional `query` filters by name (substring). Use get_collection_tree to see what is inside one.",
+        inputSchema: { workspace: shared_js_1.workspaceArg, query: zod_1.z.string().max(200).optional(), ...shared_js_1.cursorArgs },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ workspace, query, cursor, limit }) => {
+        const ws = await ctx.resolveWorkspace(workspace);
+        const all = await (0, lookups_js_1.loadCollections)(ctx, ws.id);
+        const needle = query?.trim().toLowerCase();
+        const filtered = needle ? all.filter((collection) => collection.name.toLowerCase().includes(needle)) : all;
+        const page = (0, pagination_js_1.sliceWithCursor)(filtered, cursor, limit);
+        return (0, shared_js_1.ok)({
+            workspace: { id: ws.id, name: ws.name },
+            collections: page.items.map((collection) => ({
+                id: collection.id,
+                name: collection.name,
+                requestCount: collection.requestCount ?? null,
+                folderCount: collection.folderCount ?? null,
+                updatedAt: collection.updatedAt ?? null,
+            })),
+            total: page.total,
+            nextCursor: page.nextCursor,
+        });
+    }));
+    server.registerTool("get_collection_tree", {
+        title: "Get a collection's folders and requests",
+        description: "The folders (with paths like \"Auth/Login\") and requests (id, name, method, url, folder) of one collection — the map you need before creating, moving or running requests.",
+        inputSchema: { workspace: shared_js_1.workspaceArg, collection: (0, shared_js_1.refArg)("Collection") },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ workspace, collection }) => {
+        const ws = await ctx.resolveWorkspace(workspace);
+        const resolved = await (0, lookups_js_1.resolveCollection)(ctx, ws.id, collection);
+        const tree = await (0, lookups_js_1.loadTree)(ctx, ws.id, resolved.item.id);
+        const truncated = tree.requests.length > truncate_js_1.LIMITS.TREE_ITEMS;
+        return (0, shared_js_1.ok)({
+            collection: { id: resolved.item.id, name: resolved.item.name },
+            resolved: [(0, resolve_js_1.resolvedSummary)(collection, resolved)],
+            folders: tree.folders.map((folder) => ({ id: folder.id, name: folder.name, parentId: folder.parentId, path: folder.path })),
+            requests: tree.requests.slice(0, truncate_js_1.LIMITS.TREE_ITEMS).map(requestShape_js_1.requestSummaryView),
+            ...(truncated ? { truncated: true, totalRequests: tree.requests.length } : {}),
+        });
+    }));
+    server.registerTool("export_collection", {
+        title: "Export a collection",
+        description: "Export a collection as a document: `internal` (Callman's own format, re-importable, includes scripts/contracts) or `postman` (Postman v2.1). Auth secrets in the export are NOT masked — treat the result as sensitive.",
+        inputSchema: { workspace: shared_js_1.workspaceArg, collection: (0, shared_js_1.refArg)("Collection"), format: zod_1.z.enum(["internal", "postman"]).default("internal") },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ workspace, collection, format }) => {
+        const ws = await ctx.resolveWorkspace(workspace);
+        const resolved = await (0, lookups_js_1.resolveCollection)(ctx, ws.id, collection);
+        const document = await ctx.api.exportCollection(ws.id, resolved.item.id, format);
+        const bytes = (0, truncate_js_1.byteLength)(document);
+        if (bytes > EXPORT_MAX_BYTES) {
+            throw new errors_js_1.ToolInputError("EXPORT_TOO_LARGE", `The export is ${bytes} bytes (limit ${EXPORT_MAX_BYTES}). Export it from the desktop app instead.`, { bytes });
+        }
+        return (0, shared_js_1.ok)({ collection: { id: resolved.item.id, name: resolved.item.name }, format, bytes, document: document });
+    }));
+    server.registerTool("create_collection", {
+        title: "Create a collection",
+        description: "Create an empty collection. Refuses a name that already exists in the workspace unless allowDuplicateName is true — list_collections first and reuse an existing one when it fits.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            name: zod_1.z.string().min(1).max(truncate_js_1.LIMITS.NAME),
+            allowDuplicateName: zod_1.z.boolean().optional(),
+            runnerSettings: zod_1.z.object({ database: zod_1.z.boolean().optional(), kafka: zod_1.z.boolean().optional(), redis: zod_1.z.boolean().optional() }).optional(),
+        },
+        annotations: shared_js_1.WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, name, allowDuplicateName, runnerSettings }) => {
+        const ws = await ctx.resolveWorkspace(workspace);
+        const existing = (await (0, lookups_js_1.loadCollections)(ctx, ws.id)).find((collection) => (0, lookups_js_1.sameName)(collection.name, name));
+        if (existing && !allowDuplicateName) {
+            throw new errors_js_1.ToolInputError("COLLECTION_NAME_EXISTS", `A collection named "${existing.name}" already exists (id ${existing.id}). Reuse it, pick another name, or pass allowDuplicateName: true.`, {
+                existing: { id: existing.id, name: existing.name },
+            });
+        }
+        const created = await ctx.api.createCollection(ws.id, { name: name.trim(), ...(runnerSettings ? { runnerSettings: compactSettings(runnerSettings) } : {}) });
+        ctx.invalidate(`collections:${ws.id}`);
+        return (0, shared_js_1.ok)({ collection: { id: created.id, name: created.name }, note: "Created. Add requests with create_request / create_requests_bulk / import_content." });
+    }));
+    server.registerTool("update_collection", {
+        title: "Rename a collection / change runner settings",
+        description: "Rename a collection or toggle its runner settings (database / kafka / redis steps during runs).",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            collection: (0, shared_js_1.refArg)("Collection"),
+            name: zod_1.z.string().min(1).max(truncate_js_1.LIMITS.NAME).optional(),
+            runnerSettings: zod_1.z.object({ database: zod_1.z.boolean().optional(), kafka: zod_1.z.boolean().optional(), redis: zod_1.z.boolean().optional() }).optional(),
+        },
+        annotations: shared_js_1.IDEMPOTENT_WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, collection, name, runnerSettings }) => {
+        if (name === undefined && runnerSettings === undefined)
+            throw new errors_js_1.ToolInputError("NOTHING_TO_UPDATE", "Pass name and/or runnerSettings.");
+        const ws = await ctx.resolveWorkspace(workspace);
+        const resolved = await (0, lookups_js_1.resolveCollection)(ctx, ws.id, collection);
+        const updated = await ctx.api.updateCollection(ws.id, resolved.item.id, {
+            ...(name !== undefined ? { name: name.trim() } : {}),
+            ...(runnerSettings ? { runnerSettings: compactSettings(runnerSettings) } : {}),
+        });
+        ctx.invalidate(`collections:${ws.id}`);
+        return (0, shared_js_1.ok)({ collection: { id: updated.id, name: updated.name, runnerSettings: updated.runnerSettings ?? null }, resolved: [(0, resolve_js_1.resolvedSummary)(collection, resolved)] });
+    }));
+    server.registerTool("create_folder", {
+        title: "Create a folder",
+        description: "Create a folder in a collection, optionally inside a parent folder (id, name or path).",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            collection: (0, shared_js_1.refArg)("Collection"),
+            name: zod_1.z.string().min(1).max(truncate_js_1.LIMITS.NAME),
+            parent: zod_1.z.string().max(300).optional().describe("Parent folder id, name or path; omit for top level"),
+        },
+        annotations: shared_js_1.WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, collection, name, parent }) => {
+        const ws = await ctx.resolveWorkspace(workspace);
+        const resolved = await (0, lookups_js_1.resolveCollection)(ctx, ws.id, collection);
+        const parentFolder = await (0, lookups_js_1.resolveFolder)(ctx, ws.id, resolved.item.id, parent);
+        const tree = await (0, lookups_js_1.loadTree)(ctx, ws.id, resolved.item.id);
+        const sibling = tree.folders.find((folder) => folder.parentId === (parentFolder?.item.id ?? null) && (0, lookups_js_1.sameName)(folder.name, name));
+        if (sibling) {
+            return (0, shared_js_1.ok)({ folder: { id: sibling.id, name: sibling.name, path: sibling.path }, existed: true, note: "A folder with that name already exists there — returned instead of creating a duplicate." });
+        }
+        const folder = await ctx.api.createFolder(ws.id, { name: name.trim(), collectionId: resolved.item.id, parentId: parentFolder?.item.id ?? null });
+        ctx.invalidate(`tree:${ws.id}:${resolved.item.id}`);
+        ctx.invalidate(`collections:${ws.id}`);
+        return (0, shared_js_1.ok)({
+            folder: { id: folder.id, name: folder.name, parentId: folder.parentId, path: parentFolder ? `${parentFolder.item.path}/${folder.name}` : folder.name },
+            resolved: [(0, resolve_js_1.resolvedSummary)(collection, resolved), ...(parentFolder ? [(0, resolve_js_1.resolvedSummary)(parent, parentFolder)] : [])],
+        });
+    }));
+    server.registerTool("update_folder", {
+        title: "Rename or move a folder",
+        description: "Rename a folder and/or move it under another parent (pass parent: null for top level).",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            collection: (0, shared_js_1.refArg)("Collection"),
+            folder: (0, shared_js_1.refArg)("Folder", "(or path)"),
+            name: zod_1.z.string().min(1).max(truncate_js_1.LIMITS.NAME).optional(),
+            parent: zod_1.z.string().max(300).nullable().optional().describe("New parent folder (id, name or path); null = top level"),
+        },
+        annotations: shared_js_1.IDEMPOTENT_WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, collection, folder, name, parent }) => {
+        if (name === undefined && parent === undefined)
+            throw new errors_js_1.ToolInputError("NOTHING_TO_UPDATE", "Pass name and/or parent.");
+        const ws = await ctx.resolveWorkspace(workspace);
+        const resolved = await (0, lookups_js_1.resolveCollection)(ctx, ws.id, collection);
+        const target = await (0, lookups_js_1.resolveFolder)(ctx, ws.id, resolved.item.id, folder);
+        if (!target)
+            throw new errors_js_1.ToolInputError("REF_REQUIRED", "folder is required.");
+        const parentFolder = parent ? await (0, lookups_js_1.resolveFolder)(ctx, ws.id, resolved.item.id, parent) : null;
+        if (parentFolder && parentFolder.item.id === target.item.id)
+            throw new errors_js_1.ToolInputError("FOLDER_CYCLE", "A folder cannot be its own parent.");
+        const updated = await ctx.api.updateFolder(ws.id, target.item.id, {
+            ...(name !== undefined ? { name: name.trim() } : {}),
+            ...(parent !== undefined ? { parentId: parentFolder?.item.id ?? null } : {}),
+        });
+        ctx.invalidate(`tree:${ws.id}:${resolved.item.id}`);
+        return (0, shared_js_1.ok)({ folder: { id: updated.id, name: updated.name, parentId: updated.parentId }, resolved: [(0, resolve_js_1.resolvedSummary)(collection, resolved), (0, resolve_js_1.resolvedSummary)(folder, target)] });
+    }));
+    server.registerTool("delete_collection", {
+        title: "Delete a collection",
+        description: "Delete a collection with all its folders and requests. Permanent — confirm with the user first.",
+        inputSchema: { workspace: shared_js_1.workspaceArg, collection: (0, shared_js_1.refArg)("Collection"), confirm: shared_js_1.confirmArg },
+        annotations: shared_js_1.DESTRUCTIVE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, collection, confirm }) => {
+        (0, shared_js_1.requireConfirm)(confirm, "a collection");
+        const ws = await ctx.resolveWorkspace(workspace);
+        const resolved = await (0, lookups_js_1.resolveCollection)(ctx, ws.id, collection);
+        await ctx.api.deleteCollection(ws.id, resolved.item.id);
+        ctx.invalidate(`collections:${ws.id}`);
+        ctx.invalidate(`tree:${ws.id}:${resolved.item.id}`);
+        return (0, shared_js_1.ok)({ deleted: { id: resolved.item.id, name: resolved.item.name }, resolved: [(0, resolve_js_1.resolvedSummary)(collection, resolved)] });
+    }));
+    server.registerTool("delete_folder", {
+        title: "Delete a folder",
+        description: "Delete a folder and everything inside it (subfolders and requests). Permanent — confirm with the user first.",
+        inputSchema: { workspace: shared_js_1.workspaceArg, collection: (0, shared_js_1.refArg)("Collection"), folder: (0, shared_js_1.refArg)("Folder", "(or path)"), confirm: shared_js_1.confirmArg },
+        annotations: shared_js_1.DESTRUCTIVE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, collection, folder, confirm }) => {
+        (0, shared_js_1.requireConfirm)(confirm, "a folder");
+        const ws = await ctx.resolveWorkspace(workspace);
+        const resolved = await (0, lookups_js_1.resolveCollection)(ctx, ws.id, collection);
+        const target = await (0, lookups_js_1.resolveFolder)(ctx, ws.id, resolved.item.id, folder);
+        if (!target)
+            throw new errors_js_1.ToolInputError("REF_REQUIRED", "folder is required.");
+        await ctx.api.deleteFolder(ws.id, target.item.id);
+        ctx.invalidate(`tree:${ws.id}:${resolved.item.id}`);
+        ctx.invalidate(`collections:${ws.id}`);
+        return (0, shared_js_1.ok)({ deleted: { id: target.item.id, name: target.item.name, path: target.item.path }, resolved: [(0, resolve_js_1.resolvedSummary)(collection, resolved), (0, resolve_js_1.resolvedSummary)(folder, target)] });
+    }));
+};
+exports.registerCollectionTools = registerCollectionTools;
+const compactSettings = (settings) => Object.fromEntries(Object.entries(settings).filter(([, value]) => typeof value === "boolean"));

package/dist-cjs/tools/diagrams.js

@@ -0,0 +1,229 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDiagramTools = void 0;
+const callman_core_1 = require("callman-core");
+const zod_1 = require("zod");
+const errors_js_1 = require("../client/errors.js");
+const build_js_1 = require("../domain/diagram/build.js");
+const layout_js_1 = require("../domain/diagram/layout.js");
+const patch_js_1 = require("../domain/diagram/patch.js");
+const summarize_js_1 = require("../domain/diagram/summarize.js");
+const resolve_js_1 = require("../domain/resolve.js");
+const ids_js_1 = require("../lib/ids.js");
+const pagination_js_1 = require("../lib/pagination.js");
+const lookups_js_1 = require("./lookups.js");
+const shared_js_1 = require("./shared.js");
+const directionArg = zod_1.z.enum(["DOWN", "RIGHT", "UP", "LEFT"]).optional().describe("Layout flow direction (default DOWN)");
+const loadDocument = (diagram) => {
+    const parsed = (0, callman_core_1.safeParseDiagramDocument)(diagram.document);
+    if (!parsed.ok) {
+        throw new errors_js_1.ToolInputError("DIAGRAM_DOCUMENT_INVALID", `The stored diagram "${diagram.name}" is not a valid document: ${parsed.errors.join("; ")}`, { errors: parsed.errors });
+    }
+    return parsed.document;
+};
+const registerDiagramTools = (server, ctx) => {
+    server.registerTool("list_diagrams", {
+        title: "List diagrams",
+        description: "List your system-design diagrams and the ones shared with you (owner, node/edge counts, whether you can edit). Diagrams belong to users and are shared into workspaces — not workspace-scoped.",
+        inputSchema: { query: zod_1.z.string().max(200).optional(), ...shared_js_1.cursorArgs },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ query, cursor, limit }) => {
+        const all = await (0, lookups_js_1.loadDiagrams)(ctx);
+        const needle = query?.trim().toLowerCase();
+        const filtered = needle ? all.filter((diagram) => diagram.name.toLowerCase().includes(needle)) : all;
+        const page = (0, pagination_js_1.sliceWithCursor)(filtered, cursor, limit);
+        return (0, shared_js_1.ok)({ diagrams: page.items.map(summarize_js_1.diagramListView), total: page.total, nextCursor: page.nextCursor });
+    }));
+    server.registerTool("get_diagram", {
+        title: "Get a diagram",
+        description: "Read a diagram: `graph` (nodes with type/label/parent and edges with their meaning — enough to describe or edit it) or `full` (the complete DiagramDocument, up to 512 KB).",
+        inputSchema: { diagram: (0, shared_js_1.refArg)("Diagram"), view: zod_1.z.enum(["summary", "graph", "full"]).default("graph") },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ diagram, view }) => {
+        const resolved = await (0, lookups_js_1.resolveDiagram)(ctx, diagram);
+        const doc = loadDocument(resolved.item);
+        const summary = (0, summarize_js_1.diagramListView)(resolved.item);
+        const body = view === "summary" ? summary : view === "graph" ? { ...summary, ...(0, summarize_js_1.diagramGraphView)(doc) } : { ...summary, ...(0, summarize_js_1.diagramFullView)(doc) };
+        return (0, shared_js_1.ok)({ diagram: body, ...(resolved.annotation ? { resolved: [(0, resolve_js_1.resolvedSummary)(diagram, resolved)] } : {}) });
+    }));
+    server.registerTool("create_diagram", {
+        title: "Create a system-design diagram",
+        description: "Create a diagram from typed nodes and edges. Node `type` must come from callman://diagram/components (e.g. net.service, net.gateway, db.postgres, mq.kafka, aws.lambda, flow.process); unknown types are rejected with suggestions unless strictTypes: false. Group nodes with a container (`parent`). Edge `semantic`: sync (default), async, fallback, bus. Layout is automatic when nodes have no positions. Keep it readable: 8–25 nodes, short labels.",
+        inputSchema: {
+            name: zod_1.z.string().min(1).max(200).describe("Diagram name (library entry)"),
+            ...build_js_1.diagramInputSchema.shape,
+            autoLayout: zod_1.z.boolean().optional().describe("Force layout even when positions were given"),
+            direction: directionArg,
+            strictTypes: zod_1.z.boolean().optional(),
+            dryRun: shared_js_1.dryRunArg,
+        },
+        annotations: shared_js_1.WRITE,
+    }, (0, shared_js_1.guarded)(async ({ name, autoLayout, direction, strictTypes, dryRun, ...input }) => {
+        const built = (0, build_js_1.buildDiagramDocument)(input, { strictTypes });
+        let document = built.document;
+        let layoutNote;
+        if (autoLayout || built.unpositionedNodeIds.length > 0) {
+            const laid = await (0, layout_js_1.layoutDocument)(document, { direction });
+            document = laid.document;
+            layoutNote = laid.warning ?? `Laid out with ${laid.engine}.`;
+        }
+        if (dryRun) {
+            return (0, shared_js_1.ok)({ dryRun: true, diagram: { name, ...(0, summarize_js_1.diagramGraphView)(document) }, warnings: built.warnings, ...(layoutNote ? { layout: layoutNote } : {}) });
+        }
+        const created = await ctx.api.createDiagram({ name: name.trim(), document });
+        ctx.invalidate("diagrams");
+        return (0, shared_js_1.ok)({
+            diagram: { ...(0, summarize_js_1.diagramListView)(created), ...(0, summarize_js_1.diagramGraphView)(document) },
+            warnings: built.warnings,
+            ...(layoutNote ? { layout: layoutNote } : {}),
+            note: "Saved. Open it in the desktop app (Diagrams → Refresh). Edit with patch_diagram; share with share_diagram.",
+        });
+    }));
+    server.registerTool("update_diagram", {
+        title: "Replace a diagram's content",
+        description: "Replace a diagram's whole document (nodes + edges) and/or rename it, keeping its identity and sharing. For small edits prefer patch_diagram.",
+        inputSchema: {
+            diagram: (0, shared_js_1.refArg)("Diagram"),
+            name: zod_1.z.string().min(1).max(200).optional(),
+            title: zod_1.z.string().max(200).optional(),
+            nodes: build_js_1.diagramInputSchema.shape.nodes.optional(),
+            edges: build_js_1.diagramInputSchema.shape.edges.optional(),
+            canvas: build_js_1.diagramInputSchema.shape.canvas,
+            autoLayout: zod_1.z.boolean().optional(),
+            direction: directionArg,
+            strictTypes: zod_1.z.boolean().optional(),
+        },
+        annotations: shared_js_1.IDEMPOTENT_WRITE,
+    }, (0, shared_js_1.guarded)(async ({ diagram, name, title, nodes, edges, canvas, autoLayout, direction, strictTypes }) => {
+        if (name === undefined && nodes === undefined)
+            throw new errors_js_1.ToolInputError("NOTHING_TO_UPDATE", "Pass name and/or nodes (+ edges).");
+        const resolved = await (0, lookups_js_1.resolveDiagram)(ctx, diagram);
+        if (!resolved.item.canEdit)
+            throw new errors_js_1.ToolInputError("DIAGRAM_READ_ONLY", "You have read-only access to this diagram.");
+        const existing = loadDocument(resolved.item);
+        let document;
+        let layoutNote;
+        let warnings = [];
+        if (nodes) {
+            const built = (0, build_js_1.buildDiagramDocument)({ title: title ?? existing.meta.title, nodes, edges: edges ?? [], canvas: canvas ?? existing.canvas }, { strictTypes, existingId: existing.id, createdAt: existing.meta.createdAt });
+            document = built.document;
+            warnings = built.warnings;
+            if (autoLayout || built.unpositionedNodeIds.length > 0) {
+                const laid = await (0, layout_js_1.layoutDocument)(document, { direction });
+                document = laid.document;
+                layoutNote = laid.warning ?? `Laid out with ${laid.engine}.`;
+            }
+        }
+        else if (title !== undefined) {
+            document = { ...existing, meta: { ...existing.meta, title, updatedAt: new Date().toISOString() } };
+        }
+        const updated = await ctx.api.updateDiagram(resolved.item.id, { ...(name !== undefined ? { name: name.trim() } : {}), ...(document ? { document } : {}) });
+        ctx.invalidate("diagrams");
+        return (0, shared_js_1.ok)({ diagram: { ...(0, summarize_js_1.diagramListView)(updated), ...(0, summarize_js_1.diagramGraphView)(document ?? existing) }, warnings, ...(layoutNote ? { layout: layoutNote } : {}), resolved: [(0, resolve_js_1.resolvedSummary)(diagram, resolved)] });
+    }));
+    server.registerTool("patch_diagram", {
+        title: "Edit a diagram incrementally",
+        description: "Apply operations to a diagram without resending it: addNode, updateNode, removeNode (drops its edges), addEdge, updateEdge, removeEdge, setTitle. `relayout`: none | new (place only new nodes, default) | all (re-run automatic layout).",
+        inputSchema: {
+            diagram: (0, shared_js_1.refArg)("Diagram"),
+            ops: zod_1.z.array(patch_js_1.diagramPatchOpSchema).min(1).max(200),
+            relayout: zod_1.z.enum(["none", "new", "all"]).default("new"),
+            direction: directionArg,
+            strictTypes: zod_1.z.boolean().optional(),
+        },
+        annotations: shared_js_1.IDEMPOTENT_WRITE,
+    }, (0, shared_js_1.guarded)(async ({ diagram, ops, relayout, direction, strictTypes }) => {
+        const resolved = await (0, lookups_js_1.resolveDiagram)(ctx, diagram);
+        if (!resolved.item.canEdit)
+            throw new errors_js_1.ToolInputError("DIAGRAM_READ_ONLY", "You have read-only access to this diagram.");
+        const existing = loadDocument(resolved.item);
+        const patched = (0, patch_js_1.applyDiagramPatch)(existing, ops, { strictTypes });
+        let document = patched.document;
+        let layoutNote;
+        if (relayout === "all") {
+            const laid = await (0, layout_js_1.layoutDocument)(document, { direction });
+            document = laid.document;
+            layoutNote = laid.warning ?? `Laid out with ${laid.engine}.`;
+        }
+        else if (relayout === "new" && patched.addedNodeIds.length > 0) {
+            document = (0, layout_js_1.placeNewNodes)(document, patched.addedNodeIds);
+            layoutNote = `Placed ${patched.addedNodeIds.length} new node(s) below the existing ones.`;
+        }
+        const updated = await ctx.api.updateDiagram(resolved.item.id, { document });
+        ctx.invalidate("diagrams");
+        return (0, shared_js_1.ok)({
+            diagram: { ...(0, summarize_js_1.diagramListView)(updated), ...(0, summarize_js_1.diagramGraphView)(document) },
+            applied: ops.length,
+            added: patched.addedNodeIds,
+            removedNodes: patched.removedNodeIds,
+            removedEdges: patched.removedEdgeIds,
+            warnings: patched.warnings,
+            ...(layoutNote ? { layout: layoutNote } : {}),
+            resolved: [(0, resolve_js_1.resolvedSummary)(diagram, resolved)],
+        });
+    }));
+    server.registerTool("delete_diagram", {
+        title: "Delete a diagram",
+        description: "Delete a diagram you own. Permanent — confirm with the user first.",
+        inputSchema: { diagram: (0, shared_js_1.refArg)("Diagram"), confirm: shared_js_1.confirmArg },
+        annotations: shared_js_1.DESTRUCTIVE,
+    }, (0, shared_js_1.guarded)(async ({ diagram, confirm }) => {
+        (0, shared_js_1.requireConfirm)(confirm, "a diagram");
+        const resolved = await (0, lookups_js_1.resolveDiagram)(ctx, diagram);
+        await ctx.api.deleteDiagram(resolved.item.id);
+        ctx.invalidate("diagrams");
+        return (0, shared_js_1.ok)({ deleted: { id: resolved.item.id, name: resolved.item.name }, resolved: [(0, resolve_js_1.resolvedSummary)(diagram, resolved)] });
+    }));
+    server.registerTool("share_diagram", {
+        title: "Share a diagram",
+        description: "Share a diagram into workspaces (every member can view it) and grant edit access to specific people (by email — they must be members of one of your workspaces). Additive by default; replace: true sets exactly the given lists (an empty list unshares).",
+        inputSchema: {
+            diagram: (0, shared_js_1.refArg)("Diagram"),
+            workspaces: zod_1.z.array(zod_1.z.string().min(1).max(200)).max(200).optional().describe("Workspace names or ids to share into"),
+            editors: zod_1.z.array(zod_1.z.string().min(1).max(255)).max(500).optional().describe("Emails (or user ids) who may edit"),
+            replace: zod_1.z.boolean().optional(),
+        },
+        annotations: shared_js_1.IDEMPOTENT_WRITE,
+    }, (0, shared_js_1.guarded)(async ({ diagram, workspaces, editors, replace }) => {
+        if (!workspaces && !editors)
+            throw new errors_js_1.ToolInputError("NOTHING_TO_UPDATE", "Pass workspaces and/or editors.");
+        const resolved = await (0, lookups_js_1.resolveDiagram)(ctx, diagram);
+        const workspaceIds = new Set(replace ? [] : resolved.item.sharedWorkspaceIds ?? []);
+        const editorIds = new Set(replace ? [] : resolved.item.editorIds ?? []);
+        const resolvedNotes = [];
+        for (const ref of workspaces ?? []) {
+            const ws = await ctx.resolveWorkspace(ref);
+            workspaceIds.add(ws.id);
+            resolvedNotes.push({ input: ref, matched: ws.name, id: ws.id });
+        }
+        if (editors && editors.length > 0) {
+            // Look up emails across the user's workspaces (members are the only
+            // people a diagram can be shared with anyway).
+            const memberByEmail = new Map();
+            const memberIds = new Set();
+            for (const ws of await ctx.listWorkspaces()) {
+                try {
+                    const { items } = await ctx.api.listMembers(ws.id);
+                    for (const member of items) {
+                        memberByEmail.set((0, ids_js_1.normalizeName)(member.email), member.userId);
+                        memberIds.add(member.userId);
+                    }
+                }
+                catch {
+                    // no access to the member list of that workspace — skip it
+                }
+            }
+            for (const ref of editors) {
+                const userId = memberByEmail.get((0, ids_js_1.normalizeName)(ref)) ?? (memberIds.has(ref) ? ref : null);
+                if (!userId)
+                    throw new errors_js_1.ToolInputError("EDITOR_NOT_FOUND", `No member with email or id "${ref}" in your workspaces.`);
+                editorIds.add(userId);
+                resolvedNotes.push({ input: ref, matched: ref, id: userId });
+            }
+        }
+        const updated = await ctx.api.shareDiagram(resolved.item.id, { workspaceIds: [...workspaceIds], editorIds: [...editorIds] });
+        ctx.invalidate("diagrams");
+        return (0, shared_js_1.ok)({ diagram: (0, summarize_js_1.diagramListView)(updated), sharedWorkspaceIds: updated.sharedWorkspaceIds, editorIds: updated.editorIds, resolved: [(0, resolve_js_1.resolvedSummary)(diagram, resolved), ...resolvedNotes] });
+    }));
+};
+exports.registerDiagramTools = registerDiagramTools;