callman-mcp 0.1.0 → 0.2.0

package/dist-cjs/tools/contracts.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerContractTools = void 0;
+const zod_1 = require("zod");
+const errors_js_1 = require("../client/errors.js");
+const contracts_js_1 = require("../domain/contracts.js");
+const requestShape_js_1 = require("../domain/requestShape.js");
+const lookups_js_1 = require("./lookups.js");
+const shared_js_1 = require("./shared.js");
+// Contract checks on a saved request (the desktop's Contracts tab): field
+// rules and the data-driven contract. Every runner evaluates them after the
+// response — run_request / run_collection report them under `contracts`.
+// Read callman://docs/contracts for the rule vocabulary and path grammar.
+const requestArgs = {
+    workspace: shared_js_1.workspaceArg,
+    request: (0, shared_js_1.refArg)("Request", "(name, \"METHOD url\" or id)"),
+    collection: zod_1.z.string().max(200).optional().describe("Narrow a request name lookup to one collection"),
+};
+const ruleView = (rule) => ({ id: rule.id, path: rule.path, enabled: rule.enabled, rules: rule.rules });
+const registerContractTools = (server, ctx) => {
+    server.registerTool("get_contract_checks", {
+        title: "Get a request's contract checks",
+        description: "Read a saved request's contract checks: field rules ({ id, path, rules, enabled }) and its data-driven contract (columns + rows, each row with expectedStatus and assertions). These run after every response of the request (desktop, CLI, run_request, run_collection).",
+        inputSchema: requestArgs,
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ workspace, request, collection }) => {
+        const { ws, value, note } = await (0, lookups_js_1.findRequest)(ctx, workspace, request, collection);
+        const { request: found, annotation } = value;
+        const [rules, dataContract] = await Promise.all([ctx.api.listContractRules(ws.id, found.id), ctx.api.getDataContract(ws.id, found.id)]);
+        return (0, shared_js_1.ok)({
+            request: (0, requestShape_js_1.requestSummaryView)(found),
+            workspace: (0, lookups_js_1.workspaceTag)(ws),
+            rules: rules.items.map(ruleView),
+            dataContract: dataContract.rows.length > 0 || dataContract.columns.length > 0 ? { columns: dataContract.columns, rows: dataContract.rows } : null,
+            ...(annotation || note ? { resolved: [{ input: request, matched: found.name, id: found.id, note: [annotation, note].filter(Boolean).join("; ") }] } : {}),
+        });
+    }));
+    server.registerTool("add_contract_rules", {
+        title: "Add contract rules to a request",
+        description: "Add field rules to a saved request's contract (one call, up to 200): each is { path, rules, enabled? } — e.g. { path: \"users[].id\", rules: { required: true, type: \"string\", format: \"uuid\" } } or { path: \"response.status\", rules: { equals: 200 } }. replace: true removes the request's existing rules first (needs requests:delete). Try them against a sample response with test_contract_rules. Rule vocabulary: callman://docs/contracts.",
+        inputSchema: {
+            ...requestArgs,
+            rules: zod_1.z.array(contracts_js_1.contractRuleInputSchema).min(1).max(200),
+            replace: zod_1.z.boolean().optional().describe("Delete the request's existing rules first"),
+            dryRun: shared_js_1.dryRunArg,
+        },
+        annotations: shared_js_1.WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, request, collection, rules, replace, dryRun }) => {
+        const { ws, value } = await (0, lookups_js_1.findRequest)(ctx, workspace, request, collection);
+        const { request: found } = value;
+        const existing = (await ctx.api.listContractRules(ws.id, found.id)).items;
+        const duplicates = replace ? [] : rules.filter((rule) => existing.some((entry) => entry.path === rule.path)).map((rule) => rule.path);
+        const warnings = duplicates.length > 0 ? [`These paths already had rules and now have another one each: ${duplicates.join(", ")} — use update_contract_rule to change an existing rule instead.`] : [];
+        if (dryRun) {
+            return (0, shared_js_1.ok)({ dryRun: true, request: (0, requestShape_js_1.requestSummaryView)(found),
+                workspace: (0, lookups_js_1.workspaceTag)(ws), adding: rules.length, ...(replace ? { removing: existing.length } : {}), warnings });
+        }
+        if (replace) {
+            for (const rule of existing)
+                await ctx.api.deleteContractRule(ws.id, rule.id);
+        }
+        const created = await ctx.api.createContractRules(ws.id, { requestId: found.id, rules: rules.map((rule) => ({ ...rule, enabled: rule.enabled ?? true })) });
+        return (0, shared_js_1.ok)({
+            request: (0, requestShape_js_1.requestSummaryView)(found),
+            workspace: (0, lookups_js_1.workspaceTag)(ws),
+            added: created.items.map(ruleView),
+            ...(replace ? { removed: existing.length } : {}),
+            ...(warnings.length > 0 ? { warnings } : {}),
+        });
+    }));
+    server.registerTool("update_contract_rule", {
+        title: "Change one contract rule",
+        description: "Change one contract rule by id (from get_contract_checks): its path, its rules (the whole rules object is replaced — send every check you want to keep) and/or enabled.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            rule: zod_1.z.string().min(1).max(64).describe("Rule id from get_contract_checks"),
+            path: contracts_js_1.contractPathSchema.optional(),
+            rules: contracts_js_1.contractRulesSchema.optional(),
+            enabled: zod_1.z.boolean().optional(),
+        },
+        annotations: shared_js_1.IDEMPOTENT_WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, rule, path, rules, enabled }) => {
+        if (path === undefined && rules === undefined && enabled === undefined)
+            throw new errors_js_1.ToolInputError("NOTHING_TO_UPDATE", "Pass path, rules and/or enabled.");
+        const body = { ...(path !== undefined ? { path } : {}), ...(rules !== undefined ? { rules } : {}), ...(enabled !== undefined ? { enabled } : {}) };
+        // A rule id lives in exactly one workspace; the others answer 404.
+        const { ws, value: updated } = await (0, lookups_js_1.findInWorkspaces)(ctx, workspace, "contract rule", rule, (candidate) => ctx.api.updateContractRule(candidate.id, rule, body), { matchOf: () => "id" });
+        return (0, shared_js_1.ok)({ rule: ruleView(updated), workspace: (0, lookups_js_1.workspaceTag)(ws) });
+    }));
+    server.registerTool("delete_contract_rules", {
+        title: "Delete contract rules",
+        description: "Delete contract rules of a request — the listed rule ids, or all of them when `rules` is omitted. Permanent — confirm with the user first.",
+        inputSchema: {
+            ...requestArgs,
+            rules: zod_1.z.array(zod_1.z.string().min(1).max(64)).max(200).optional().describe("Rule ids; omit to delete every rule of the request"),
+            confirm: shared_js_1.confirmArg,
+        },
+        annotations: shared_js_1.DESTRUCTIVE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, request, collection, rules, confirm }) => {
+        (0, shared_js_1.requireConfirm)(confirm, "contract rules");
+        const { ws, value } = await (0, lookups_js_1.findRequest)(ctx, workspace, request, collection, { exact: true });
+        const { request: found } = value;
+        const existing = (await ctx.api.listContractRules(ws.id, found.id)).items;
+        const ids = rules ?? existing.map((rule) => rule.id);
+        const unknown = ids.filter((id) => !existing.some((rule) => rule.id === id));
+        if (unknown.length > 0) {
+            throw new errors_js_1.ToolInputError("CONTRACT_RULE_NOT_FOUND", `Not rules of "${found.name}": ${unknown.join(", ")}.`, { rules: existing.map(ruleView) });
+        }
+        const deleted = [];
+        const failed = [];
+        for (const id of ids) {
+            try {
+                await ctx.api.deleteContractRule(ws.id, id);
+                deleted.push(id);
+            }
+            catch (error) {
+                failed.push({ rule: id, error: (0, shared_js_1.failureOf)(error) });
+            }
+        }
+        return (0, shared_js_1.ok)({ request: (0, requestShape_js_1.requestSummaryView)(found),
+            workspace: (0, lookups_js_1.workspaceTag)(ws), deleted, failed });
+    }));
+    server.registerTool("test_contract_rules", {
+        title: "Test contract rules against a response body",
+        description: "Evaluate a request's ENABLED contract rules against a response body you provide (e.g. a sample from the API docs or a previous run) — on the server, nothing is sent to the API and nothing is saved. Returns pass/fail per rule. `response.*` rules (status, headers) need a real run: use run_request.",
+        inputSchema: {
+            ...requestArgs,
+            responseBody: zod_1.z.unknown().describe("The response body (JSON value) to check"),
+        },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ workspace, request, collection, responseBody }) => {
+        const { ws, value } = await (0, lookups_js_1.findRequest)(ctx, workspace, request, collection);
+        const { request: found } = value;
+        const result = await ctx.api.validateContractRules(ws.id, { requestId: found.id, responseBody: responseBody ?? null });
+        return (0, shared_js_1.ok)({ request: (0, requestShape_js_1.requestSummaryView)(found),
+            workspace: (0, lookups_js_1.workspaceTag)(ws), summary: result.summary, results: result.results });
+    }));
+    server.registerTool("set_data_contract", {
+        title: "Set a request's data-driven contract",
+        description: `Replace a request's data-driven contract: the request runs once per row with the row's values as {{data.<column>}}, and each row checks its own expectedStatus and assertions (same rule vocabulary as contract rules). Limits: ${contracts_js_1.DATA_CONTRACT_LIMITS.columns} columns, ${contracts_js_1.DATA_CONTRACT_LIMITS.rows} rows, ${contracts_js_1.DATA_CONTRACT_LIMITS.assertions} assertions per row. Put {{data.<column>}} into the request's url/body/headers with update_request so the rows are used.`,
+        inputSchema: {
+            ...requestArgs,
+            columns: zod_1.z.array(zod_1.z.string().trim().min(1).max(200)).max(contracts_js_1.DATA_CONTRACT_LIMITS.columns).describe("Column names — referenced as {{data.<column>}}"),
+            rows: zod_1.z.array(contracts_js_1.dataContractRowSchema).min(1).max(contracts_js_1.DATA_CONTRACT_LIMITS.rows),
+        },
+        annotations: shared_js_1.IDEMPOTENT_WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, request, collection, columns, rows }) => {
+        const undeclared = (0, contracts_js_1.undeclaredDataColumns)(columns, rows);
+        if (undeclared.length > 0) {
+            throw new errors_js_1.ToolInputError("DATA_COLUMN_UNDECLARED", `Rows use column(s) not in columns: ${undeclared.join(", ")}.`);
+        }
+        const { ws, value } = await (0, lookups_js_1.findRequest)(ctx, workspace, request, collection);
+        const { request: found } = value;
+        const saved = await ctx.api.putDataContract(ws.id, { requestId: found.id, columns, rows });
+        const text = JSON.stringify([found.url, found.headers, found.body, found.query]);
+        const unused = columns.filter((column) => !text.includes(`{{data.${column}}}`));
+        return (0, shared_js_1.ok)({
+            request: (0, requestShape_js_1.requestSummaryView)(found),
+            workspace: (0, lookups_js_1.workspaceTag)(ws),
+            dataContract: { columns: saved.columns, rows: saved.rows.length },
+            ...(unused.length > 0 ? { warnings: [`The request does not reference {{data.${unused.join("}}, {{data.")}}} yet — add them to its url, query, headers or body with update_request.`] } : {}),
+        });
+    }));
+    server.registerTool("delete_data_contract", {
+        title: "Delete a request's data-driven contract",
+        description: "Remove a request's data-driven contract (all rows). Permanent — confirm with the user first.",
+        inputSchema: { ...requestArgs, confirm: shared_js_1.confirmArg },
+        annotations: shared_js_1.DESTRUCTIVE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, request, collection, confirm }) => {
+        (0, shared_js_1.requireConfirm)(confirm, "a data contract");
+        const { ws, value } = await (0, lookups_js_1.findRequest)(ctx, workspace, request, collection, { exact: true });
+        const { request: found } = value;
+        await ctx.api.deleteDataContract(ws.id, found.id);
+        return (0, shared_js_1.ok)({ request: (0, requestShape_js_1.requestSummaryView)(found),
+            workspace: (0, lookups_js_1.workspaceTag)(ws), deleted: true });
+    }));
+    server.registerTool("list_connections", {
+        title: "List workspace connections",
+        description: "List database / Redis / Kafka / notification / AI connections (id, name, type, provider, workspace — never credentials) across all your workspaces, or one `workspace`. A connection belongs to one workspace: use one from the same workspace as the request or scenario. Request database/Kafka/Redis steps and scenario db/redis/kafka/notification/ai nodes reference a connection by this id (or name). Connections are created and tested in the desktop app.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            type: zod_1.z.enum(["database", "redis", "kafka", "notification", "ai"]).optional(),
+        },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ workspace, type }) => {
+        const workspaces = await (0, lookups_js_1.workspacesForListing)(ctx, workspace);
+        const perWorkspace = await Promise.all(workspaces.map(async (ws) => (await ctx.api.listConnections(ws.id, type)).map((connection) => ({ ws, connection }))));
+        return (0, shared_js_1.ok)({
+            ...(workspaces.length === 1 ? { workspace: (0, lookups_js_1.workspaceTag)(workspaces[0]) } : { workspaces: workspaces.map(lookups_js_1.workspaceTag) }),
+            connections: perWorkspace.flat().map(({ ws, connection }) => ({
+                id: connection.id,
+                name: connection.name,
+                ...(workspaces.length > 1 ? { workspace: (0, lookups_js_1.workspaceTag)(ws) } : {}),
+                type: connection.type,
+                provider: connection.provider,
+                ...(connection.description ? { description: connection.description } : {}),
+                ...(connection.isActive === false ? { active: false } : {}),
+                ...(connection.managed ? { managed: true } : {}),
+                ...(connection.lastTestStatus ? { lastTest: connection.lastTestStatus } : {}),
+            })),
+        });
+    }));
+};
+exports.registerContractTools = registerContractTools;

