@intentius/chant 0.0.18 → 0.0.22

package/src/discovery/import.test.ts

@@ -28,8 +28,8 @@ describe("importModule", () => {
 
       const module = await importModule(filePath);
       expect(module.default).toBeDefined();
-      expect(module.default.name).toBe("test");
-      expect(module.default.value).toBe(123);
+      expect((module.default as any).name).toBe("test");
+      expect((module.default as any).value).toBe(123);
     });
   });
 
@@ -125,7 +125,7 @@ describe("importModule", () => {
 
       const module = await importModule(filePath);
       expect(module.MyClass).toBeDefined();
-      const instance = new module.MyClass(100);
+      const instance = new (module.MyClass as any)(100);
       expect(instance.getValue()).toBe(100);
     });
   });
@@ -142,8 +142,8 @@ describe("importModule", () => {
       const module = await importModule(filePath);
       expect(module.add).toBeInstanceOf(Function);
       expect(module.multiply).toBeInstanceOf(Function);
-      expect(module.add(2, 3)).toBe(5);
-      expect(module.multiply(4, 5)).toBe(20);
+      expect((module.add as Function)(2, 3)).toBe(5);
+      expect((module.multiply as Function)(4, 5)).toBe(20);
     });
   });
 

package/src/discovery/resolve.test.ts

