@intentius/chant 0.0.18 → 0.0.24

package/src/cli/handlers/state.ts

@@ -0,0 +1,230 @@
+import { resolve } from "node:path";
+import { build } from "../../build";
+import { takeSnapshot } from "../../state/snapshot";
+import { readSnapshot, readEnvironmentSnapshots, listSnapshots, fetchState } from "../../state/git";
+import { computeBuildDigest, diffDigests } from "../../state/digest";
+import { loadChantConfig } from "../../config";
+import { formatError, formatWarning, formatSuccess, formatBold } from "../format";
+import type { CommandContext } from "../registry";
+import type { StateSnapshot } from "../../state/types";
+
+/**
+ * chant state snapshot <environment> [lexicon]
+ */
+export async function runStateSnapshot(ctx: CommandContext): Promise<number> {
+  const { args, plugins } = ctx;
+  const environment = args.extraPositional;
+  const lexiconFilter = args.extraPositional2;
+
+  if (!environment) {
+    console.error(formatError({ message: "Environment is required: chant state snapshot <environment> [lexicon]" }));
+    return 1;
+  }
+
+  // Validate environment against config
+  const projectPath = resolve(".");
+  const { config } = await loadChantConfig(projectPath);
+  if (config.environments && !config.environments.includes(environment)) {
+    console.error(formatError({
+      message: `Unknown environment "${environment}"`,
+      hint: `Defined environments: ${config.environments.join(", ")}`,
+    }));
+    return 1;
+  }
+
+  // Filter plugins if lexicon specified
+  const targetPlugins = lexiconFilter
+    ? plugins.filter((p) => p.name === lexiconFilter)
+    : plugins;
+  const targetSerializers = targetPlugins.map((p) => p.serializer);
+
+  // Build first to get entity names and build output
+  const buildResult = await build(projectPath, targetSerializers);
+  if (buildResult.errors.length > 0) {
+    console.error(formatError({ message: "Build failed — fix errors before taking a snapshot" }));
+    return 1;
+  }
+
+  const pluginsWithDescribe = targetPlugins.filter((p) => p.describeResources);
+  if (pluginsWithDescribe.length === 0) {
+    console.error(formatError({
+      message: "No plugins implement describeResources",
+      hint: lexiconFilter ? `Lexicon "${lexiconFilter}" does not support state snapshots` : undefined,
+    }));
+    return 1;
+  }
+
+  const result = await takeSnapshot(environment, pluginsWithDescribe, buildResult);
+
+  for (const w of result.warnings) {
+    console.error(formatWarning({ message: w }));
+  }
+  for (const e of result.errors) {
+    console.error(formatError({ message: e }));
+  }
+
+  if (result.snapshots.length > 0) {
+    const counts = result.snapshots
+      .map((s) => `${s.lexicon}(${Object.keys(s.resources).length})`)
+      .join(" ");
+    console.error(formatSuccess(`Snapshot saved to chant/state (${counts})`));
+  }
+
+  return result.errors.length > 0 && result.snapshots.length === 0 ? 1 : 0;
+}
+
+/**
+ * chant state show <environment> [lexicon]
+ */
+export async function runStateShow(ctx: CommandContext): Promise<number> {
+  const environment = ctx.args.extraPositional;
+  const lexiconFilter = ctx.args.extraPositional2;
+
+  if (!environment) {
+    console.error(formatError({ message: "Environment is required: chant state show <environment> [lexicon]" }));
+    return 1;
+  }
+
+  // Fetch from remote first
+  await fetchState();
+
+  if (lexiconFilter) {
+    const content = await readSnapshot(environment, lexiconFilter);
+    if (!content) {
+      console.error(formatError({ message: `No snapshot found for ${environment}/${lexiconFilter}` }));
+      return 1;
+    }
+
+    const snapshot: StateSnapshot = JSON.parse(content);
+    printSnapshotTable(snapshot);
+  } else {
+    const snapshots = await readEnvironmentSnapshots(environment);
+    if (snapshots.size === 0) {
+      console.error(formatError({ message: `No snapshots found for environment "${environment}"` }));
+      return 1;
+    }
+
+    for (const [lexicon, content] of snapshots) {
+      const snapshot: StateSnapshot = JSON.parse(content);
+      console.log(`\n${formatBold(`${environment}/${lexicon}`)} — ${Object.keys(snapshot.resources).length} resources — ${snapshot.timestamp}`);
+      printSnapshotTable(snapshot);
+    }
+  }
+
+  return 0;
+}
+
+/**
+ * chant state diff <environment> [lexicon]
+ */
+export async function runStateDiff(ctx: CommandContext): Promise<number> {
+  const { args, plugins, serializers } = ctx;
+  const environment = args.extraPositional;
+  const lexiconFilter = args.extraPositional2;
+
+  if (!environment) {
+    console.error(formatError({ message: "Environment is required: chant state diff <environment> [lexicon]" }));
+    return 1;
+  }
+
+  // Filter serializers to target lexicon before building
+  const targetSerializers = lexiconFilter
+    ? plugins.filter((p) => p.name === lexiconFilter).map((p) => p.serializer)
+    : serializers;
+
+  // Build to get current digest
+  const projectPath = resolve(".");
+  const buildResult = await build(projectPath, targetSerializers);
+  if (buildResult.errors.length > 0) {
+    console.error(formatError({ message: "Build failed — fix errors before diffing" }));
+    return 1;
+  }
+
+  const currentDigest = computeBuildDigest(buildResult);
+
+  // Fetch and read previous snapshot
+  await fetchState();
+
+  const lexicons = lexiconFilter
+    ? [lexiconFilter]
+    : Array.from(buildResult.manifest.lexicons);
+
+  for (const lexicon of lexicons) {
+    const content = await readSnapshot(environment, lexicon);
+    let previousDigest = undefined;
+    if (content) {
+      const snapshot: StateSnapshot = JSON.parse(content);
+      previousDigest = snapshot.digest;
+    }
+
+    const diff = diffDigests(currentDigest, previousDigest);
+
+    console.log(`\n${formatBold(lexicon)}`);
+    console.log("RESOURCE".padEnd(20) + "STATUS".padEnd(12) + "TYPE");
+    console.log("-".repeat(60));
+
+    for (const name of diff.added) {
+      console.log(name.padEnd(20) + "added".padEnd(12) + (currentDigest.resources[name]?.type ?? ""));
+    }
+    for (const name of diff.changed) {
+      console.log(name.padEnd(20) + "changed".padEnd(12) + (currentDigest.resources[name]?.type ?? ""));
+    }
+    for (const name of diff.removed) {
+      console.log(name.padEnd(20) + "removed".padEnd(12) + (previousDigest?.resources[name]?.type ?? ""));
+    }
+    for (const name of diff.unchanged) {
+      console.log(name.padEnd(20) + "unchanged".padEnd(12) + (currentDigest.resources[name]?.type ?? ""));
+    }
+  }
+
+  return 0;
+}
+
+/**
+ * chant state log [environment]
+ */
+export async function runStateLog(ctx: CommandContext): Promise<number> {
+  const environment = ctx.args.extraPositional;
+
+  await fetchState();
+
+  const entries = await listSnapshots({ environment });
+  if (entries.length === 0) {
+    console.error(formatError({ message: "No state snapshots found" }));
+    return 1;
+  }
+
+  for (const entry of entries) {
+    const date = entry.date.split("T")[0];
+    console.log(`${entry.commit.slice(0, 7)}  ${date}  ${entry.message}`);
+  }
+
+  return 0;
+}
+
+/**
+ * Fallback for unknown state subcommands.
+ */
+export async function runStateUnknown(ctx: CommandContext): Promise<number> {
+  console.error(formatError({
+    message: `Unknown state subcommand: ${ctx.args.extraPositional ?? ctx.args.path}`,
+    hint: "Available: chant state snapshot, chant state show, chant state diff, chant state log",
+  }));
+  return 1;
+}
+
+function printSnapshotTable(snapshot: StateSnapshot): void {
+  console.log("RESOURCE".padEnd(20) + "TYPE".padEnd(28) + "PHYSICAL ID".padEnd(44) + "STATUS");
+  console.log("-".repeat(100));
+
+  for (const [name, meta] of Object.entries(snapshot.resources)) {
+    const physicalId = meta.physicalId ?? "";
+    const truncId = physicalId.length > 40 ? physicalId.slice(0, 37) + "..." : physicalId;
+    console.log(
+      name.padEnd(20) +
+      meta.type.padEnd(28) +
+      truncId.padEnd(44) +
+      meta.status
+    );
+  }
+}

