@intentius/chant 0.0.16 → 0.0.22

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

package/src/spell/types.ts

@@ -0,0 +1,89 @@
+/**
+ * Spell types and factory functions.
+ *
+ * A spell is a structured task definition for agent orchestration.
+ */
+
+// ── Types ────────────────────────────────────────────────────────
+
+export interface ContextItem {
+  type: "file" | "cmd";
+  value: string;
+}
+
+export interface Task {
+  description: string;
+  done: boolean;
+}
+
+export type Status = "blocked" | "ready" | "done";
+
+export interface SpellDefinition {
+  name: string;
+  lexicon?: string;
+  overview: string;
+  context?: (string | ContextItem)[];
+  tasks: Task[];
+  depends?: string[];
+  afterAll?: string[];
+}
+
+// ── Validation ───────────────────────────────────────────────────
+
+const NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const MAX_NAME_LENGTH = 64;
+const RESERVED_NAMES = new Set([
+  "add", "list", "show", "cast", "done", "rm", "graph",
+]);
+
+function validateName(name: string): void {
+  if (!name) {
+    throw new Error("Spell name must not be empty");
+  }
+  if (name.length > MAX_NAME_LENGTH) {
+    throw new Error(`Spell name must be at most ${MAX_NAME_LENGTH} characters: "${name}"`);
+  }
+  if (!NAME_PATTERN.test(name)) {
+    throw new Error(`Spell name must be kebab-case (lowercase letters, numbers, hyphens): "${name}"`);
+  }
+  if (RESERVED_NAMES.has(name)) {
+    throw new Error(`Spell name "${name}" is reserved (conflicts with CLI subcommand)`);
+  }
+}
+
+// ── Factory functions ────────────────────────────────────────────
+
+/**
+ * Define a spell. Validates the name and freezes the object.
+ */
+export function spell(def: SpellDefinition): SpellDefinition {
+  validateName(def.name);
+  if (!def.overview) {
+    throw new Error(`Spell "${def.name}" must have a non-empty overview`);
+  }
+  if (!def.tasks || def.tasks.length === 0) {
+    throw new Error(`Spell "${def.name}" must have at least one task`);
+  }
+  return Object.freeze({ ...def });
+}
+
+/**
+ * Define a task within a spell.
+ */
+export function task(description: string, opts?: { done?: boolean }): Task {
+  return { description, done: opts?.done ?? false };
+}
+
+/**
+ * File context item — contents inlined at cast time.
+ */
+export function file(path: string): ContextItem {
+  return { type: "file", value: path };
+}
+
+/**
+ * Command context item — stdout inlined at cast time.
+ */
+export function cmd(command: string): ContextItem {
+  return { type: "cmd", value: command };
+}

package/src/state/digest.ts

@@ -0,0 +1,88 @@
+/**
+ * Build digest: fingerprints of resource declarations + dependency graph.
+ *
+ * The digest captures *what was declared* at a point in time, enabling
+ * diff operations without re-parsing templates.
+ */
+import type { BuildResult } from "../build";
+import type { Declarable } from "../declarable";
+import type { BuildDigest, ResourceDigest, DigestDiff } from "./types";
+import { sortedJsonReplacer } from "../utils";
+import { getRuntime } from "../runtime-adapter";
+
+/**
+ * Hash an entity's props deterministically.
+ */
+export function hashProps(props: unknown): string {
+  const json = JSON.stringify(props, sortedJsonReplacer);
+  return getRuntime().hash(json);
+}
+
+/**
+ * Compute a full build digest from a BuildResult.
+ */
+export function computeBuildDigest(buildResult: BuildResult): BuildDigest {
+  const resources: Record<string, ResourceDigest> = {};
+
+  for (const [name, entity] of buildResult.entities) {
+    const props = "props" in entity && entity.props != null ? entity.props : {};
+    resources[name] = {
+      type: entity.entityType,
+      lexicon: entity.lexicon,
+      propsHash: hashProps(props),
+    };
+  }
+
+  // Convert dependency Map<string, Set<string>> to Record<string, string[]>
+  const dependencies: Record<string, string[]> = {};
+  for (const [name, deps] of buildResult.dependencies) {
+    dependencies[name] = Array.from(deps);
+  }
+
+  return {
+    resources,
+    dependencies,
+    outputs: buildResult.manifest.outputs,
+    deployOrder: buildResult.manifest.deployOrder,
+  };
+}
+
+/**
+ * Compare two digests and categorize resources.
+ */
+export function diffDigests(
+  current: BuildDigest,
+  previous: BuildDigest | undefined,
+): DigestDiff {
+  const added: string[] = [];
+  const removed: string[] = [];
+  const changed: string[] = [];
+  const unchanged: string[] = [];
+
+  if (!previous) {
+    // No previous digest — everything is added
+    added.push(...Object.keys(current.resources));
+    return { added, removed, changed, unchanged };
+  }
+
+  // Check current resources against previous
+  for (const name of Object.keys(current.resources)) {
+    const prev = previous.resources[name];
+    if (!prev) {
+      added.push(name);
+    } else if (current.resources[name].propsHash !== prev.propsHash) {
+      changed.push(name);
+    } else {
+      unchanged.push(name);
+    }
+  }
+
+  // Check for removed resources
+  for (const name of Object.keys(previous.resources)) {
+    if (!(name in current.resources)) {
+      removed.push(name);
+    }
+  }
+
+  return { added, removed, changed, unchanged };
+}