@intentius/chant 0.0.5 → 0.0.9

package/src/cli/commands/update.ts

@@ -1,5 +1,6 @@
-import { existsSync, mkdirSync, writeFileSync, cpSync, readdirSync, statSync } from "fs";
+import { existsSync, mkdirSync, writeFileSync, cpSync, readdirSync, statSync, readFileSync } from "fs";
 import { join, resolve } from "path";
+import { createRequire } from "module";
 import { formatSuccess, formatWarning, formatError } from "../format";
 import { loadChantConfig } from "../../config";
 import { loadPlugins } from "../plugins";
@@ -63,13 +64,14 @@ function copyTypeFiles(src: string, dest: string): number {
 function resolvePackagePath(packageName: string, projectDir: string): string | undefined {
   // Try resolve from project dir
   try {
-    const entryPoint = require.resolve(packageName, { paths: [projectDir] });
+    const _require = createRequire(join(projectDir, "package.json"));
+    const entryPoint = _require.resolve(packageName);
     // Walk up from entry point to find package root
     let dir = entryPoint;
     while (dir !== "/") {
       dir = join(dir, "..");
       if (existsSync(join(dir, "package.json"))) {
-        const pkg = JSON.parse(require("fs").readFileSync(join(dir, "package.json"), "utf-8"));
+        const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8"));
         if (pkg.name === packageName) return dir;
       }
     }

package/src/cli/conflict-check.test.ts

@@ -22,7 +22,6 @@ function makePlugin(
     validate: noopAsync,
     coverage: noopAsync,
     package: noopAsync,
-    rollback: noopAsync,
   };
 
   if (opts.rules) {

package/src/cli/handlers/dev.ts

@@ -21,18 +21,10 @@ export async function runDevPublish(ctx: CommandContext): Promise<number> {
   return 0;
 }
 
-export async function runDevRollback(ctx: CommandContext): Promise<number> {
-  for (const plugin of ctx.plugins) {
-    await plugin.rollback({ verbose: ctx.args.verbose });
-    console.error(formatSuccess(`${plugin.name}: rollback complete`));
-  }
-  return 0;
-}
-
 export async function runDevUnknown(ctx: CommandContext): Promise<number> {
   console.error(formatError({
     message: `Unknown dev subcommand: ${ctx.args.path}`,
-    hint: "Available: chant dev generate, chant dev publish, chant dev rollback",
+    hint: "Available: chant dev generate, chant dev publish",
   }));
   return 1;
 }

package/src/cli/handlers/init.ts

@@ -16,6 +16,7 @@ export async function runInit(ctx: CommandContext): Promise<number> {
   const result = await initCommand({
     path: args.path === "." ? undefined : args.path,
     lexicon: args.lexicon,
+    template: args.template,
     force: args.force,
     skipInstall: true,
   });

package/src/cli/lsp/server.ts

@@ -362,7 +362,7 @@ export class LspServer {
 
       if (rules.length === 0) return [];
 
-      const diagnostics = await runLint([filePath], rules);
+      const { diagnostics } = await runLint([filePath], rules);
       return toLspDiagnostics(diagnostics);
     } catch {
       return [];

package/src/cli/main.ts

@@ -4,9 +4,11 @@ import { resolve } from "node:path";
 import { formatSuccess, formatError } from "./format";
 import { loadPlugins, resolveProjectLexicons } from "./plugins";
 import { resolveCommand, type CommandDef, type ParsedArgs } from "./registry";
+import { loadChantConfig } from "../config";
+import { initRuntime } from "../runtime-adapter";
 import { runBuild } from "./handlers/build";
 import { runLint } from "./handlers/lint";
-import { runDevGenerate, runDevPublish, runDevRollback, runDevUnknown } from "./handlers/dev";
+import { runDevGenerate, runDevPublish, runDevUnknown } from "./handlers/dev";
 import { runServeLsp, runServeMcp, runServeUnknown } from "./handlers/serve";
 import { runInit, runInitLexicon } from "./handlers/init";
 import { runList, runImport, runUpdate, runDoctor } from "./handlers/misc";
@@ -25,6 +27,7 @@ export function parseArgs(args: string[]): ParsedArgs {
     force: undefined,
     fix: false,
     lexicon: undefined,
+    template: undefined,
     watch: false,
     verbose: false,
     help: false,
@@ -42,6 +45,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.format = args[++i];
     } else if (arg === "--lexicon" || arg === "-d") {
       result.lexicon = args[++i];
+    } else if (arg === "--template" || arg === "-t") {
+      result.template = args[++i];
     } else if (arg === "--force") {
       result.force = true;
     } else if (arg === "--fix") {
@@ -89,7 +94,6 @@ Commands:
 Lexicon development:
   dev generate          Generate lexicon artifacts (+ validate + coverage)
   dev publish           Package lexicon for distribution
-  dev rollback          List or restore generation snapshots
 
 Servers:
   serve lsp             Start the LSP server (stdio)
@@ -106,6 +110,7 @@ Options:
                         - list: text (default) or json
                         - lint: stylish (default), json, or sarif
   -d, --lexicon <name>  Build only the specified lexicon (e.g. aws, gitlab)
+  -t, --template <name> Init template (e.g. node-pipeline, docker-build)
   --fix                 Auto-fix fixable issues (lint command)
   --force               Force overwrite existing files (import command)
   -w, --watch           Watch for changes and rebuild/re-lint (build, lint)
@@ -167,7 +172,6 @@ const registry: CommandDef[] = [
   // Dev subcommands
   { name: "dev generate", requiresPlugins: true, handler: runDevGenerate },
   { name: "dev publish", requiresPlugins: true, handler: runDevPublish },
-  { name: "dev rollback", requiresPlugins: true, handler: runDevRollback },
 
   // Serve subcommands
   { name: "serve lsp", requiresPlugins: true, handler: runServeLsp },
@@ -189,6 +193,16 @@ async function main(): Promise<void> {
     process.exit(args.help ? 0 : 1);
   }
 
+  // Initialize runtime adapter early — before plugins or commands run
+  const projectPath0 = resolve(args.path === "." ? "." : args.path);
+  try {
+    const { config } = await loadChantConfig(projectPath0);
+    initRuntime(config.runtime);
+  } catch {
+    // Config may not exist yet (e.g. `chant init`); auto-detect runtime
+    initRuntime();
+  }
+
   const match = resolveCommand(args, registry);
   if (!match) {
     console.error(formatError({

package/src/cli/mcp/server.test.ts

@@ -81,7 +81,7 @@ describe("McpServer", () => {
   // -----------------------------------------------------------------------
 
   describe("tools/list", () => {
-    test("returns core tools (build, lint, import)", async () => {
+    test("returns core tools (build, lint, import, explain, scaffold, search)", async () => {
       const response = await server.handleRequest({
         jsonrpc: "2.0",
         id: 1,
@@ -94,6 +94,9 @@ describe("McpServer", () => {
       expect(toolNames).toContain("build");
       expect(toolNames).toContain("lint");
       expect(toolNames).toContain("import");
+      expect(toolNames).toContain("explain");
+      expect(toolNames).toContain("scaffold");
+      expect(toolNames).toContain("search");
     });
 
     test("each tool has name, description, and inputSchema", async () => {
@@ -148,6 +151,46 @@ describe("McpServer", () => {
       expect(props.source).toBeDefined();
       expect(props.output).toBeDefined();
     });
+
+    test("explain tool schema has path and format properties", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/list",
+      });
+      const result = response.result as { tools: Array<{ name: string; inputSchema: Record<string, unknown> }> };
+      const tool = result.tools.find((t) => t.name === "explain")!;
+      const props = tool.inputSchema.properties as Record<string, unknown>;
+      expect(props.path).toBeDefined();
+      expect(props.format).toBeDefined();
+    });
+
+    test("scaffold tool schema has pattern and lexicon properties", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/list",
+      });
+      const result = response.result as { tools: Array<{ name: string; inputSchema: Record<string, unknown> }> };
+      const tool = result.tools.find((t) => t.name === "scaffold")!;
+      const props = tool.inputSchema.properties as Record<string, unknown>;
+      expect(props.pattern).toBeDefined();
+      expect(props.lexicon).toBeDefined();
+    });
+
+    test("search tool schema has query, lexicon, and limit properties", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/list",
+      });
+      const result = response.result as { tools: Array<{ name: string; inputSchema: Record<string, unknown> }> };
+      const tool = result.tools.find((t) => t.name === "search")!;
+      const props = tool.inputSchema.properties as Record<string, unknown>;
+      expect(props.query).toBeDefined();
+      expect(props.lexicon).toBeDefined();
+      expect(props.limit).toBeDefined();
+    });
   });
 
   describe("tools/call", () => {
@@ -194,6 +237,192 @@ describe("McpServer", () => {
       expect(result.isError).toBe(true);
       expect(result.content[0].text).toContain("Error:");
     });
+
+    test("calls explain tool on empty directory", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "explain", arguments: { path: testDir } },
+      });
+
+      expect(response.error).toBeUndefined();
+      const result = response.result as { content: Array<{ type: string; text: string }> };
+      expect(result.content[0].type).toBe("text");
+      expect(result.content[0].text).toContain("Project Summary");
+    });
+
+    test("calls explain tool with json format", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "explain", arguments: { path: testDir, format: "json" } },
+      });
+
+      expect(response.error).toBeUndefined();
+      const result = response.result as { content: Array<{ text: string }> };
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.totalEntities).toBe(0);
+      expect(parsed.sourceFiles).toBeDefined();
+    });
+
+    test("calls scaffold tool with generic fallback", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "scaffold", arguments: { pattern: "my-service" } },
+      });
+
+      expect(response.error).toBeUndefined();
+      const result = response.result as { content: Array<{ text: string }> };
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.pattern).toBe("my-service");
+      expect(parsed.files).toBeDefined();
+      expect(parsed.files.length).toBeGreaterThan(0);
+    });
+
+    test("calls search tool with no plugins", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "search", arguments: { query: "bucket" } },
+      });
+
+      expect(response.error).toBeUndefined();
+      const result = response.result as { content: Array<{ text: string }> };
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.query).toBe("bucket");
+      expect(parsed.total).toBe(0);
+      expect(parsed.results).toEqual([]);
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // Search tool with plugins
+  // -----------------------------------------------------------------------
+
+  describe("search with plugins", () => {
+    test("searches plugin resource catalogs", async () => {
+      const plugin = createMockPlugin({
+        name: "test-lex",
+        mcpResources: () => [
+          {
+            uri: "resource-catalog",
+            name: "Test Catalog",
+            description: "Test resource catalog",
+            mimeType: "application/json",
+            handler: async () => JSON.stringify([
+              { className: "Bucket", resourceType: "AWS::S3::Bucket", kind: "resource" },
+              { className: "Table", resourceType: "AWS::DynamoDB::Table", kind: "resource" },
+            ]),
+          },
+        ],
+      });
+
+      const s = new McpServer([plugin]);
+      const response = await s.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "search", arguments: { query: "bucket" } },
+      });
+
+      const result = response.result as { content: Array<{ text: string }> };
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.total).toBe(1);
+      expect(parsed.results[0].className).toBe("Bucket");
+      expect(parsed.results[0].lexicon).toBe("test-lex");
+    });
+
+    test("search respects limit parameter", async () => {
+      const entries = Array.from({ length: 30 }, (_, i) => ({
+        className: `Type${i}`,
+        resourceType: `NS::Type${i}`,
+        kind: "resource",
+      }));
+      const plugin = createMockPlugin({
+        name: "big",
+        mcpResources: () => [
+          {
+            uri: "resource-catalog",
+            name: "Big Catalog",
+            description: "Big catalog",
+            mimeType: "application/json",
+            handler: async () => JSON.stringify(entries),
+          },
+        ],
+      });
+
+      const s = new McpServer([plugin]);
+      const response = await s.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "search", arguments: { query: "type", limit: 5 } },
+      });
+
+      const parsed = JSON.parse((response.result as { content: Array<{ text: string }> }).content[0].text);
+      expect(parsed.total).toBe(30);
+      expect(parsed.results.length).toBe(5);
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // Scaffold tool with plugins
+  // -----------------------------------------------------------------------
+
+  describe("scaffold with plugins", () => {
+    test("matches plugin init templates", async () => {
+      const plugin = createMockPlugin({
+        name: "test-lex",
+        initTemplates: () => ({ src: {
+          "config.ts": "export const config = {};",
+          "data-bucket.ts": "export const dataBucket = {};",
+        } }),
+      });
+
+      const s = new McpServer([plugin]);
+      const response = await s.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "scaffold", arguments: { pattern: "bucket", lexicon: "test-lex" } },
+      });
+
+      const parsed = JSON.parse((response.result as { content: Array<{ text: string }> }).content[0].text);
+      expect(parsed.lexicon).toBe("test-lex");
+      expect(parsed.files.length).toBe(1);
+      expect(parsed.files[0].filename).toBe("data-bucket.ts");
+    });
+
+    test("passes template name to initTemplates", async () => {
+      const plugin = createMockPlugin({
+        name: "test-lex",
+        initTemplates: (template?: string) => {
+          if (template === "special") {
+            return { src: { "special.ts": "export const special = {};" } };
+          }
+          return { src: { "default.ts": "export const def = {};" } };
+        },
+      });
+
+      const s = new McpServer([plugin]);
+      const response = await s.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "scaffold", arguments: { pattern: "special", lexicon: "test-lex", template: "special" } },
+      });
+
+      const parsed = JSON.parse((response.result as { content: Array<{ text: string }> }).content[0].text);
+      expect(parsed.lexicon).toBe("test-lex");
+      expect(parsed.template).toBe("special");
+      expect(parsed.files.length).toBe(1);
+      expect(parsed.files[0].filename).toBe("special.ts");
+    });
   });
 
   // -----------------------------------------------------------------------