package/dist-cjs/tools/diagrams.js

@@ -31,12 +31,12 @@ const registerDiagramTools = (server, ctx) => {
         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);
+        const page = (0, pagination_js_1.sliceWithCursor)(filtered, cursor, limit, needle ?? "");
         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).",
+        description: "Read a diagram: `summary` (counts, owner, sharing), `graph` (default — nodes with type/label/parent/style and edges with semantic/color, in the same shape the write tools accept: enough to describe, restyle or edit it) or `full` (the complete stored DiagramDocument with positions, sizes and routes, 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 }) => {
@@ -48,7 +48,7 @@ const registerDiagramTools = (server, ctx) => {
     }));
     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.",
+        description: "Create a diagram from typed nodes and edges. Node `type` must come from callman://diagram/components (e.g. net.service, net.api-gateway, db.postgres, mq.kafka, aws.lambda, flow.process); unknown types are rejected with suggestions unless strictTypes: false. Group nodes inside a container node — frame, pool.horizontal or pool.vertical — with `parent`. Style nodes with `style` (fill / stroke / textColor as CSS colors, strokeWidth, dashed, radius, bold, fontSize, opacity…) and edges with `semantic` (sync default, async, fallback, bus) plus an optional `color`. Layout is automatic when nodes have no positions. Read callman://docs/diagram-schema for every field. 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,
@@ -81,7 +81,7 @@ const registerDiagramTools = (server, ctx) => {
     }));
     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.",
