@intentius/chant 0.124.13 → 0.124.15

package/dist/cli/mcp/resources/context.js

@@ -0,0 +1,85 @@
+/**
+ * Get the chant context for MCP
+ * Returns lexicon-specific instructions and patterns
+ */
+export function getContext() {
+    return `# chant Development Context
+
+chant is a lexicon-agnostic declarative specification system for infrastructure as code.
+
+## Key Concepts
+
+### Declarable
+Base interface for all infrastructure entities. Every resource you create must implement \`Declarable\`.
+
+### Lexicon
+Lexicons define target platforms (e.g. AWS). Each lexicon:
+- Has a unique name and rule prefix
+- Implements \`serialize(entities)\` to generate platform-specific output
+
+### AttrRef
+Deferred references to entity attributes. Use these for cross-resource references:
+\`\`\`typescript
+const bucket = new Bucket({ name: "data" });
+// bucket.arn is an AttrRef that resolves at build time
+\`\`\`
+
+### Intrinsics
+Lexicon-provided functions resolved at build time:
+- \`Sub\` - String interpolation with references
+- \`Ref\` - Reference to another resource
+- \`Json\` - JSON serialization
+
+## CLI Commands
+
+### Build
+\`\`\`bash
+chant build ./infra/          # Build infrastructure
+chant build ./infra/ -o out.json  # Output to file
+\`\`\`
+
+### Lint
+\`\`\`bash
+chant lint ./infra/           # Check for issues
+\`\`\`
+
+### Import
+\`\`\`bash
+chant import template.json    # Convert external template
+chant import template.json -o ./src/  # Custom output dir
+\`\`\`
+
+## Ops
+
+An Op is a convergent verb. Each \`*.op.ts\` file declares one with named phases and activity steps; \`--on <lexicon>\` picks the runtime that hosts the run, and the built-in local runtime runs it in-process otherwise.
+
+### Op MCP Tools
+
+| Tool | Description |
+|---|---|
+| \`op-list\` | List all discovered Ops with their current run state. |
+| \`op-run\` | Run an Op and return its result. Requires \`name\`. |
+| \`op-status\` | Get current run state (state, step records, times). Requires \`name\`. |
+| \`op-approve\` | Record a gate's resolution and wake the runtime hosting the run. Requires \`name\` and \`gate\`. |
+| \`op-report\` | Return a markdown report for the latest run. Requires \`name\`. |
+
+All Op tools accept an optional \`runtime\` parameter: a lexicon name whose \`opRuntime\` hosts the run, or \`local\` (the default) for the built-in in-process runtime.
+
+### Op MCP Resources
+
+| URI | Description |
+|---|---|
+| \`chant://ops\` | JSON array of all Op definitions (name, overview, phase count, labels, depends) |
+| \`chant://ops/{name}/runs\` | Run ledger history for a named Op, newest first |
+| \`chant://ops/{name}/runs/latest\` | Latest run state for a named Op |
+
+Both run resources read the built-in local runtime, the one an MCP client can address without naming a lexicon.
+
+## Best Practices
+
+1. **Flat Declarations**: Keep declarations at module level, avoid deep nesting
+2. **Use AttrRefs**: Reference other resources via AttrRef, not string interpolation
+3. **Lexicon-specific Rules**: Each lexicon has lint rules (WAW001, etc.)
+4. **Type Safety**: Leverage TypeScript for infrastructure definitions
+`;
+}

package/dist/cli/mcp/server.js