@@ -729,8 +958,8 @@ describe("McpServer", () => {
 
       const toolsRes = await s.handleRequest({ jsonrpc: "2.0", id: 2, method: "tools/list" });
       const tools = (toolsRes.result as { tools: Array<{ name: string }> }).tools;
-      expect(tools).toHaveLength(3);
-      expect(tools.map((t) => t.name).sort()).toEqual(["build", "import", "lint"]);
+      expect(tools).toHaveLength(6);
+      expect(tools.map((t) => t.name).sort()).toEqual(["build", "explain", "import", "lint", "scaffold", "search"]);
 
       const resourcesRes = await s.handleRequest({ jsonrpc: "2.0", id: 3, method: "resources/list" });
       const resources = (resourcesRes.result as { resources: Array<{ uri: string }> }).resources;
@@ -741,7 +970,7 @@ describe("McpServer", () => {
       const s = new McpServer([]);
       const toolsRes = await s.handleRequest({ jsonrpc: "2.0", id: 1, method: "tools/list" });
       const tools = (toolsRes.result as { tools: Array<{ name: string }> }).tools;
-      expect(tools).toHaveLength(3);
+      expect(tools).toHaveLength(6);
     });
   });
 });

package/src/cli/mcp/server.ts

@@ -3,6 +3,9 @@ import { resolve } from "node:path";
 import { buildTool, handleBuild } from "./tools/build";
 import { lintTool, handleLint } from "./tools/lint";
 import { importTool, handleImport } from "./tools/import";
