@intentius/chant 0.0.16 → 0.0.22

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

@@ -10,6 +10,10 @@ function createMockPlugin(overrides?: Partial<LexiconPlugin>): LexiconPlugin {
   return {
     name: "mock",
     serializer: { name: "mock", serialize: () => "" } as unknown as Serializer,
+    generate: async () => {},
+    validate: async () => {},
+    coverage: async () => {},
+    package: async () => {},
     ...overrides,
   };
 }
@@ -401,11 +405,11 @@ describe("McpServer", () => {
     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 = {};" } };
+        initTemplates: (template?: string | undefined) => {
+          const src: Record<string, string> = template === "special"
+            ? { "special.ts": "export const special = {};" }
+            : { "default.ts": "export const def = {};" };
+          return { src };
         },
       });
 
@@ -958,19 +962,19 @@ 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(6);
-      expect(tools.map((t) => t.name).sort()).toEqual(["build", "explain", "import", "lint", "scaffold", "search"]);
+      expect(tools).toHaveLength(9);
+      expect(tools.map((t) => t.name).sort()).toEqual(["build", "explain", "import", "lint", "scaffold", "search", "spell-done", "state-diff", "state-snapshot"]);
 
       const resourcesRes = await s.handleRequest({ jsonrpc: "2.0", id: 3, method: "resources/list" });
       const resources = (resourcesRes.result as { resources: Array<{ uri: string }> }).resources;
-      expect(resources).toHaveLength(2);
+      expect(resources).toHaveLength(7);
     });
 
     test("server with empty plugins array works", async () => {
       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(6);
+      expect(tools).toHaveLength(9);
     });
   });
 });

package/src/cli/mcp/server.ts

@@ -9,6 +9,14 @@ import { searchTool, createSearchHandler } from "./tools/search";
 import { getContext } from "./resources/context";
 import type { LexiconPlugin } from "../../lexicon";
 import type { McpToolContribution, McpResourceContribution } from "../../mcp/types";
+import { readSnapshot, readEnvironmentSnapshots } 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";
+import { generatePrompt } from "../../spell/prompt";
+import { getRuntime } from "../../runtime-adapter";
 
 /**
  * MCP message types
@@ -31,12 +39,6 @@ interface McpResponse {
   };
 }
 
-interface McpNotification {
-  jsonrpc: "2.0";
-  method: string;
-  params?: Record<string, unknown>;
-}
-
 /**
  * Tool definition for MCP
  */
@@ -77,6 +79,117 @@ export class McpServer {
     this.registerTool(scaffoldTool, createScaffoldHandler(plugins ?? []));
     this.registerTool(searchTool, createSearchHandler(plugins ?? []));
 
+    // Register state tools
+    this.registerTool(
+      {
+        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"],
+        },
+      },
+      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 };
+      },
+    );
+
+    this.registerTool(
+      {
+        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"],
+        },
+      },
+      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;
+      },
+    );
+
+    // Register spell tools
+    this.registerTool(
+      {
+        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"],
+        },
+      },
+      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}"`;
+      },
+    );
+
     // Register plugin contributions
     if (plugins) {
       for (const plugin of plugins) {
@@ -268,6 +381,36 @@ export class McpServer {
         description: "List of available chant examples",
         mimeType: "application/json",
       },
+      {
+        uri: "chant://spells",
+        name: "Spells",
+        description: "List all spells with status, tasks, and lexicon",
+        mimeType: "application/json",
+      },
+      {
+        uri: "chant://spell/{name}",
+        name: "Spell details",
+        description: "Show spell definition and status",
+        mimeType: "application/json",
+      },
+      {
+        uri: "chant://spell/{name}/prompt",
+        name: "Spell bootstrap prompt",
+        description: "Bootstrap prompt for agent consumption",
+        mimeType: "text/markdown",
+      },
+      {
+        uri: "chant://state/{environment}",
+        name: "State (all lexicons)",
+        description: "All lexicon snapshots for an environment",
+        mimeType: "application/json",
+      },
+      {
+        uri: "chant://state/{environment}/{lexicon}",
+        name: "State (single lexicon)",
+        description: "Single lexicon snapshot for an environment",
+        mimeType: "application/json",
+      },
     ];
 
     // Merge plugin resources
@@ -322,6 +465,77 @@ export class McpServer {
       };
     }
 