+        description: "Replace a diagram's whole document (nodes + edges, same fields as create_diagram) and/or rename it, retitle it or change its canvas, keeping its identity and sharing. Passing nodes replaces ALL nodes and edges (omitted edges are removed). For small edits — including restyling — prefer patch_diagram.",
         inputSchema: {
             diagram: (0, shared_js_1.refArg)("Diagram"),
             name: zod_1.z.string().min(1).max(200).optional(),
@@ -95,8 +95,9 @@ const registerDiagramTools = (server, ctx) => {
         },
         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).");
+        if (name === undefined && nodes === undefined && title === undefined && canvas === undefined) {
+            throw new errors_js_1.ToolInputError("NOTHING_TO_UPDATE", "Pass name, title, canvas 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.");
@@ -108,14 +109,21 @@ const registerDiagramTools = (server, ctx) => {
             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 (edges === undefined && existing.edges.length > 0) {
+                warnings.push(`edges was omitted, so the ${existing.edges.length} existing edge(s) were removed. Pass edges to keep connections, or use patch_diagram for partial edits.`);
+            }
             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() } };
+        else if (title !== undefined || canvas !== undefined) {
+            document = {
+                ...existing,
+                ...(canvas !== undefined ? { canvas: { ...existing.canvas, ...canvas } } : {}),
+                meta: { ...existing.meta, ...(title !== undefined ? { title } : {}), updatedAt: new Date().toISOString() },
+            };
         }
         const updated = await ctx.api.updateDiagram(resolved.item.id, { ...(name !== undefined ? { name: name.trim() } : {}), ...(document ? { document } : {}) });
         ctx.invalidate("diagrams");