+import { explainTool, handleExplain } from "./tools/explain";
+import { scaffoldTool, createScaffoldHandler } from "./tools/scaffold";
+import { searchTool, createSearchHandler } from "./tools/search";
 import { getContext } from "./resources/context";
 import type { LexiconPlugin } from "../../lexicon";
 import type { McpToolContribution, McpResourceContribution } from "../../mcp/types";
@@ -70,6 +73,9 @@ export class McpServer {
     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 ?? []));
 
     // Register plugin contributions
     if (plugins) {

package/src/cli/mcp/tools/explain.ts

@@ -0,0 +1,134 @@
+import { resolve } from "path";
+import { discover } from "../../../discovery/index";
+
+/**
+ * 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" as const,
+    properties: {
+      path: {
+        type: "string",
+        description: "Path to the infrastructure directory to analyze",
+      },
+      format: {
+        type: "string",
+        enum: ["markdown", "json"],
+        description: "Output format (default: markdown)",
+      },
+    },
+    required: ["path"],
+  },
+};
+
+/**
+ * Handle explain tool invocation
+ */
+export async function handleExplain(params: Record<string, unknown>): Promise<unknown> {
+  const path = params.path as string;
+  const format = (params.format as "markdown" | "json") ?? "markdown";
+
+  const infraPath = resolve(path);
+  const result = await discover(infraPath);
+
+  // Group entities by lexicon and kind
+  const byLexicon = new Map<string, { resources: string[]; properties: string[] }>();
+
+  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: Array<{ from: string; to: string }> = [];
+  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") {
+    return summary;
+  }
+
+  // Markdown format
+  const lines: string[] = [];
+  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 (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");
+}