@intentius/chant 0.0.18 → 0.0.24

package/src/cli/mcp/server.ts

@@ -6,66 +6,17 @@ 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";
-
-/**
- * MCP message types
- */
-interface McpRequest {
-  jsonrpc: "2.0";
-  id: string | number;
-  method: string;
-  params?: Record<string, unknown>;
-}
-
-interface McpResponse {
-  jsonrpc: "2.0";
-  id: string | number;
-  result?: unknown;
-  error?: {
-    code: number;
-    message: string;
-    data?: unknown;
-  };
-}
-
-interface McpNotification {
-  jsonrpc: "2.0";
-  method: string;
-  params?: Record<string, unknown>;
-}
-
-/**
- * Tool definition for MCP
- */
-interface ToolDefinition {
-  name: string;
-  description: string;
-  inputSchema: {
-    type: "object";
-    properties: Record<string, unknown>;
-    required?: string[];
-  };
-}
-
-/**
- * Resource definition for MCP
- */
-interface ResourceDefinition {
-  uri: string;
-  name: string;
-  description: string;
-  mimeType?: string;
-}
+import type { McpRequest, McpResponse, ToolDefinition, ToolHandler, ResourceDefinition } from "./types";
+import { createSnapshotTool, createDiffTool, createSpellDoneTool } from "./state-tools";
+import { buildResourcesList, handleResourcesRead } from "./resource-handlers";
 
 /**
  * MCP Server implementation
  */
 export class McpServer {
   private tools: Map<string, ToolDefinition> = new Map();
-  private toolHandlers: Map<string, (params: Record<string, unknown>) => Promise<unknown>> = new Map();
+  private toolHandlers: Map<string, ToolHandler> = new Map();
   private pluginResources: Map<string, { definition: ResourceDefinition; handler: () => Promise<string> }> = new Map();
 
   constructor(plugins?: LexiconPlugin[]) {
@@ -77,6 +28,16 @@ export class McpServer {
     this.registerTool(scaffoldTool, createScaffoldHandler(plugins ?? []));
     this.registerTool(searchTool, createSearchHandler(plugins ?? []));
 
+    // Register state tools
+    const snapshot = createSnapshotTool(plugins ?? []);
+    this.registerTool(snapshot.definition, snapshot.handler);
+
+    const diff = createDiffTool(plugins ?? []);
+    this.registerTool(diff.definition, diff.handler);
+
+    const spellDone = createSpellDoneTool();
+    this.registerTool(spellDone.definition, spellDone.handler);
+
     // Register plugin contributions
     if (plugins) {
       for (const plugin of plugins) {
@@ -128,7 +89,7 @@ export class McpServer {
    */
   private registerTool(
     definition: ToolDefinition,
-    handler: (params: Record<string, unknown>) => Promise<unknown>
+    handler: ToolHandler,
   ): void {
     this.tools.set(definition.name, definition);
     this.toolHandlers.set(definition.name, handler);
@@ -163,51 +124,29 @@ export class McpServer {
   private async dispatch(method: string, params: Record<string, unknown>): Promise<unknown> {
     switch (method) {
       case "initialize":
-        return this.handleInitialize(params);
+        return {
+          protocolVersion: "2024-11-05",
+          capabilities: { tools: {}, resources: {} },
+          serverInfo: { name: "chant", version: "0.1.0" },
+        };
 
       case "tools/list":
-        return this.handleToolsList();
+        return { tools: Array.from(this.tools.values()) };
 
       case "tools/call":
         return this.handleToolsCall(params);
 
       case "resources/list":
-        return this.handleResourcesList();
+        return buildResourcesList(this.pluginResources);
 
       case "resources/read":
-        return this.handleResourcesRead(params);
+        return handleResourcesRead(params, this.pluginResources);
 
       default:
         throw new Error(`Unknown method: ${method}`);
     }
   }
 
-  /**
-   * Handle initialize request
-   */
-  private handleInitialize(params: Record<string, unknown>): unknown {
-    return {
-      protocolVersion: "2024-11-05",
-      capabilities: {
-        tools: {},
-        resources: {},
-      },
-      serverInfo: {
-        name: "chant",
-        version: "0.1.0",
-      },
-    };
-  }
-
-  /**
-   * Handle tools/list request
-   */
-  private handleToolsList(): unknown {
-    return {
-      tools: Array.from(this.tools.values()),
-    };
-  }
-
   /**
    * Handle tools/call request
    */
@@ -218,12 +157,7 @@ export class McpServer {
     const handler = this.toolHandlers.get(name);
     if (!handler) {
       return {
-        content: [
-          {
-            type: "text",
-            text: `Error: Unknown tool: ${name}`,
-          },
-        ],
+        content: [{ type: "text", text: `Error: Unknown tool: ${name}` }],
         isError: true,
       };
     }
@@ -251,115 +185,6 @@ export class McpServer {
     }
   }
 
-  /**
-   * Handle resources/list request — merges core + plugin resources
-   */
-  private handleResourcesList(): unknown {
-    const resources: ResourceDefinition[] = [
-      {
-        uri: "chant://context",
-        name: "chant Context",
-        description: "Lexicon-specific instructions and patterns for chant development",
-        mimeType: "text/markdown",
-      },
-      {
-        uri: "chant://examples/list",
-        name: "Examples List",
-        description: "List of available chant examples",
-        mimeType: "application/json",
-      },
-    ];
-
-    // Merge plugin resources
-    for (const { definition } of this.pluginResources.values()) {
-      resources.push(definition);
-    }
-
-    return { resources };
-  }
-
-  /**
-   * Collect example resources from plugins whose URI contains "examples/"
-   */
-  private collectExamples(): Array<{ name: string; description: string }> {
-    const examples: Array<{ name: string; description: string }> = [];
-    for (const [uri, { definition }] of this.pluginResources.entries()) {
-      if (uri.includes("/examples/")) {
-        const name = uri.replace(/^chant:\/\/[^/]+\/examples\//, "");
-        examples.push({ name, description: definition.description });
-      }
-    }
-    return examples;
-  }
-
-  /**
-   * Handle resources/read request — checks plugin resources after core
-   */
-  private async handleResourcesRead(params: Record<string, unknown>): Promise<unknown> {
-    const uri = params.uri as string;
-
-    if (uri === "chant://context") {
-      return {
-        contents: [
-          {
-            uri,
-            mimeType: "text/markdown",
-            text: getContext(),
-          },
-        ],
-      };
-    }
-
-    if (uri === "chant://examples/list") {
-      return {
-        contents: [
-          {
-            uri,
-            mimeType: "application/json",
-            text: JSON.stringify(this.collectExamples()),
-          },
-        ],
-      };
-    }
-
-    if (uri.startsWith("chant://examples/")) {
-      // Look up example in plugin resources
-      const name = uri.replace("chant://examples/", "");
-      for (const [pluginUri, pluginResource] of this.pluginResources.entries()) {
-        if (pluginUri.endsWith(`/examples/${name}`)) {
-          const text = await pluginResource.handler();
-          return {
-            contents: [
-              {
-                uri,
-                mimeType: pluginResource.definition.mimeType ?? "text/typescript",
-                text,
-              },
-            ],
-          };
-        }
-      }
-      throw new Error(`Example not found: ${name}`);
-    }
-
-    // Check plugin resources
-    const pluginResource = this.pluginResources.get(uri);
-    if (pluginResource) {
-      const text = await pluginResource.handler();
-      return {
-        contents: [
-          {
-            uri,
-            mimeType: pluginResource.definition.mimeType ?? "text/plain",
-            text,
-          },
-        ],
-      };
-    }
-
-    throw new Error(`Unknown resource: ${uri}`);
-  }
-
   /**
    * Start the MCP server on stdio
    */

package/src/cli/mcp/state-tools.ts

@@ -0,0 +1,138 @@
+import { resolve } from "node:path";
+import type { LexiconPlugin } from "../../lexicon";
+import type { ToolDefinition, ToolHandler } from "./types";
+import { readSnapshot } from "../../state/git";
+import { build } from "../../build";
+import { computeBuildDigest, diffDigests } from "../../state/digest";
+import { takeSnapshot } from "../../state/snapshot";
+import type { StateSnapshot } from "../../state/types";
+import { discoverSpells } from "../../spell/discovery";
+
+export interface ToolRegistration {
+  definition: ToolDefinition;
+  handler: ToolHandler;
+}
+
+/**
+ * Create state-snapshot tool definition and handler
+ */
+export function createSnapshotTool(plugins: LexiconPlugin[]): ToolRegistration {
+  return {
+    definition: {
+      name: "state-snapshot",
+      description: "Capture deployed state for an environment",
+      inputSchema: {
+        type: "object",
+        properties: {
+          environment: { type: "string", description: "Target environment" },
+          lexicon: { type: "string", description: "Optional — snapshot all lexicons if omitted" },
+        },
+        required: ["environment"],
+      },
+    },
+    handler: async (params) => {
+      const env = params.environment as string;
+      const lexiconFilter = params.lexicon as string | undefined;
+      const targetPlugins = lexiconFilter
+        ? plugins.filter((p) => p.name === lexiconFilter)
+        : plugins;
+      const pluginsWithDescribe = targetPlugins.filter((p) => p.describeResources);
+      if (pluginsWithDescribe.length === 0) return "No plugins implement describeResources";
+      const serializers = plugins.map((p) => p.serializer);
+      const buildResult = await build(resolve("."), serializers);
+      if (buildResult.errors.length > 0) return "Build failed";
+      const result = await takeSnapshot(env, pluginsWithDescribe, buildResult);
+      return { snapshots: result.snapshots.length, warnings: result.warnings, errors: result.errors };
+    },
+  };
+}
+
+/**
+ * Create state-diff tool definition and handler
+ */
+export function createDiffTool(plugins: LexiconPlugin[]): ToolRegistration {
+  return {
+    definition: {
+      name: "state-diff",
+      description: "Compare current build declarations against last snapshot's digest",
+      inputSchema: {
+        type: "object",
+        properties: {
+          environment: { type: "string", description: "Target environment" },
+          lexicon: { type: "string", description: "Optional — diff all lexicons if omitted" },
+        },
+        required: ["environment"],
+      },
+    },
+    handler: async (params) => {
+      const env = params.environment as string;
+      const lexiconFilter = params.lexicon as string | undefined;
+      const serializers = plugins.map((p) => p.serializer);
+      const buildResult = await build(resolve("."), serializers);
+      if (buildResult.errors.length > 0) return "Build failed";
+      const currentDigest = computeBuildDigest(buildResult);
+      const lexicons = lexiconFilter ? [lexiconFilter] : buildResult.manifest.lexicons;
+      const results: Record<string, unknown> = {};
+      for (const lex of lexicons) {
+        const content = await readSnapshot(env, lex);
+        let previousDigest = undefined;
+        if (content) {
+          const snapshot: StateSnapshot = JSON.parse(content);
+          previousDigest = snapshot.digest;
+        }
+        results[lex] = diffDigests(currentDigest, previousDigest);
+      }
+      return results;
+    },
+  };
+}
+
+/**
+ * Create spell-done tool definition and handler
+ */
+export function createSpellDoneTool(): ToolRegistration {
+  return {
+    definition: {
+      name: "spell-done",
+      description: "Mark a spell task as done",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Spell name" },
+          taskNumber: { type: "number", description: "Task number (1-based)" },
+        },
+        required: ["name", "taskNumber"],
+      },
+    },
+    handler: async (params) => {
+      const { readFileSync, writeFileSync } = await import("node:fs");
+      const { spells } = await discoverSpells();
+      const name = params.name as string;
+      const taskNumber = params.taskNumber as number;
+      const spell = spells.get(name);
+      if (!spell) return `Spell "${name}" not found`;
+      if (taskNumber < 1 || taskNumber > spell.definition.tasks.length) {
+        return `Invalid task number ${taskNumber}`;
+      }
+      const task = spell.definition.tasks[taskNumber - 1];
+      if (task.done) return `Task ${taskNumber} is already done`;
+
+      const content = readFileSync(spell.filePath, "utf-8");
+      let count = 0;
+      const rewritten = content.replace(
+        /task\(("[^"]*"|'[^']*'|`[^`]*`)((?:\s*,\s*\{[^}]*\})?)\)/g,
+        (match, desc, opts) => {
+          count++;
+          if (count !== taskNumber) return match;
+          if (opts && opts.includes("done:")) {
+            return match.replace(/done:\s*false/, "done: true");
+          }
+          return `task(${desc}, { done: true })`;
+        },
+      );
+      if (rewritten === content) return `Could not rewrite task ${taskNumber}`;
+      writeFileSync(spell.filePath, rewritten);
+      return `Task ${taskNumber} marked done: "${task.description}"`;
+    },
+  };
+}

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

@@ -58,7 +58,8 @@ export async function handleBuild(params: Record<string, unknown>): Promise<unkn
   // Combine all lexicon outputs
   const combined: Record<string, unknown> = {};
   for (const [lexiconName, lexiconOutput] of result.outputs) {
-    combined[lexiconName] = JSON.parse(lexiconOutput);
+    const raw = lexiconOutput;
+    combined[lexiconName] = JSON.parse(typeof raw === "string" ? raw : raw.primary);
   }
 
   let output = JSON.stringify(combined, null, 2);

package/src/cli/mcp/types.ts

@@ -0,0 +1,45 @@
+/**
+ * MCP message types
+ */
+export interface McpRequest {
+  jsonrpc: "2.0";
+  id: string | number;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface McpResponse {
+  jsonrpc: "2.0";
+  id: string | number;
+  result?: unknown;
+  error?: {
+    code: number;
+    message: string;
+    data?: unknown;
+  };
+}
+
+/**
+ * Tool definition for MCP
+ */
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: "object";
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+}
+
+/**
+ * Resource definition for MCP
+ */
+export interface ResourceDefinition {
+  uri: string;
+  name: string;
+  description: string;
+  mimeType?: string;
+}
+
+export type ToolHandler = (params: Record<string, unknown>) => Promise<unknown>;

package/src/cli/plugins.ts

@@ -33,7 +33,7 @@ export async function loadPlugin(lexiconName: string): Promise<LexiconPlugin> {
       validate: notSupported("validate"),
       coverage: notSupported("coverage"),
       package: notSupported("package"),
-      rollback: notSupported("rollback"),
+
     };
   }
 

package/src/cli/reporters/stylish.test.ts

@@ -17,9 +17,9 @@ describe("formatStylish", () => {
     }
   });
 
-  test("returns empty string for no diagnostics", () => {
+  test("returns summary line for no diagnostics", () => {
     const result = formatStylish([]);
-    expect(result).toBe("");
+    expect(result).toBe("\u2713 No problems found");
   });
 
   test("formats single diagnostic", () => {

package/src/cli/reporters/stylish.ts

@@ -36,7 +36,7 @@ function color(text: string, colorCode: string): string {
  */
 export function formatStylish(diagnostics: LintDiagnostic[]): string {
   if (diagnostics.length === 0) {
-    return "";
+    return formatSummary(0, 0);
   }
 
   // Group by file

package/src/codegen/docs-file-markers.ts

@@ -0,0 +1,69 @@
+/**
+ * File marker interpolation and MDX escaping utilities.
+ */
+
+import { readFileSync } from "fs";
+import { join } from "path";
+
+/** Escape curly braces so MDX doesn't treat them as JSX expressions. */
+export function escapeMdx(text: string): string {
+  return text.replace(/\{/g, "\\{").replace(/\}/g, "\\}");
+}
+
+/**
+ * Expand `{{file:path.ts}}` markers in content with fenced code blocks.
+ *
+ * Supported forms:
+ * - `{{file:path.ts}}` — full file
+ * - `{{file:path.ts:5-12}}` — lines 5–12 (1-based, inclusive)
+ * - `{{file:path.ts|title=custom.ts}}` — override the code block title
+ * - `{{file:path.ts:5-12|title=custom.ts}}` — both
+ */
+export function expandFileMarkers(content: string, examplesDir: string): string {
+  return content.replace(
+    /\{\{file:([^}]+)\}\}/g,
+    (_match, spec: string) => {
+      // Parse options after |
+      let filePart = spec;
+      let title: string | undefined;
+      const pipeIdx = spec.indexOf("|");
+      if (pipeIdx !== -1) {
+        filePart = spec.substring(0, pipeIdx);
+        const opts = spec.substring(pipeIdx + 1);
+        const titleMatch = opts.match(/title=([^\s|]+)/);
+        if (titleMatch) title = titleMatch[1];
+      }
+
+      // Parse line range after :digits-digits at end of filePart
+      let lineStart: number | undefined;
+      let lineEnd: number | undefined;
+      const rangeMatch = filePart.match(/^(.+):(\d+)-(\d+)$/);
+      if (rangeMatch) {
+        filePart = rangeMatch[1];
+        lineStart = parseInt(rangeMatch[2], 10);
+        lineEnd = parseInt(rangeMatch[3], 10);
+      }
+
+      const filePath = join(examplesDir, filePart);
+      let fileContent: string;
+      try {
+        fileContent = readFileSync(filePath, "utf-8");
+      } catch {
+        throw new Error(`File marker {{file:${spec}}} — file not found: ${filePath}`);
+      }
+
+      // Extract line range if specified
+      if (lineStart !== undefined && lineEnd !== undefined) {
+        const lines = fileContent.split("\n");
+        fileContent = lines.slice(lineStart - 1, lineEnd).join("\n");
+      }
+
+      // Determine language from extension
+      const ext = filePart.substring(filePart.lastIndexOf(".") + 1);
+      const lang = ext === "ts" || ext === "tsx" ? "typescript" : ext;
+      const displayTitle = title ?? filePart.substring(filePart.lastIndexOf("/") + 1);
+
+      return `\`\`\`${lang} title="${displayTitle}"\n${fileContent.trimEnd()}\n\`\`\``;
+    },
+  );
+}