@@ -8,11 +8,13 @@ import { LOGICAL_NAME_SYMBOL, getLogicalName } from "../utils";
 describe("resolveAttrRefs", () => {
   test("sets logical names on all entities", () => {
     const entity1: Declarable = {
+      lexicon: "test",
       entityType: "Test1",
       [DECLARABLE_MARKER]: true,
     };
 
     const entity2: Declarable = {
+      lexicon: "test",
       entityType: "Test2",
       [DECLARABLE_MARKER]: true,
     };
@@ -30,11 +32,13 @@ describe("resolveAttrRefs", () => {
 
   test("resolves AttrRef with parent in entities collection", () => {
     const parent: Declarable = {
+      lexicon: "test",
       entityType: "Parent",
       [DECLARABLE_MARKER]: true,
     };
 
     const child: Declarable & { ref: AttrRef } = {
+      lexicon: "test",
       entityType: "Child",
       [DECLARABLE_MARKER]: true,
       ref: new AttrRef(parent, "Arn"),
@@ -55,11 +59,13 @@ describe("resolveAttrRefs", () => {
 
   test("resolves multiple AttrRefs on same entity", () => {
     const parent: Declarable = {
+      lexicon: "test",
       entityType: "Parent",
       [DECLARABLE_MARKER]: true,
     };
 
     const child: Declarable & { arn: AttrRef; name: AttrRef } = {
+      lexicon: "test",
       entityType: "Child",
       [DECLARABLE_MARKER]: true,
       arn: new AttrRef(parent, "Arn"),
@@ -83,16 +89,19 @@ describe("resolveAttrRefs", () => {
 
   test("resolves AttrRefs with different parents", () => {
     const parent1: Declarable = {
+      lexicon: "test",
       entityType: "Parent1",
       [DECLARABLE_MARKER]: true,
     };
 
     const parent2: Declarable = {
+      lexicon: "test",
       entityType: "Parent2",
       [DECLARABLE_MARKER]: true,
     };
 
     const child: Declarable & { ref1: AttrRef; ref2: AttrRef } = {
+      lexicon: "test",
       entityType: "Child",
       [DECLARABLE_MARKER]: true,
       ref1: new AttrRef(parent1, "Arn"),
@@ -119,6 +128,7 @@ describe("resolveAttrRefs", () => {
     const parent = {}; // Not a Declarable, not in entities
 
     const child: Declarable & { ref: AttrRef } = {
+      lexicon: "test",
       entityType: "Child",
       [DECLARABLE_MARKER]: true,
       ref: new AttrRef(parent, "Arn"),
@@ -133,11 +143,13 @@ describe("resolveAttrRefs", () => {
 
   test("handles entities with no AttrRefs", () => {
     const entity1: Declarable = {
+      lexicon: "test",
       entityType: "Test1",
       [DECLARABLE_MARKER]: true,
     };
 
     const entity2: Declarable & { prop: string } = {
+      lexicon: "test",
       entityType: "Test2",
       [DECLARABLE_MARKER]: true,
       prop: "value",
@@ -162,17 +174,20 @@ describe("resolveAttrRefs", () => {
 
   test("resolves chain of entities with AttrRefs", () => {
     const root: Declarable = {
+      lexicon: "test",
       entityType: "Root",
       [DECLARABLE_MARKER]: true,
     };
 
     const middle: Declarable & { rootRef: AttrRef } = {
+      lexicon: "test",
       entityType: "Middle",
       [DECLARABLE_MARKER]: true,
       rootRef: new AttrRef(root, "Id"),
     };
 
     const leaf: Declarable & { middleRef: AttrRef } = {
+      lexicon: "test",
       entityType: "Leaf",
       [DECLARABLE_MARKER]: true,
       middleRef: new AttrRef(middle, "Name"),
@@ -196,6 +211,7 @@ describe("resolveAttrRefs", () => {
 
   test("handles entity referencing itself", () => {
     const entity: Declarable & { selfRef: AttrRef } = {
+      lexicon: "test",
       entityType: "SelfReferencing",
       [DECLARABLE_MARKER]: true,
       selfRef: null as unknown as AttrRef, // Will be set below
@@ -214,6 +230,7 @@ describe("resolveAttrRefs", () => {
 
   test("preserves logical name symbol on entities", () => {
     const entity: Declarable = {
+      lexicon: "test",
       entityType: "Test",
       [DECLARABLE_MARKER]: true,
     };
@@ -228,6 +245,7 @@ describe("resolveAttrRefs", () => {
 
   test("uses export name as logical name", () => {
     const entity: Declarable = {
+      lexicon: "test",
       entityType: "Test",
       [DECLARABLE_MARKER]: true,
     };
@@ -243,11 +261,13 @@ describe("resolveAttrRefs", () => {
 
   test("handles complex attribute names in AttrRef", () => {
     const parent: Declarable = {
+      lexicon: "test",
       entityType: "Parent",
       [DECLARABLE_MARKER]: true,
     };
 
     const child: Declarable & { ref: AttrRef } = {
+      lexicon: "test",
       entityType: "Child",
       [DECLARABLE_MARKER]: true,
       ref: new AttrRef(parent, "Outputs.WebsiteURL"),

package/src/discovery/resolve.ts

@@ -1,6 +1,6 @@
 import type { Declarable } from "../declarable";
 import { AttrRef } from "../attrref";
-import { LOGICAL_NAME_SYMBOL, getAttributes } from "../utils";
+import { LOGICAL_NAME_SYMBOL, getAttributes, isAttrRefLike } from "../utils";
 
 /**
  * Resolves all AttrRef instances in a collection of entities
@@ -22,7 +22,7 @@ export function resolveAttrRefs(entities: Map<string, Declarable>): void {
     for (const attrName of attributes) {
       const attrRef = (entity as unknown as Record<string, unknown>)[attrName];
 
-      if (attrRef instanceof AttrRef) {
+      if (isAttrRefLike(attrRef)) {
         const parent = attrRef.parent.deref();
 
         if (!parent) {

package/src/index.ts

@@ -59,3 +59,5 @@ export * from "./child-project";
 export * from "./lsp/types";
 export * from "./lsp/lexicon-providers";
 export * from "./mcp/types";
+export * from "./state/index";
+export * from "./spell/index";

package/src/lexicon.ts

@@ -193,6 +193,30 @@ export interface LexiconPlugin {
 
   /** Return MCP resource contributions */
   mcpResources?(): McpResourceContribution[];
+
+  // State
+  /** Query deployed resources and return API metadata. Opt-in. */
+  describeResources?(options: {
+    environment: string;
+    buildOutput: string;
+    entityNames: string[];
+  }): Promise<Record<string, ResourceMetadata>>;
+}
+
+/**
+ * Metadata about a deployed resource, returned by describeResources.
+ */
+export interface ResourceMetadata {
+  /** Entity type (e.g. AWS::S3::Bucket, K8s::Apps::Deployment) */
+  type: string;
+  /** Provider-assigned physical ID (ARN, resource ID, pod name) */
+  physicalId?: string;
+  /** Provider-specific status string */
+  status: string;
+  /** ISO timestamp of last update */
+  lastUpdated?: string;
+  /** Cloud-assigned output properties */
+  attributes?: Record<string, unknown>;
 }
 
 /**

package/src/lint/rule-options.test.ts

@@ -2,7 +2,7 @@ import { describe, test, expect, beforeEach, afterEach } from "bun:test";
 import { parseRuleConfig, loadConfig } from "./config";
 import { fileDeclarableLimitRule } from "./rules/file-declarable-limit";
 import * as ts from "typescript";
-import type { LintContext } from "./rule";
+import type { LintContext, RuleConfig } from "./rule";
 import { writeFileSync, mkdirSync, rmSync } from "fs";
 import { join } from "path";
 
@@ -37,12 +37,12 @@ describe("parseRuleConfig", () => {
   });
 
   test("parses [severity, options] tuple", () => {
-    const result = parseRuleConfig(["warning", { max: 12 }]);
+    const result = parseRuleConfig(["warning" as const, { max: 12 }]);
     expect(result).toEqual({ severity: "warning", options: { max: 12 } });
   });
 
   test("throws for invalid tuple length", () => {
-    expect(() => parseRuleConfig([] as unknown as [string, Record<string, unknown>])).toThrow(
+    expect(() => parseRuleConfig([] as unknown as RuleConfig)).toThrow(
       /expected a severity string or \[severity, options\] tuple/
     );
   });

package/src/lint/rule-registry.test.ts

@@ -88,7 +88,7 @@ describe("buildRuleRegistry", () => {
 
   test("falls back to rule ID when description is missing", () => {
     const rule = mockRule("COR001");
-    delete (rule as Record<string, unknown>).description;
+    delete (rule as unknown as Record<string, unknown>).description;
 
     const entries = buildRuleRegistry([rule]);
     expect(entries[0].description).toBe("COR001");

package/src/lint/rules/composite-scope.ts

@@ -14,7 +14,7 @@ export function isInsideCompositeFactory(node: ts.Node): boolean {
 
   while (current) {
     if (ts.isArrowFunction(current) || ts.isFunctionExpression(current)) {
-      const parent = current.parent;
+      const parent: ts.Node | undefined = current.parent;
       if (parent && ts.isCallExpression(parent) && parent.arguments[0] === current) {
         const callee = parent.expression;
         if (isCompositeCallee(callee)) {

package/src/serializer-walker.ts

@@ -9,6 +9,7 @@ import type { Declarable } from "./declarable";
 import { isPropertyDeclarable } from "./declarable";
 import { INTRINSIC_MARKER } from "./intrinsic";
 import { AttrRef } from "./attrref";
+import { isAttrRefLike } from "./utils";
 
 export interface SerializerVisitor {
   /** Format an attribute reference (e.g. CFN Fn::GetAttr). */
@@ -33,7 +34,7 @@ export function walkValue(
   }
 
   // Handle AttrRef
-  if (value instanceof AttrRef) {
+  if (isAttrRefLike(value)) {
     const name = value.getLogicalName();
     if (!name) {
       throw new Error(

package/src/spell/discovery.ts

@@ -0,0 +1,183 @@
+/**
+ * Spell discovery: find, import, validate, and index spell files.
+ */
+import { getRuntime } from "../runtime-adapter";
+import type { SpellDefinition, Status } from "./types";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+export interface DiscoveredSpell {
+  definition: SpellDefinition;
+  filePath: string;
+  status: Status;
+}
+
+export interface SpellDiscoveryResult {
+  spells: Map<string, DiscoveredSpell>;
+  errors: string[];
+}
+
+/**
+ * Find the git root directory.
+ */
+async function findGitRoot(cwd?: string): Promise<string> {
+  const rt = getRuntime();
+  const result = await rt.spawn(["git", "rev-parse", "--show-toplevel"], { cwd });
+  if (result.exitCode !== 0) {
+    throw new Error("Not in a git repository");
+  }
+  return result.stdout.trim();
+}
+
+/**
+ * Discover all spells from the spells/ directory at the git root.
+ */
+export async function discoverSpells(
+  opts?: { cwd?: string },
+): Promise<SpellDiscoveryResult> {
+  const errors: string[] = [];
+  const spells = new Map<string, DiscoveredSpell>();
+
+  const gitRoot = await findGitRoot(opts?.cwd);
+  const spellsDir = join(gitRoot, "spells");
+
+  // List *.spell.ts files
+  let files: string[];
+  try {
+    const entries = await readdir(spellsDir);
+    files = entries.filter((f) => f.endsWith(".spell.ts")).map((f) => join(spellsDir, f));
+  } catch {
+    // spells/ directory doesn't exist — that's OK
+    return { spells, errors };
+  }
+
+  // Import each file
+  const fileMap = new Map<string, string>(); // name → filePath for duplicate detection
+  for (const filePath of files) {
+    try {
+      const mod = await import(filePath);
+      const def = mod.default as SpellDefinition | undefined;
+
+      if (!def) {
+        errors.push(`File ${filePath} has no default export`);
+        continue;
+      }
+
+      // Validate shape
+      if (!def.name || typeof def.name !== "string") {
+        errors.push(`File ${filePath}: default export has no valid name`);
+        continue;
+      }
+      if (!def.tasks || !Array.isArray(def.tasks)) {
+        errors.push(`File ${filePath}: default export has no valid tasks`);
+        continue;
+      }
+
+      // Duplicate check
+      if (fileMap.has(def.name)) {
+        errors.push(
+          `Duplicate name "${def.name}" in ${filePath} and ${fileMap.get(def.name)}`,
+        );
+        continue;
+      }
+
+      fileMap.set(def.name, filePath);
+      spells.set(def.name, {
+        definition: def,
+        filePath,
+        status: "ready", // placeholder — computed after all are loaded
+      });
+    } catch (err) {
+      errors.push(
+        `${filePath}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  // Validate dependencies
+  for (const [name, spell] of spells) {
+    const deps = spell.definition.depends;
+    if (!deps) continue;
+
+    for (const depName of deps) {
+      if (!spells.has(depName)) {
+        errors.push(
+          `Spell "${name}" depends on "${depName}" which does not exist`,
+        );
+      }
+    }
+  }
+
+  // Detect circular dependencies via topological sort
+  const circularError = detectCycles(spells);
+  if (circularError) {
+    errors.push(circularError);
+  }
+
+  // Compute status for each spell
+  computeStatuses(spells);
+
+  return { spells, errors };
+}
+
+/**
+ * Detect circular dependencies. Returns an error message or null.
+ */
+function detectCycles(spells: Map<string, DiscoveredSpell>): string | null {
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+
+  function visit(name: string, path: string[]): string | null {
+    if (visiting.has(name)) {
+      const cycle = [...path.slice(path.indexOf(name)), name];
+      return `Circular dependency: ${cycle.join(" → ")}`;
+    }
+    if (visited.has(name)) return null;
+
+    visiting.add(name);
+    path.push(name);
+
+    const spell = spells.get(name);
+    if (spell?.definition.depends) {
+      for (const dep of spell.definition.depends) {
+        if (spells.has(dep)) {
+          const err = visit(dep, path);
+          if (err) return err;
+        }
+      }
+    }
+
+    visiting.delete(name);
+    visited.add(name);
+    path.pop();
+    return null;
+  }
+
+  for (const name of spells.keys()) {
+    const err = visit(name, []);
+    if (err) return err;
+  }
+  return null;
+}
+
+/**
+ * Compute statuses: blocked / ready / done.
+ */
+function computeStatuses(spells: Map<string, DiscoveredSpell>): void {
+  for (const [, spell] of spells) {
+    const allTasksDone = spell.definition.tasks.every((t) => t.done);
+    if (allTasksDone) {
+      spell.status = "done";
+      continue;
+    }
+
+    const deps = spell.definition.depends ?? [];
+    const hasIncompleteDep = deps.some((depName) => {
+      const dep = spells.get(depName);
+      if (!dep) return true; // dangling dep counts as incomplete
+      return !dep.definition.tasks.every((t) => t.done);
+    });
+
+    spell.status = hasIncompleteDep ? "blocked" : "ready";
+  }
+}

package/src/spell/index.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./discovery";
+export * from "./prompt";

package/src/spell/prompt.ts

@@ -0,0 +1,133 @@
+/**
+ * Bootstrap prompt generation for spells.
+ *
+ * Resolves context items (static strings, files, commands), assembles the
+ * full prompt with overview, context, task list, and afterAll instructions.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getRuntime } from "../runtime-adapter";
+import type { SpellDefinition, ContextItem, Task } from "./types";
+import type { LexiconPlugin } from "../lexicon";
+
+/**
+ * Resolve a single context item to a string.
+ */
+async function resolveContextItem(
+  item: string | ContextItem,
+  gitRoot: string,
+): Promise<string> {
+  if (typeof item === "string") return item;
+
+  if (item.type === "file") {
+    const filePath = join(gitRoot, item.value);
+    try {
+      const content = await readFile(filePath, "utf-8");
+      return `--- ${item.value} ---\n${content}`;
+    } catch {
+      return `[Context error: ${item.value} not found]`;
+    }
+  }
+
+  if (item.type === "cmd") {
+    const rt = getRuntime();
+    try {
+      const result = await rt.spawn(["sh", "-c", item.value], { cwd: gitRoot });
+      if (result.exitCode !== 0) {
+        return `[Context error: command "${item.value}" failed with exit code ${result.exitCode}]\n${result.stderr}`;
+      }
+      return `--- $ ${item.value} ---\n${result.stdout}`;
+    } catch (err) {
+      return `[Context error: command "${item.value}" failed: ${err instanceof Error ? err.message : String(err)}]`;
+    }
+  }
+
+  return String(item);
+}
+
+/**
+ * Format the task list for the prompt.
+ */
+function formatTasks(tasks: Task[]): string {
+  return tasks
+    .map((t, i) => {
+      const check = t.done ? "[x]" : "[ ]";
+      return `${i + 1}. ${check} ${t.description}`;
+    })
+    .join("\n");
+}
+
+/**
+ * Find relevant skill content from a lexicon plugin.
+ */
+function getLexiconSkillContent(
+  lexiconName: string,
+  plugins: LexiconPlugin[],
+): string | null {
+  const plugin = plugins.find((p) => p.name === lexiconName);
+  if (!plugin?.skills) return null;
+  const skills = plugin.skills();
+  if (skills.length === 0) return null;
+
+  return skills
+    .map((s) => `### ${s.name}\n\n${s.content}`)
+    .join("\n\n");
+}
+
+export interface PromptOptions {
+  gitRoot: string;
+  plugins?: LexiconPlugin[];
+}
+
+/**
+ * Generate the bootstrap prompt for a spell.
+ */
+export async function generatePrompt(
+  spell: SpellDefinition,
+  opts: PromptOptions,
+): Promise<string> {
+  const sections: string[] = [];
+
+  // Header
+  sections.push(`# Spell: ${spell.name}\n`);
+
+  // Overview
+  sections.push(`## Overview\n\n${spell.overview}\n`);
+
+  // Resolved context
+  if (spell.context && spell.context.length > 0) {
+    const resolved = await Promise.all(
+      spell.context.map((item) => resolveContextItem(item, opts.gitRoot)),
+    );
+    sections.push(`## Context\n\n${resolved.join("\n\n")}\n`);
+  }
+
+  // Lexicon skill guidance
+  if (spell.lexicon && opts.plugins) {
+    const skillContent = getLexiconSkillContent(spell.lexicon, opts.plugins);
+    if (skillContent) {
+      sections.push(`## ${spell.lexicon} Guidance\n\n${skillContent}\n`);
+    }
+  }
+
+  // Task list
+  sections.push(`## Tasks\n\n${formatTasks(spell.tasks)}\n`);
+
+  // After all
+  if (spell.afterAll && spell.afterAll.length > 0) {
+    sections.push(
+      `## After Completion\n\nAfter all tasks are done, run:\n${spell.afterAll.map((c) => `- \`${c}\``).join("\n")}\n`,
+    );
+  }
+
+  // Instructions
+  sections.push(
+    `## Instructions\n\n` +
+    `- Mark tasks done with: \`chant spell done ${spell.name} <task-number>\`\n` +
+    `- Task numbers are 1-based\n` +
+    `- Commit with trailer: \`Spell: ${spell.name}\`\n` +
+    `- Work through tasks in order\n`,
+  );
+
+  return sections.join("\n");
+}