@@ -123,7 +131,7 @@ const registerDiagramTools = (server, ctx) => {
     }));
     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).",
+        description: "Apply operations to a diagram without resending it: addNode, updateNode, removeNode (drops its edges), addEdge, updateEdge, removeEdge, setTitle. updateNode `changes` MERGE: style and data keys you pass change, a key set to null is removed. updateEdge can change semantic, color, label, arrows and ends. Moving a node (position/size/parent) re-routes its edges. `relayout`: none | new (place only new nodes, default) | all (re-run automatic layout). Call get_diagram (view: graph) first to see node ids and current styles.",
         inputSchema: {
             diagram: (0, shared_js_1.refArg)("Diagram"),
             ops: zod_1.z.array(patch_js_1.diagramPatchOpSchema).min(1).max(200),
@@ -157,6 +165,7 @@ const registerDiagramTools = (server, ctx) => {
             added: patched.addedNodeIds,
             removedNodes: patched.removedNodeIds,
             removedEdges: patched.removedEdgeIds,
+            ...(patched.reroutedEdgeIds.length > 0 ? { reroutedEdges: patched.reroutedEdgeIds } : {}),
             warnings: patched.warnings,
             ...(layoutNote ? { layout: layoutNote } : {}),
             resolved: [(0, resolve_js_1.resolvedSummary)(diagram, resolved)],
@@ -169,7 +178,7 @@ const registerDiagramTools = (server, ctx) => {
         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);
+        const resolved = await (0, lookups_js_1.resolveDiagram)(ctx, diagram, { exact: true });
         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)] });