@@ -0,0 +1,353 @@
+import { createInterface } from "readline";
+import { resolve } from "node:path";
+import { buildTool, handleBuild } from "./tools/build.js";
+import { lintTool, handleLint } from "./tools/lint.js";
+import { importTool, handleImport } from "./tools/import.js";
+import { explainTool, handleExplain } from "./tools/explain.js";
+import { scaffoldTool, createScaffoldHandler } from "./tools/scaffold.js";
+import { searchTool, createSearchHandler } from "./tools/search.js";
+import { compositesTool, createCompositesHandler } from "./tools/composites.js";
+import { findWorkspaceRoot } from "../../project-root.js";
+import { createWorkspaceTools } from "./workspace-tools.js";
+import { createSnapshotTool, createDiffTool } from "./lifecycle-tools.js";
+import { setGateOrigin } from "../../lifecycle/gate-origin.js";
+import { createOpListTool, createOpRunTool, createOpStatusTool, createOpApproveTool, createOpReportTool } from "./op-tools.js";
+import { buildResourcesList, handleResourcesRead } from "./resource-handlers.js";
+import { CHANT_VERSION } from "../version.js";
+/**
+ * Protocol versions this server understands, newest first. `initialize` and
+ * `server/discover` both negotiate against this list rather than assuming
+ * the client's revision (#1194).
+ *
+ * Exported because `docs-parity.test.ts` reads it: `cli/mcp.mdx` states these
+ * revisions in prose, and stating them twice is how the page came to claim
+ * 2024-11-05 for two releases after this list moved past it (#2385).
+ *
+ * The 2025 revisions are here because Claude Code 2.1.274 asks for
+ * 2025-11-25 and rejects any answer outside 2025-11-25, 2025-06-18,
+ * 2025-03-26, 2024-11-05 and 2024-10-07. A 2025 client sends
+ * `protocolVersion`/`clientInfo` at the top level of `initialize`, which
+ * {@link parseMeta} already falls back to, so it needs no other branch.
+ */
+export const SUPPORTED_PROTOCOL_VERSIONS = ["2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+const LATEST_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0];
+/**
+ * Pick the protocol version to answer with: the client's requested version
+ * when we support it, otherwise our latest. A 2024-11-05 or 2025 client that
+ * asks for its own version gets it back unchanged; a 2026-07-28 client, or one
+ * that never says, gets the latest revision (#1194).
+ */
+export function negotiateProtocolVersion(requested) {
+    if (requested && SUPPORTED_PROTOCOL_VERSIONS.includes(requested)) {
+        return requested;
+    }
+    return LATEST_PROTOCOL_VERSION;
+}
+/**
+ * Parse the `_meta` envelope the 2026-07-28 revision puts on every request
+ * (client identity, requested protocol version), falling back to the
+ * top-level `protocolVersion`/`clientInfo` fields a prior-revision client
+ * sends on `initialize`. Read-side only — the server holds no handshake
+ * state to update (#1194).
+ */
+export function parseMeta(params) {
+    const meta = (params._meta ?? {});
+    const protocolVersion = (typeof meta.protocolVersion === "string" ? meta.protocolVersion : undefined) ??
+        (typeof params.protocolVersion === "string" ? params.protocolVersion : undefined);
+    const clientInfo = meta["io.modelcontextprotocol/clientInfo"] ??
+        params.clientInfo;
+    return { protocolVersion, clientInfo };
+}
+/**
+ * The name a lexicon's MCP tool is registered under: `<lexicon>:<verb>`,
+ * whether or not the lexicon already wrote the prefix itself (#1341).
+ */
+export function namespacedToolName(lexicon, name) {
+    const prefix = `${lexicon}:`;
+    return name.startsWith(prefix) ? name : `${prefix}${name}`;
+}
+/**
+ * The URI a lexicon's MCP resource is registered under: `chant://<lexicon>/<path>`.
+ *
+ * Three authored forms reach here (#1341). The bare path is the intended one.
+ * `createCatalogResource` emits `<lexicon>:resource-catalog`, and
+ * `lexicon-authoring/lsp-mcp.mdx` taught `chant://lexicon/<lexicon>/<path>` —
+ * which azure followed, and which produced the unusable
+ * `chant://azure/chant://lexicon/azure/catalog`.
+ */
+export function namespacedResourceUri(lexicon, uri) {
+    const base = `chant://${lexicon}/`;
+    if (uri.startsWith(base))
+        return uri;
+    for (const authored of [`chant://lexicon/${lexicon}/`, `${lexicon}:`]) {
+        if (uri.startsWith(authored))
+            return `${base}${uri.slice(authored.length)}`;
+    }
+    return `${base}${uri}`;
+}
+/**
+ * MCP Server implementation
+ */
+export class McpServer {
+    /**
+     * `options.instructions` is sent as the `initialize` result's
+     * `instructions`, the text a client may give its model about this server.
+     * Only a workspace root with no lexicon of its own sets it (#2700), to say
+     * which members' lexicons were loaded.
+     *
+     * `options.workspace` names the directory the server serves (#2707). When
+     * it is at or inside a declared workspace, the workspace read-contract and
+     * record-write tools are served too.
+     */
+    constructor(plugins, options = {}) {
+        this.tools = new Map();
+        this.toolHandlers = new Map();
+        this.pluginResources = new Map();
+        this.plugins = plugins ?? [];
+        this.instructions = options.instructions;
+        // Register core tools
+        this.registerTool(buildTool, handleBuild);
+        this.registerTool(lintTool, handleLint);
+        this.registerTool(importTool, handleImport);
+        this.registerTool(explainTool, handleExplain);
+        this.registerTool(scaffoldTool, createScaffoldHandler(plugins ?? []));
+        this.registerTool(searchTool, createSearchHandler(plugins ?? []));
+        this.registerTool(compositesTool, createCompositesHandler(plugins ?? []));
+        // Register state tools
+        const snapshot = createSnapshotTool(plugins ?? []);
+        this.registerTool(snapshot.definition, snapshot.handler);
+        const diff = createDiffTool(plugins ?? []);
+        this.registerTool(diff.definition, diff.handler);
+        // Register Op tools
+        for (const factory of [createOpListTool, createOpRunTool, createOpStatusTool, createOpApproveTool, createOpReportTool]) {
+            const t = factory();
+            this.registerTool(t.definition, t.handler);
+        }
+        // Workspace reads and record writes (#2707), inside a declared workspace only.
+        if (options.workspace && findWorkspaceRoot(options.workspace.cwd)) {
+            for (const t of createWorkspaceTools(options.workspace))
+                this.registerTool(t.definition, t.handler);
+        }
+        // Register plugin contributions
+        if (plugins) {
+            for (const plugin of plugins) {
+                this.registerPluginTools(plugin);
+                this.registerPluginResources(plugin);
+            }
+        }
+    }
+    /**
+     * Register tools contributed by a plugin, namespaced as `lexicon:toolName`.
+     *
+     * Namespacing is idempotent (#1341). Core is not the only place that applies
+     * a prefix: `createDiffTool` in ../../lexicon-plugin-helpers.ts already emits
+     * `${lexiconName}:diff`, and eleven lexicons write the prefix into the name by
+     * hand. Applying it unconditionally produced `gitlab:gitlab:diff` and
+     * `aws:aws:diff` in every `chant serve mcp` session, while every doc named the
+     * single-prefixed form. A tool declared either way now registers under exactly
+     * one namespace.
+     */
+    registerPluginTools(plugin) {
+        const tools = plugin.mcpTools?.() ?? [];
+        for (const tool of tools) {
+            this.registerTool({
+                name: namespacedToolName(plugin.name, tool.name),
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+            }, tool.handler);
+        }
+    }
+    /**
+     * Register resources contributed by a plugin, namespaced as
+     * `chant://lexicon/uri`, idempotently — see {@link registerPluginTools}.
+     */
+    registerPluginResources(plugin) {
+        const resources = plugin.mcpResources?.() ?? [];
+        for (const resource of resources) {
+            const namespacedUri = namespacedResourceUri(plugin.name, resource.uri);
+            this.pluginResources.set(namespacedUri, {
+                definition: {
+                    uri: namespacedUri,
+                    name: resource.name,
+                    description: resource.description,
+                    mimeType: resource.mimeType,
+                },
+                handler: resource.handler,
+            });
+        }
+    }
+    /**
+     * Register a tool with its handler
+     */
+    registerTool(definition, handler) {
+        this.tools.set(definition.name, definition);
+        this.toolHandlers.set(definition.name, handler);
+    }
+    async handleRequest(request) {
+        if (request.id === undefined) {
+            return null;
+        }
+        try {
+            const result = await this.dispatch(request.method, request.params ?? {});
+            return {
+                jsonrpc: "2.0",
+                id: request.id,
+                result,
+            };
+        }
+        catch (error) {
+            return {
+                jsonrpc: "2.0",
+                id: request.id,
+                error: {
+                    code: -32603,
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            };
+        }
+    }
+    /**
+     * The `initialize` result — also the basis of `server/discover` below.
+     */
+    buildInitializeResult(params) {
+        const { protocolVersion } = parseMeta(params);
+        return {
+            protocolVersion: negotiateProtocolVersion(protocolVersion),
+            capabilities: { tools: {}, resources: {} },
+            // The installed chant's version, so a client can tell which chant it talks to (#2689).
+            serverInfo: { name: "chant", version: CHANT_VERSION },
+            ...(this.instructions ? { instructions: this.instructions } : {}),
+        };
+    }
+    /**
+     * Dispatch request to appropriate handler
+     */
+    async dispatch(method, params) {
+        switch (method) {
+            case "initialize":
+                // Kept for a write's source block (#2707): a prior-revision client names itself only here.
+                this.clientInfo = parseMeta(params).clientInfo ?? this.clientInfo;
+                // Answered for prior-revision clients too — negotiated, not hard-coded (#1194).
+                return this.buildInitializeResult(params);
+            case "server/discover":
+                // On-demand capability discovery (#1194): the initialize result
+                // merged with the tools/resources listings, so a 2026-07-28 client
+                // never has to call `initialize` at all.
+                return {
+                    ...this.buildInitializeResult(params),
+                    tools: Array.from(this.tools.values()),
+                    resources: buildResourcesList(this.pluginResources).resources,
+                };
+            case "tools/list":
+                return { tools: Array.from(this.tools.values()) };
+            case "tools/call":
+                return this.handleToolsCall(params);
+            case "resources/list":
+                return buildResourcesList(this.pluginResources);
+            case "resources/read":
+                return handleResourcesRead(params, this.pluginResources, this.plugins);
+            default:
+                throw new Error(`Unknown method: ${method}`);
+        }
+    }
+    /**
+     * Handle tools/call request
+     */
+    async handleToolsCall(params) {
+        const name = params.name;
+        const toolParams = (params.arguments ?? {});
+        const handler = this.toolHandlers.get(name);
+        if (!handler) {
+            return {
+                content: [{ type: "text", text: `Error: Unknown tool: ${name}` }],
+                isError: true,
+            };
+        }
+        try {
+            // The client, from this request's _meta (2026-07-28) or else from initialize.
+            const clientInfo = parseMeta(params).clientInfo ?? this.clientInfo;
+            const result = await handler(toolParams, clientInfo ? { clientInfo } : {});
+            const isStructured = typeof result === "object" && result !== null;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: typeof result === "string" ? result : JSON.stringify(result, null, 2),
+                    },
+                ],
+                // Structured output (2025-06-18+): handlers already return plain
+                // objects that get stringified above, so agents that want the
+                // parsed shape directly get it here too, alongside the text block
+                // kept for backward compatibility (#1194).
+                ...(isStructured ? { structuredContent: result } : {}),
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    /**
+     * Start the MCP server on stdio
+     */
+    async start() {
+        // chant#2384 — declared here rather than in the constructor, because this
+        // is where the PROCESS becomes an MCP server. Constructing the object does
+        // not change what the process is, and a test that builds one should not
+        // silently make every later gate fact in that worker read as model-authored.
+        //
+        // From here on a person's only act was launching this; every call is the
+        // model's. So every gate fact written records the channel it came through,
+        // and a gate reached here cannot also be resolved here.
+        setGateOrigin("mcp");
+        const rl = createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            terminal: false,
+        });
+        rl.on("line", async (line) => {
+            try {
+                const request = JSON.parse(line);
+                const response = await this.handleRequest(request);
+                // Notifications (#1194) get no response at all — not even an empty one.
+                if (response !== null) {
+                    console.log(JSON.stringify(response));
+                }
+            }
+            catch (error) {
+                const errorResponse = {
+                    jsonrpc: "2.0",
+                    id: 0,
+                    error: {
+                        code: -32700,
+                        message: "Parse error",
+                    },
+                };
+                console.log(JSON.stringify(errorResponse));
+            }
+        });
+    }
+}
+/**
+ * Start MCP server, loading plugins from the project
+ */
+export async function startMcpServer() {
+    let plugins = [];
+    try {
+        const { resolveProjectLexicons, loadPlugins } = await import("../plugins.js");
+        const lexiconNames = await resolveProjectLexicons(resolve("."));
+        plugins = await loadPlugins(lexiconNames);
+    }
+    catch {
+        // Start without plugins if resolution fails
+    }
+    const server = new McpServer(plugins, { workspace: { cwd: process.cwd() } });
+    server.start();
+}