+    // Spell resources
+    if (uri === "chant://spells") {
+      const { spells } = await discoverSpells();
+      const list = Array.from(spells.entries()).map(([name, s]) => ({
+        name,
+        status: s.status,
+        tasks: `${s.definition.tasks.filter((t) => t.done).length}/${s.definition.tasks.length}`,
+        lexicon: s.definition.lexicon ?? null,
+        overview: s.definition.overview,
+      }));
+      return {
+        contents: [{ uri, mimeType: "application/json", text: JSON.stringify(list, null, 2) }],
+      };
+    }
+
+    if (uri.startsWith("chant://spell/") && uri.endsWith("/prompt")) {
+      const name = uri.replace("chant://spell/", "").replace("/prompt", "");
+      const { spells } = await discoverSpells();
+      const spell = spells.get(name);
+      if (!spell) throw new Error(`Spell "${name}" not found`);
+      const rt = getRuntime();
+      const gitRootResult = await rt.spawn(["git", "rev-parse", "--show-toplevel"]);
+      const gitRoot = gitRootResult.stdout.trim();
+      const prompt = await generatePrompt(spell.definition, { gitRoot });
+      return {
+        contents: [{ uri, mimeType: "text/markdown", text: prompt }],
+      };
+    }
+
+    if (uri.startsWith("chant://spell/")) {
+      const name = uri.replace("chant://spell/", "");
+      const { spells } = await discoverSpells();
+      const spell = spells.get(name);
+      if (!spell) throw new Error(`Spell "${name}" not found`);
+      return {
+        contents: [{
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify({
+            ...spell.definition,
+            status: spell.status,
+            filePath: spell.filePath,
+          }, null, 2),
+        }],
+      };
+    }
+
+    // State resources: chant://state/{environment} and chant://state/{environment}/{lexicon}
+    if (uri.startsWith("chant://state/")) {
+      const parts = uri.replace("chant://state/", "").split("/");
+      const environment = parts[0];
+      const lexicon = parts[1];
+
+      if (lexicon) {
+        const content = await readSnapshot(environment, lexicon);
+        if (!content) throw new Error(`No snapshot found for ${environment}/${lexicon}`);
+        return {
+          contents: [{ uri, mimeType: "application/json", text: content }],
+        };
+      } else {
+        const snapshots = await readEnvironmentSnapshots(environment);
+        const result: Record<string, unknown> = {};
+        for (const [lex, content] of snapshots) {
+          result[lex] = JSON.parse(content);
+        }
+        return {
+          contents: [{ uri, mimeType: "application/json", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+    }
+
     if (uri.startsWith("chant://examples/")) {
       // Look up example in plugin resources
       const name = uri.replace("chant://examples/", "");

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/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.ts

@@ -46,6 +46,8 @@ export interface DocsConfig {
   basePath?: string;
   /** Root directory for resolving {{file:...}} markers in extra page content */
   examplesDir?: string;
+  /** Extra sidebar entries appended after extraPages (supports Starlight groups) */
+  sidebarExtra?: Array<Record<string, unknown>>;
 }
 
 export interface DocsResult {
@@ -285,8 +287,12 @@ export function writeDocsSite(config: DocsConfig, result: DocsResult): void {
   const outDir = config.outDir;
   const contentDir = join(outDir, "src", "content", "docs");
 
-  // Clear stale content and Astro caches so changes are picked up on next build
-  rmSync(contentDir, { recursive: true, force: true });
+  // Clear stale generated content and Astro caches so changes are picked up on next build.
+  // Only remove files that will be regenerated — preserve hand-written pages.
+  for (const filename of result.pages.keys()) {
+    const filePath = join(contentDir, filename);
+    rmSync(filePath, { force: true });
+  }
   rmSync(join(outDir, ".astro"), { recursive: true, force: true });
   rmSync(join(outDir, "node_modules", ".astro"), { recursive: true, force: true });
 
@@ -411,6 +417,11 @@ function buildSidebar(
     items.push({ label: "Serialization", slug: "serialization" });
   }
 
+  // Append raw sidebar entries (supports groups and nested items)
+  if (config.sidebarExtra) {
+    items.push(...config.sidebarExtra);
+  }
+
   return items;
 }
 

package/src/composite.test.ts

@@ -116,7 +116,7 @@ describe("Composite", () => {
     });
 
     const instance = MyComp({});
-    const roleProps = instance.members.role.props as Record<string, unknown>;
+    const roleProps = (instance.members.role as MockResource).props;
     expect(roleProps.bucketArn).toBeInstanceOf(AttrRef);
     // The AttrRef's parent should be the bucket instance
     expect((roleProps.bucketArn as AttrRef).attribute).toBe("Arn");

package/src/config.ts

@@ -9,6 +9,7 @@ import type { LintConfig } from "./lint/config";
 export const ChantConfigSchema = z.object({
   runtime: z.enum(["bun", "node"]).optional(),
   lexicons: z.array(z.string().min(1)).optional(),
+  environments: z.array(z.string().min(1)).optional(),
   lint: z.record(z.string(), z.unknown()).optional(),
 }).passthrough();
 
@@ -24,6 +25,9 @@ export interface ChantConfig {
   /** Lexicon package names to load (e.g. ["aws"]) */
   lexicons?: string[];
 
+  /** Environment names (e.g. ["staging", "prod"]) */
+  environments?: string[];
+
   /** Lint configuration (rules, extends, overrides, plugins) */
   lint?: LintConfig;
 }

package/src/declarable.test.ts

@@ -12,7 +12,8 @@ describe("DECLARABLE_MARKER", () => {
   });
 
   test("uses Symbol.for for global registry", () => {
-    expect(DECLARABLE_MARKER).toBe(Symbol.for("chant.declarable"));
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(DECLARABLE_MARKER).toBe(Symbol.for("chant.declarable") as any);
   });
 });
 

package/src/declarable.ts

@@ -9,7 +9,7 @@ export const DECLARABLE_MARKER = Symbol.for("chant.declarable");
 export interface Declarable {
   readonly lexicon: string;
   readonly entityType: string;
-  readonly kind?: "resource" | "property";
+  readonly kind?: "resource" | "property" | "output";
   readonly [DECLARABLE_MARKER]: true;
 }