package/src/cli/lsp/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,
   };
 }

package/src/cli/main.ts

@@ -12,6 +12,8 @@ import { runDevGenerate, runDevPublish, runDevOnboard, runDevCheckLexicon, runDe
 import { runServeLsp, runServeMcp, runServeUnknown } from "./handlers/serve";
 import { runInit, runInitLexicon } from "./handlers/init";
 import { runList, runImport, runUpdate, runDoctor } from "./handlers/misc";
+import { runStateSnapshot, runStateShow, runStateDiff, runStateLog, runStateUnknown } from "./handlers/state";
+import { runSpellAdd, runSpellRm, runSpellList, runSpellShow, runSpellCast, runSpellDone, runGraph, runSpellUnknown } from "./handlers/spell";
 
 /**
  * Parse command line arguments
@@ -91,6 +93,21 @@ Commands:
   list                  List discovered entities
   import                Import external template into TypeScript
 
+Spells:
+  spell add <name>      Create a new spell
+  spell rm <name>       Remove a spell
+  spell list            List all spells with status
+  spell show <name>     Show spell details
+  spell cast <name>     Generate bootstrap prompt for agent
+  spell done <name> <N> Mark task N as done
+  graph                 Show spell dependency graph
+
+State:
+  state snapshot <env>  Query API, save metadata to orphan branch
+  state show <env>      Show latest state snapshot
+  state diff <env>      Compare current build against last snapshot
+  state log [env]       History of state snapshots
+
 Lexicon development:
   dev generate          Generate lexicon artifacts (+ validate + coverage)
   dev publish           Package lexicon for distribution
@@ -177,11 +194,28 @@ const registry: CommandDef[] = [
   { name: "dev onboard", handler: runDevOnboard },
   { name: "dev check-lexicon", handler: runDevCheckLexicon },
 
+  // Spell subcommands
+  { name: "spell add", handler: runSpellAdd },
+  { name: "spell rm", handler: runSpellRm },
+  { name: "spell list", handler: runSpellList },
+  { name: "spell show", handler: runSpellShow },
+  { name: "spell cast", handler: runSpellCast },
+  { name: "spell done", handler: runSpellDone },
+  { name: "graph", handler: runGraph },
+
+  // State subcommands
+  { name: "state snapshot", requiresPlugins: true, handler: runStateSnapshot },
+  { name: "state show", handler: runStateShow },
+  { name: "state diff", requiresPlugins: true, handler: runStateDiff },
+  { name: "state log", handler: runStateLog },
+
   // Serve subcommands
   { name: "serve lsp", requiresPlugins: true, handler: runServeLsp },
   { name: "serve mcp", requiresPlugins: true, handler: runServeMcp },
 
   // Fallback for unknown subcommands (must come after compound entries)
+  { name: "spell", handler: runSpellUnknown },
+  { name: "state", handler: runStateUnknown },
   { name: "dev", handler: runDevUnknown },
   { name: "serve", handler: runServeUnknown },
 ];
@@ -216,9 +250,9 @@ async function main(): Promise<void> {
     process.exit(1);
   }
 
-  // For compound commands (e.g. "dev generate"), args.path is the subcommand,
-  // so the project path shifts to extraPositional. For simple commands, use args.path.
-  const projectPath = match.compound ? (args.extraPositional ?? ".") : args.path;
+  // For compound commands (e.g. "spell cast"), args.path is the subcommand,
+  // so always use "." as the project path. For simple commands, use args.path.
+  const projectPath = match.compound ? (args.extraPositional || ".") : args.path;
   const plugins = match.def.requiresPlugins
     ? await loadPluginsOrExit(projectPath)
     : [];

package/src/cli/mcp/resource-handlers.ts

@@ -0,0 +1,227 @@
+import type { ResourceDefinition } from "./types";
+import { getContext } from "./resources/context";
+import { readSnapshot, readEnvironmentSnapshots } from "../../state/git";
+import { discoverSpells } from "../../spell/discovery";
+import { generatePrompt } from "../../spell/prompt";
+import { getRuntime } from "../../runtime-adapter";
+
+type PluginResourceEntry = { definition: ResourceDefinition; handler: () => Promise<string> };
+
+/**
+ * Core resource definitions (always present regardless of plugins)
+ */
+export const coreResourceDefinitions: 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",
+  },
+  {
+    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",
+  },
+];
+
+/**
+ * Build the full resources list merging core + plugin resources
+ */
+export function buildResourcesList(
+  pluginResources: Map<string, PluginResourceEntry>,
+): { resources: ResourceDefinition[] } {
+  const resources = [...coreResourceDefinitions];
+  for (const { definition } of pluginResources.values()) {
+    resources.push(definition);
+  }
+  return { resources };
+}
+
+/**
+ * Collect example resources from plugins whose URI contains "examples/"
+ */
+export function collectExamples(
+  pluginResources: Map<string, PluginResourceEntry>,
+): Array<{ name: string; description: string }> {
+  const examples: Array<{ name: string; description: string }> = [];
+  for (const [uri, { definition }] of 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
+ */
+export async function handleResourcesRead(
+  params: Record<string, unknown>,
+  pluginResources: Map<string, PluginResourceEntry>,
+): 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(collectExamples(pluginResources)),
+        },
+      ],
+    };
+  }
+
+  // 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/", "");
+    for (const [pluginUri, pluginResource] of 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 = 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}`);
+}

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);
     });
   });
 });