package/dist/cli/mcp/tools/build.js

@@ -0,0 +1,111 @@
+import { build } from "../../../build.js";
+import { resolve } from "path";
+// Default lexicon serializer for MCP builds (fallback when no lexicon is detected)
+const defaultLexicon = {
+    name: "default",
+    rulePrefix: "DF",
+    serialize(entities) {
+        const output = {};
+        for (const [name, entity] of entities) {
+            output[name] = entity;
+        }
+        return JSON.stringify(output, null, 2);
+    },
+};
+/**
+ * Build tool definition for MCP
+ */
+export const buildTool = {
+    name: "build",
+    description: "Build chant infrastructure code and generate output for the target lexicon",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: {
+                type: "string",
+                description: "Path to the infrastructure directory or file to build",
+            },
+            output: {
+                type: "string",
+                description: "Output file path (optional, returns in response if not specified)",
+            },
+            format: {
+                type: "string",
+                enum: ["json", "yaml"],
+                description: "Output format (default: json)",
+            },
+        },
+        required: ["path"],
+    },
+};
+/**
+ * Handle build tool invocation
+ */
+export async function handleBuild(params) {
+    const path = params.path;
+    const format = params.format ?? "json";
+    const infraPath = resolve(path);
+    const result = await build(infraPath, [defaultLexicon]);
+    if (result.errors.length > 0) {
+        throw new Error(result.errors.map((e) => e.message).join("; "));
+    }
+    // Combine all lexicon outputs
+    const combined = {};
+    for (const [lexiconName, lexiconOutput] of result.outputs) {
+        const raw = lexiconOutput;
+        combined[lexiconName] = JSON.parse(typeof raw === "string" ? raw : raw.primary);
+    }
+    let output = JSON.stringify(combined, null, 2);
+    if (format === "yaml") {
+        // Basic YAML conversion
+        output = jsonToYaml(JSON.parse(output));
+    }
+    return {
+        success: true,
+        resourceCount: result.entities.size,
+        output,
+        format,
+    };
+}
+/**
+ * Simple JSON to YAML converter
+ */
+function jsonToYaml(obj, indent = 0) {
+    const spaces = "  ".repeat(indent);
+    if (obj === null)
+        return "null";
+    if (obj === undefined)
+        return "~";
+    if (typeof obj === "boolean")
+        return obj ? "true" : "false";
+    if (typeof obj === "number")
+        return String(obj);
+    if (typeof obj === "string") {
+        if (obj.includes("\n") || obj.includes(":") || obj.includes("#")) {
+            return `"${obj.replace(/"/g, '\\"')}"`;
+        }
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        if (obj.length === 0)
+            return "[]";
+        return obj
+            .map((item) => `${spaces}- ${jsonToYaml(item, indent + 1).trimStart()}`)
+            .join("\n");
+    }
+    if (typeof obj === "object") {
+        const entries = Object.entries(obj);
+        if (entries.length === 0)
+            return "{}";
+        return entries
+            .map(([key, value]) => {
+            const yamlValue = jsonToYaml(value, indent + 1);
+            if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+                return `${spaces}${key}:\n${yamlValue}`;
+            }
+            return `${spaces}${key}: ${yamlValue.trimStart()}`;
+        })
+            .join("\n");
+    }
+    return String(obj);
+}

