@intentius/chant 0.124.13 → 0.124.14

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

@@ -0,0 +1,166 @@
+import { resolve, dirname } from "path";
+import { discover } from "../../../discovery/index.js";
+import { buildOkfBundle, OKF_VERSION } from "../../../okf.js";
+import { loadOkfBundle, bindConcepts } from "../../../okf-read.js";
+import { loadChantConfigUpward, resolveKnowledgeDir } from "../../../config.js";
+function toKnowledgeEntry(concept) {
+    return { type: concept.type, title: concept.title, path: concept.path };
+}
+/**
+ * Explain tool definition for MCP
+ */
+export const explainTool = {
+    name: "explain",
+    description: "Analyze a chant project directory and return a structured summary of all discovered entities",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: {
+                type: "string",
+                description: "Path to the infrastructure directory to analyze",
+            },
+            format: {
+                type: "string",
+                enum: ["markdown", "json", "okf"],
+                description: "Output format (default: markdown). okf: an OKF v0.2 knowledge bundle — one markdown concept per entity plus an index.md (#1058)",
+            },
+        },
+        required: ["path"],
+    },
+};
+/**
+ * Handle explain tool invocation
+ */
+export async function handleExplain(params) {
+    const path = params.path;
+    const format = params.format ?? "markdown";
+    const infraPath = resolve(path);
+    const result = await discover(infraPath);
+    // OKF knowledge bundle (#1058): one concept document per entity plus a root
+    // index.md, returned as bundle-relative path → content. The CLI path writes
+    // the same files to a directory.
+    if (format === "okf") {
+        return {
+            okf_version: OKF_VERSION,
+            files: Object.fromEntries(buildOkfBundle(result, infraPath).map((f) => [f.path, f.content])),
+            errors: result.errors.map((e) => e.message),
+        };
+    }
+    // Authored knowledge (#1867, design #1059): bind the project's OKF bundle
+    // (if any) to the discovered entities and carry each bound concept's
+    // type/title/path into the summary. A project with no `knowledge/` yet
+    // binds nothing — `bound` is empty — so the section is omitted below
+    // rather than rendered empty; this is the CLI and MCP tool's one shared
+    // code path, so both surfaces match by construction.
+    // `loadChantConfigUpward` walks up from `infraPath` (chant #1117) — a
+    // `chant explain src/<stack>` two levels below `chant.config.ts` must find
+    // the same `knowledge/` a `chant explain .` at the root would, matching
+    // `build.ts`'s `configDir` derivation for the same reason.
+    const loaded = await loadChantConfigUpward(infraPath);
+    const projectRoot = loaded.configPath ? dirname(loaded.configPath) : infraPath;
+    const knowledgeDir = resolveKnowledgeDir(loaded.config, projectRoot);
+    const bundle = await loadOkfBundle(knowledgeDir);
+    const { bound } = bindConcepts(bundle, result.entities);
+    const knowledge = new Map(Array.from(bound.entries()).map(([name, concepts]) => [name, concepts.map(toKnowledgeEntry)]));
+    // Group entities by lexicon and kind
+    const byLexicon = new Map();
+    for (const [name, entity] of result.entities) {
+        const lexicon = entity.lexicon ?? "unknown";
+        if (!byLexicon.has(lexicon)) {
+            byLexicon.set(lexicon, { resources: [], properties: [] });
+        }
+        const group = byLexicon.get(lexicon);
+        if (entity.kind === "property") {
+            group.properties.push(name);
+        }
+        else {
+            group.resources.push(name);
+        }
+    }
+    // Collect dependency info
+    const crossResourceDeps = [];
+    for (const [from, deps] of result.dependencies) {
+        for (const to of deps) {
+            crossResourceDeps.push({ from, to });
+        }
+    }
+    const summary = {
+        sourceFiles: result.sourceFiles,
+        totalEntities: result.entities.size,
+        lexicons: Object.fromEntries(Array.from(byLexicon.entries()).map(([lexicon, group]) => [
+            lexicon,
+            {
+                resourceCount: group.resources.length,
+                propertyCount: group.properties.length,
+                resources: group.resources,
+                properties: group.properties,
+            },
+        ])),
+        dependencies: crossResourceDeps,
+        errors: result.errors.map((e) => e.message),
+    };
+    if (format === "json") {
+        // Omitted entirely when no entity bound a concept — "cleanly absent" per
+        // #1867's AC, not an empty `{}`.
+        return knowledge.size > 0
+            ? { ...summary, knowledge: Object.fromEntries(knowledge) }
+            : summary;
+    }
+    // Markdown format
+    const lines = [];
+    lines.push(`# Project Summary`);
+    lines.push("");
+    lines.push(`- **Source files:** ${result.sourceFiles.length}`);
+    lines.push(`- **Total entities:** ${result.entities.size}`);
+    lines.push("");
+    for (const [lexicon, group] of byLexicon) {
+        lines.push(`## Lexicon: ${lexicon}`);
+        lines.push("");
+        lines.push(`- Resources: ${group.resources.length}`);
+        lines.push(`- Properties: ${group.properties.length}`);
+        lines.push("");
+        if (group.resources.length > 0) {
+            lines.push("### Resources");
+            for (const name of group.resources) {
+                lines.push(`- \`${name}\``);
+            }
+            lines.push("");
+        }
+        if (group.properties.length > 0) {
+            lines.push("### Properties");
+            for (const name of group.properties) {
+                lines.push(`- \`${name}\``);
+            }
+            lines.push("");
+        }
+    }
+    if (crossResourceDeps.length > 0) {
+        lines.push("## Dependencies");
+        lines.push("");
+        for (const dep of crossResourceDeps) {
+            lines.push(`- \`${dep.from}\` → \`${dep.to}\``);
+        }
+        lines.push("");
+    }
+    if (knowledge.size > 0) {
+        lines.push("## Knowledge");
+        lines.push("");
+        for (const [name, entries] of knowledge) {
+            lines.push(`### \`${name}\``);
+            for (const entry of entries) {
+                const title = entry.title ? `${entry.title} ` : "";
+                lines.push(`- ${entry.type || "concept"}: ${title}(\`${entry.path}\`)`);
+            }
+            lines.push("");
+        }
+    }
+    if (result.errors.length > 0) {
+        lines.push("## Errors");
+        lines.push("");
+        for (const err of result.errors) {
+            lines.push(`- ${err.message}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}

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

@@ -0,0 +1,49 @@
+import { importCommand } from "../../commands/import.js";
+/**
+ * Import tool definition for MCP
+ */
+export const importTool = {
+    name: "import",
+    description: "Import external templates and convert them to chant TypeScript",
+    inputSchema: {
+        type: "object",
+        properties: {
+            source: {
+                type: "string",
+                description: "Path to the template file to import",
+            },
+            output: {
+                type: "string",
+                description: "Output directory (default: ./infra/)",
+            },
+            lexicon: {
+                type: "string",
+                description: "Lexicon to import with (e.g. k8s); skips template detection",
+            },
+        },
+        required: ["source"],
+    },
+};
+/**
+ * Handle import tool invocation
+ */
+export async function handleImport(params) {
+    const source = params.source;
+    const output = params.output;
+    const lexicon = params.lexicon;
+    const result = await importCommand({
+        templatePath: source,
+        output,
+        force: true,
+        lexicon,
+    });
+    if (!result.success) {
+        throw new Error(result.error ?? "Import failed");
+    }
+    return {
+        success: true,
+        lexicon: result.lexicon,
+        generatedFiles: result.generatedFiles,
+        warnings: result.warnings,
+    };
+}

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

@@ -0,0 +1,41 @@
+import { lintCommand } from "../../commands/lint.js";
+/**
+ * Lint tool definition for MCP
+ */
+export const lintTool = {
+    name: "lint",
+    description: "Lint chant infrastructure code and report issues",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: {
+                type: "string",
+                description: "Path to the infrastructure directory or file to lint",
+            },
+            fix: {
+                type: "boolean",
+                description: "Automatically fix issues where possible",
+            },
+        },
+        required: ["path"],
+    },
+};
+/**
+ * Handle lint tool invocation
+ */
+export async function handleLint(params) {
+    const path = params.path;
+    const fix = params.fix ?? false;
+    const result = await lintCommand({
+        path,
+        fix,
+        format: "json",
+    });
+    return {
+        success: result.success,
+        errorCount: result.errorCount,
+        warningCount: result.warningCount,
+        diagnostics: result.diagnostics,
+        output: result.output,
+    };
+}

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

@@ -0,0 +1,111 @@
+/**
+ * Scaffold tool definition for MCP
+ */
+export const scaffoldTool = {
+    name: "scaffold",
+    description: "Generate starter code for a common infrastructure pattern",
+    inputSchema: {
+        type: "object",
+        properties: {
+            pattern: {
+                type: "string",
+                description: "Infrastructure pattern to scaffold (e.g. 's3-bucket', 'lambda', 'pipeline')",
+            },
+            lexicon: {
+                type: "string",
+                description: "Lexicon to use for scaffolding (e.g. 'aws', 'gitlab'). Auto-detected if omitted.",
+            },
+            template: {
+                type: "string",
+                description: "Named init template (e.g. 'node-pipeline', 'docker-build'). When provided, returns the template's source files instead of pattern-matching.",
+            },
+        },
+        required: ["pattern"],
+    },
+};
+/**
+ * Create a scaffold handler with access to loaded plugins
+ */
+export function createScaffoldHandler(plugins) {
+    return async (params) => {
+        const pattern = params.pattern;
+        const lexiconName = params.lexicon;
+        const templateName = params.template;
+        // Try to find a matching plugin
+        const candidates = lexiconName
+            ? plugins.filter((p) => p.name === lexiconName)
+            : plugins;
+        // Search plugin init templates for a pattern match
+        for (const plugin of candidates) {
+            const templateSet = plugin.initTemplates?.(templateName);
+            if (!templateSet)
+                continue;
+            // If a named template was requested, return all its source files
+            if (templateName) {
+                const files = Object.entries(templateSet.src).map(([filename, content]) => ({ filename, content }));
+                if (files.length > 0) {
+                    return {
+                        lexicon: plugin.name,
+                        pattern,
+                        template: templateName,
+                        files,
+                    };
+                }
+            }
+            // Match template filenames against the pattern (case-insensitive substring)
+            const lowerPattern = pattern.toLowerCase();
+            const matched = [];
+            for (const [filename, content] of Object.entries(templateSet.src)) {
+                if (filename.toLowerCase().includes(lowerPattern)) {
+                    matched.push({ filename, content });
+                }
+            }
+            if (matched.length > 0) {
+                return {
+                    lexicon: plugin.name,
+                    pattern,
+                    files: matched,
+                };
+            }
+        }
+        // Fall back to a generic skeleton
+        const configContent = `/**
+ * Shared configuration for ${pattern}
+ */
+
+// TODO: Import resource types from your lexicon
+// import { ... } from "@intentius/chant-lexicon-<name>";
+
+export const config = {
+  // Add shared configuration here
+};
+`;
+        const resourceContent = `/**
+ * ${pattern} resource definition
+ */
+
+// TODO: Import resource types from your lexicon
+// import { ... } from "@intentius/chant-lexicon-<name>";
+// import { config } from "./config";
+
+// export const ${toCamelCase(pattern)} = new ResourceType({
+//   // Add properties here
+// });
+`;
+        return {
+            lexicon: lexiconName ?? null,
+            pattern,
+            files: [
+                { filename: "config.ts", content: configContent },
+                { filename: `${pattern}.ts`, content: resourceContent },
+            ],
+            note: "No lexicon-specific template found. Generic skeleton provided — fill in imports and resource types.",
+        };
+    };
+}
+function toCamelCase(s) {
+    return s
+        .split(/[-_]/)
+        .map((part, i) => (i === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)))
+        .join("");
+}

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

@@ -0,0 +1,112 @@
+import { collectComposites, compositeMatchScore } from "./composites.js";
+/**
+ * Search tool definition for MCP
+ */
+export const searchTool = {
+    name: "search",
+    description: "Search the resource catalog and the composite catalog across loaded lexicons by keyword; a composite comes back with kind 'composite'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                description: "Search query: matches a resource's type, class name and kind, and a composite's name, description and the resource kinds it bundles",
+            },
+            lexicon: {
+                type: "string",
+                description: "Filter results to a specific lexicon (e.g. 'aws', 'gitlab')",
+            },
+            limit: {
+                type: "number",
+                description: "Maximum number of results to return (default: 20)",
+            },
+        },
+        required: ["query"],
+    },
+};
+function sortKey(result) {
+    return "resourceType" in result ? result.resourceType ?? "" : result.name;
+}
+/**
+ * Create a search handler with access to loaded plugins
+ */
+export function createSearchHandler(plugins) {
+    return async (params) => {
+        const query = params.query;
+        const lexiconFilter = params.lexicon;
+        const limit = params.limit ?? 20;
+        const lowerQuery = query.toLowerCase();
+        const results = [];
+        const candidates = lexiconFilter
+            ? plugins.filter((p) => p.name === lexiconFilter)
+            : plugins;
+        for (const plugin of candidates) {
+            const resources = plugin.mcpResources?.() ?? [];
+            // Catalog URIs were unscoped ("resource-catalog") before lexicon
+            // namespacing landed; new lexicons emit "<lexicon>:resource-catalog"
+            // to avoid cross-lexicon collision. Support both.
+            const catalog = resources.find((r) => r.uri === "resource-catalog" || r.uri.endsWith(":resource-catalog"));
+            if (!catalog)
+                continue;
+            let entries;
+            try {
+                const raw = await catalog.handler();
+                entries = JSON.parse(raw);
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                const fields = [
+                    entry.resourceType?.toLowerCase() ?? "",
+                    entry.className?.toLowerCase() ?? "",
+                    entry.kind?.toLowerCase() ?? "",
+                ];
+                const match = fields.some((f) => f.includes(lowerQuery));
+                if (!match)
+                    continue;
+                // Score: prefix match on resourceType or className ranks higher
+                const isPrefix = fields.some((f) => f.startsWith(lowerQuery));
+                const score = isPrefix ? 1 : 0;
+                results.push({ ...entry, lexicon: plugin.name, score });
+            }
+        }
+        // Composites (#2662), so one query finds both a resource type and the
+        // composite that bundles it. A name or bundled-kind prefix ranks with the
+        // resource prefix matches. The full entry (params included) is the
+        // `composites` tool's answer; search keeps a result short.
+        for (const entry of collectComposites(candidates)) {
+            const score = compositeMatchScore(entry, lowerQuery);
+            if (score === 0)
+                continue;
+            const isPrefix = entry.name.toLowerCase().startsWith(lowerQuery) ||
+                entry.bundles.some((b) => b.toLowerCase().startsWith(lowerQuery));
+            results.push({
+                kind: "composite",
+                name: entry.name,
+                description: entry.description,
+                bundles: entry.bundles,
+                lexicon: entry.lexicon,
+                score: isPrefix ? 1 : 0,
+            });
+        }
+        // Sort: prefix matches first; within a tier composites ahead of resource
+        // types, since a handful of composites would otherwise sort behind every
+        // `AWS::...` type the same word prefixes; then alphabetical.
+        results.sort((a, b) => {
+            if (a.score !== b.score)
+                return b.score - a.score;
+            const aComposite = a.kind === "composite" ? 0 : 1;
+            const bComposite = b.kind === "composite" ? 0 : 1;
+            if (aComposite !== bComposite)
+                return aComposite - bComposite;
+            return sortKey(a).localeCompare(sortKey(b));
+        });
+        const limited = results.slice(0, limit);
+        return {
+            query,
+            total: results.length,
+            results: limited.map(({ score: _score, ...entry }) => entry),
+        };
+    };
+}

package/dist/cli/mcp/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/mcp/workspace-plugins.js

@@ -0,0 +1,91 @@
+/**
+ * #2700 — the lexicons `chant serve mcp` loads at the root of a declared
+ * workspace that has no lexicon of its own.
+ *
+ * Such a root (a generated app repo, say, whose lexicons are all under a
+ * delivery directory) used to refuse with "No lexicon detected", so an agent
+ * started there got none of chant's tools. The server now starts with core's
+ * tools and resources, and with the lexicons of the workspace's members of
+ * kind chant, each read from that member's own config the way `chant build`
+ * in the member's directory reads it.
+ *
+ * Loading is best effort, one member and one lexicon at a time: a member whose
+ * config does not load, or a lexicon this chant cannot import, is left out and
+ * named in the server's `instructions`, and the rest are served. Nothing here
+ * fails the server; with nothing loaded it serves core alone and says so.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+function message(error) {
+    const text = error instanceof Error ? error.message : String(error);
+    return text.split("\n")[0];
+}
+/** Load the lexicons of the chant members of the workspace declared at `root`. */
+export async function loadWorkspacePlugins(root) {
+    const [{ readDeclaration }, { workingTree }, { resolveProjectLexicons, loadPlugins }] = await Promise.all([
+        import("../../workspace/declaration.js"),
+        import("../../workspace/tree.js"),
+        import("../plugins.js"),
+    ]);
+    const members = [];
+    let workspaceName;
+    let declarationError;
+    try {
+        const declaration = readDeclaration(workingTree(root));
+        workspaceName = declaration.name;
+        for (const m of declaration.members) {
+            // The root member is the directory this server already found no lexicon in.
+            if (m.kind !== "chant" || m.dir === ".")
+                continue;
+            const abs = join(root, m.dir);
+            if (!existsSync(abs)) {
+                members.push({ member: m.name, dir: m.dir, lexicons: null, error: "its directory does not exist" });
+                continue;
+            }
+            try {
+                members.push({ member: m.name, dir: m.dir, lexicons: await resolveProjectLexicons(abs) });
+            }
+            catch (error) {
+                members.push({ member: m.name, dir: m.dir, lexicons: null, error: message(error) });
+            }
+        }
+    }
+    catch (error) {
+        declarationError = message(error);
+    }
+    const plugins = [];
+    const failed = [];
+    const seen = new Set();
+    for (const m of members) {
+        for (const name of m.lexicons ?? []) {
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            try {
+                plugins.push(...(await loadPlugins([name])));
+            }
+            catch (error) {
+                failed.push({ lexicon: name, error: message(error) });
+            }
+        }
+    }
+    return { plugins, members, failed, instructions: describe(workspaceName, members, plugins, failed, declarationError) };
+}
+function describe(name, members, plugins, failed, declarationError) {
+    const lines = [];
+    lines.push(`This chant MCP server runs at the root of the workspace ${name ? `"${name}" ` : ""}(chant.workspace.json), which has no lexicon of its own. ` +
+        "Core tools and resources are served as in any project. The tools that take a path (build, lint, explain) work on a project directory, so pass a member's directory.");
+    if (declarationError)
+        lines.push(`The workspace declaration could not be read: ${declarationError}.`);
+    for (const m of members) {
+        lines.push(m.lexicons
+            ? `Member ${m.member} (${m.dir}/) declares ${m.lexicons.length ? m.lexicons.join(", ") : "no lexicon"}.`
+            : `Member ${m.member} (${m.dir}/) was not read: ${m.error}.`);
+    }
+    for (const f of failed)
+        lines.push(`Lexicon ${f.lexicon} did not load: ${f.error}.`);
+    lines.push(plugins.length > 0
+        ? `Lexicon tools and resources served: ${plugins.map((p) => p.name).join(", ")}.`
+        : "No member lexicon loaded, so only chant's core tools and resources are served.");
+    return lines.join("\n");
+}

package/dist/cli/mcp/workspace-tools.d.ts

@@ -44,7 +44,7 @@ import type { ToolDefinition, ToolHandler } from "./types.js";
 /** How the reads run chant: a command and its leading arguments. */
 export type ChantCommand = string[];
 /**
- * The chant this process runs as: node with the same flags (the tsx loader
+ * The chant this process runs as: node with the same flags (from source, the tsx loader
  * `bin/chant` registers) and the same entry script.
  */
 export declare function ownChantCommand(): ChantCommand;