package/dist/cli/mcp/tools/composites.js

@@ -0,0 +1,95 @@
+/**
+ * The `composites` tool (#2662): what composites the loaded lexicons export,
+ * what each one bundles and what it takes. "What composites do you have for
+ * aws?" is `{ lexicon: "aws" }`.
+ *
+ * Everything here reads `LexiconPlugin.composites()`, which is static catalog
+ * data. No composite is loaded or called and no provider is asked anything.
+ */
+export const compositesTool = {
+    name: "composites",
+    description: "List the composites the loaded lexicons export: what each builds, the resource kinds it bundles, and its parameters",
+    inputSchema: {
+        type: "object",
+        properties: {
+            lexicon: {
+                type: "string",
+                description: "Only composites from this lexicon (e.g. 'aws', 'k8s')",
+            },
+            query: {
+                type: "string",
+                description: "Keyword matched against the composite's name, description, bundled resource kinds and parameter names",
+            },
+            limit: {
+                type: "number",
+                description: "Maximum number of composites to return (default: 50)",
+            },
+        },
+    },
+};
+/**
+ * Every composite the plugins contribute, in plugin order. A plugin whose
+ * `composites()` throws contributes nothing rather than failing the listing.
+ */
+export function collectComposites(plugins) {
+    const entries = [];
+    for (const plugin of plugins) {
+        let contributed = [];
+        try {
+            contributed = plugin.composites?.() ?? [];
+        }
+        catch {
+            contributed = [];
+        }
+        for (const entry of contributed)
+            entries.push({ ...entry, lexicon: entry.lexicon || plugin.name });
+    }
+    return entries;
+}
+/**
+ * How well an entry matches a lowercased keyword: 0 for no match, higher for
+ * better. A name match beats a bundled kind, which beats a word in the
+ * description or a parameter name, so `queue` lists `LambdaSqs` ahead of a
+ * composite that merely mentions queues.
+ */
+export function compositeMatchScore(entry, lowerQuery) {
+    const name = entry.name.toLowerCase();
+    if (name.startsWith(lowerQuery))
+        return 4;
+    if (name.includes(lowerQuery))
+        return 3;
+    if (entry.bundles.some((b) => b.toLowerCase().includes(lowerQuery)))
+        return 2;
+    if (entry.description.toLowerCase().includes(lowerQuery))
+        return 1;
+    if (entry.params.some((p) => p.name.toLowerCase().includes(lowerQuery)))
+        return 1;
+    return 0;
+}
+export function createCompositesHandler(plugins) {
+    return async (params) => {
+        const lexicon = typeof params.lexicon === "string" && params.lexicon !== "" ? params.lexicon : undefined;
+        const query = typeof params.query === "string" && params.query !== "" ? params.query : undefined;
+        const limit = typeof params.limit === "number" ? params.limit : 50;
+        let entries = collectComposites(plugins);
+        if (lexicon)
+            entries = entries.filter((e) => e.lexicon === lexicon);
+        if (query) {
+            const lowerQuery = query.toLowerCase();
+            entries = entries
+                .map((entry) => ({ entry, score: compositeMatchScore(entry, lowerQuery) }))
+                .filter(({ score }) => score > 0)
+                .sort((a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name))
+                .map(({ entry }) => entry);
+        }
+        return {
+            ...(lexicon ? { lexicon } : {}),
+            ...(query ? { query } : {}),
+            // The loaded lexicons, so an empty answer for `lexicon: "cedar"` reads
+            // as "cedar exports none" when cedar is listed, and "not loaded" when not.
+            lexicons: plugins.map((p) => p.name),
+            total: entries.length,
+            composites: entries.slice(0, limit),
+        };
+    };
+}