@intentius/chant 0.0.18 → 0.0.22

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

package/src/state/git.ts

@@ -0,0 +1,317 @@
+/**
+ * Git plumbing operations for the chant/state orphan branch.
+ *
+ * All operations use git plumbing commands — no checkout, no branch switching,
+ * no working tree changes.
+ */
+import { getRuntime } from "../runtime-adapter";
+
+const STATE_BRANCH = "chant/state";
+
+/**
+ * Write a state snapshot JSON to the orphan branch.
+ *
+ * Pipeline: hash-object → mktree → commit-tree → update-ref
+ */
+export async function writeSnapshot(
+  environment: string,
+  lexicon: string,
+  json: string,
+  opts?: { cwd?: string },
+): Promise<string> {
+  const rt = getRuntime();
+  const cwd = opts?.cwd;
+
+  // 1. Write blob
+  const hashResult = await rt.spawn(
+    ["git", "hash-object", "-w", "--stdin"],
+    { cwd },
+  );
+  // hash-object reads from stdin, but spawn doesn't support piping directly.
+  // Use a shell pipeline instead.
+  const blobResult = await rt.spawn(
+    ["sh", "-c", `echo '${json.replace(/'/g, "'\\''")}' | git hash-object -w --stdin`],
+    { cwd },
+  );
+  if (blobResult.exitCode !== 0) {
+    throw new Error(`git hash-object failed: ${blobResult.stderr}`);
+  }
+  const blobSha = blobResult.stdout.trim();
+
+  // 2. Read existing tree (if branch exists) to preserve other env/lexicon entries
+  const existingTree = await readTree(cwd);
+
+  // 3. Build new tree entries
+  const path = `${environment}/${lexicon}.json`;
+  const entries = mergeTreeEntry(existingTree, path, blobSha);
+  const treeInput = entries.map((e) => `${e.mode} ${e.type} ${e.sha}\t${e.name}`).join("\n");
+
+  // mktree needs a nested tree structure. Build env subtree first, then root tree.
+  // Build env subtree
+  const envEntries = entries
+    .filter((e) => e.env === environment)
+    .map((e) => `${e.mode} ${e.type} ${e.sha}\t${e.name}`)
+    .join("\n");
+
+  const envTreeResult = await rt.spawn(
+    ["sh", "-c", `printf '%s\\n' ${shellQuoteLines(envEntries)} | git mktree`],
+    { cwd },
+  );
+  if (envTreeResult.exitCode !== 0) {
+    throw new Error(`git mktree (env) failed: ${envTreeResult.stderr}`);
+  }
+  const envTreeSha = envTreeResult.stdout.trim();
+
+  // Build root tree: collect env subtrees
+  const rootEntries: string[] = [];
+  const envsSeen = new Set<string>();
+  for (const e of entries) {
+    if (!envsSeen.has(e.env)) {
+      envsSeen.add(e.env);
+      if (e.env === environment) {
+        rootEntries.push(`040000 tree ${envTreeSha}\t${environment}`);
+      } else {
+        rootEntries.push(`040000 tree ${e.envTreeSha!}\t${e.env}`);
+      }
+    }
+  }
+
+  const rootTreeResult = await rt.spawn(
+    ["sh", "-c", `printf '%s\\n' ${shellQuoteLines(rootEntries.join("\n"))} | git mktree`],
+    { cwd },
+  );
+  if (rootTreeResult.exitCode !== 0) {
+    throw new Error(`git mktree (root) failed: ${rootTreeResult.stderr}`);
+  }
+  const rootTreeSha = rootTreeResult.stdout.trim();
+
+  // 4. Create commit
+  const parentRef = await getStateBranchTip(cwd);
+  const parentArgs = parentRef ? ["-p", parentRef] : [];
+  const commitResult = await rt.spawn(
+    ["git", "commit-tree", ...parentArgs, "-m", "State snapshot", rootTreeSha],
+    { cwd },
+  );
+  if (commitResult.exitCode !== 0) {
+    throw new Error(`git commit-tree failed: ${commitResult.stderr}`);
+  }
+  const commitSha = commitResult.stdout.trim();
+
+  // 5. Update ref
+  const updateResult = await rt.spawn(
+    ["git", "update-ref", `refs/heads/${STATE_BRANCH}`, commitSha],
+    { cwd },
+  );
+  if (updateResult.exitCode !== 0) {
+    throw new Error(`git update-ref failed: ${updateResult.stderr}`);
+  }
+
+  return commitSha;
+}
+
+/**
+ * Read a snapshot from the orphan branch.
+ */
+export async function readSnapshot(
+  environment: string,
+  lexicon: string,
+  opts?: { cwd?: string },
+): Promise<string | null> {
+  const rt = getRuntime();
+  const result = await rt.spawn(
+    ["git", "show", `${STATE_BRANCH}:${environment}/${lexicon}.json`],
+    { cwd: opts?.cwd },
+  );
+  if (result.exitCode !== 0) return null;
+  return result.stdout;
+}
+
+/**
+ * Read all snapshots for an environment (all lexicons).
+ */
+export async function readEnvironmentSnapshots(
+  environment: string,
+  opts?: { cwd?: string },
+): Promise<Map<string, string>> {
+  const rt = getRuntime();
+  const snapshots = new Map<string, string>();
+
+  // List files in the environment directory
+  const lsResult = await rt.spawn(
+    ["git", "ls-tree", "--name-only", `${STATE_BRANCH}:${environment}/`],
+    { cwd: opts?.cwd },
+  );
+  if (lsResult.exitCode !== 0) return snapshots;
+
+  const files = lsResult.stdout.trim().split("\n").filter(Boolean);
+  for (const file of files) {
+    if (file.endsWith(".json")) {
+      const lexicon = file.replace(/\.json$/, "");
+      const content = await readSnapshot(environment, lexicon, opts);
+      if (content) snapshots.set(lexicon, content);
+    }
+  }
+
+  return snapshots;
+}
+
+/**
+ * List snapshot history from the orphan branch.
+ */
+export async function listSnapshots(
+  opts?: { cwd?: string; environment?: string },
+): Promise<Array<{ commit: string; date: string; message: string }>> {
+  const rt = getRuntime();
+  const result = await rt.spawn(
+    ["git", "log", "--format=%H %aI %s", STATE_BRANCH],
+    { cwd: opts?.cwd },
+  );
+  if (result.exitCode !== 0) return [];
+
+  return result.stdout
+    .trim()
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      const [commit, date, ...rest] = line.split(" ");
+      return { commit, date, message: rest.join(" ") };
+    });
+}
+
+/**
+ * Push the state branch to remote.
+ */
+export async function pushState(opts?: { cwd?: string }): Promise<boolean> {
+  const rt = getRuntime();
+  // Check if remote exists
+  const remoteResult = await rt.spawn(["git", "remote"], { cwd: opts?.cwd });
+  if (remoteResult.exitCode !== 0 || !remoteResult.stdout.trim()) return false;
+
+  const remote = remoteResult.stdout.trim().split("\n")[0];
+  const pushResult = await rt.spawn(
+    ["git", "push", remote, `${STATE_BRANCH}:${STATE_BRANCH}`],
+    { cwd: opts?.cwd },
+  );
+  return pushResult.exitCode === 0;
+}
+
+/**
+ * Fetch the state branch from remote.
+ */
+export async function fetchState(opts?: { cwd?: string }): Promise<boolean> {
+  const rt = getRuntime();
+  const remoteResult = await rt.spawn(["git", "remote"], { cwd: opts?.cwd });
+  if (remoteResult.exitCode !== 0 || !remoteResult.stdout.trim()) return false;
+
+  const remote = remoteResult.stdout.trim().split("\n")[0];
+  const fetchResult = await rt.spawn(
+    ["git", "fetch", remote, `${STATE_BRANCH}:${STATE_BRANCH}`],
+    { cwd: opts?.cwd },
+  );
+  return fetchResult.exitCode === 0;
+}
+
+/**
+ * Get the current HEAD commit SHA of the main working branch.
+ */
+export async function getHeadCommit(opts?: { cwd?: string }): Promise<string> {
+  const rt = getRuntime();
+  const result = await rt.spawn(["git", "rev-parse", "HEAD"], { cwd: opts?.cwd });
+  if (result.exitCode !== 0) {
+    throw new Error(`git rev-parse HEAD failed: ${result.stderr}`);
+  }
+  return result.stdout.trim();
+}
+
+// ── Internal helpers ────────────────────────────────────────────
+
+interface TreeEntry {
+  mode: string;
+  type: string;
+  sha: string;
+  name: string;
+  env: string;
+  envTreeSha?: string;
+}
+
+async function getStateBranchTip(cwd?: string): Promise<string | null> {
+  const rt = getRuntime();
+  const result = await rt.spawn(
+    ["git", "rev-parse", "--verify", `refs/heads/${STATE_BRANCH}`],
+    { cwd },
+  );
+  if (result.exitCode !== 0) return null;
+  return result.stdout.trim();
+}
+
+async function readTree(cwd?: string): Promise<TreeEntry[]> {
+  const rt = getRuntime();
+  const tip = await getStateBranchTip(cwd);
+  if (!tip) return [];
+
+  // List root tree to get env directories
+  const rootResult = await rt.spawn(
+    ["git", "ls-tree", STATE_BRANCH],
+    { cwd },
+  );
+  if (rootResult.exitCode !== 0) return [];
+
+  const entries: TreeEntry[] = [];
+  const lines = rootResult.stdout.trim().split("\n").filter(Boolean);
+
+  for (const line of lines) {
+    // Format: mode type sha\tname
+    const match = line.match(/^(\d+)\s+(\w+)\s+([0-9a-f]+)\t(.+)$/);
+    if (!match) continue;
+    const [, mode, type, sha, name] = match;
+
+    if (type === "tree") {
+      // This is an env directory — list its contents
+      const envResult = await rt.spawn(
+        ["git", "ls-tree", `${STATE_BRANCH}:${name}/`],
+        { cwd },
+      );
+      if (envResult.exitCode !== 0) continue;
+
+      const envLines = envResult.stdout.trim().split("\n").filter(Boolean);
+      for (const envLine of envLines) {
+        const envMatch = envLine.match(/^(\d+)\s+(\w+)\s+([0-9a-f]+)\t(.+)$/);
+        if (!envMatch) continue;
+        entries.push({
+          mode: envMatch[1],
+          type: envMatch[2],
+          sha: envMatch[3],
+          name: envMatch[4],
+          env: name,
+          envTreeSha: sha,
+        });
+      }
+    }
+  }
+
+  return entries;
+}
+
+function mergeTreeEntry(
+  existing: TreeEntry[],
+  path: string,
+  blobSha: string,
+): TreeEntry[] {
+  const [env, filename] = path.split("/");
+  const entries = existing.filter(
+    (e) => !(e.env === env && e.name === filename),
+  );
+  entries.push({
+    mode: "100644",
+    type: "blob",
+    sha: blobSha,
+    name: filename,
+    env,
+  });
+  return entries;
+}
+
+function shellQuoteLines(input: string): string {
+  // Escape for printf in shell
+  return `'${input.replace(/'/g, "'\\''")}'`;
+}

package/src/state/index.ts

@@ -0,0 +1,4 @@
+export * from "./types";
+export * from "./git";
+export * from "./digest";
+export * from "./snapshot";

package/src/state/snapshot.ts

@@ -0,0 +1,179 @@
+/**
+ * Snapshot orchestration: queries plugins for deployed resource metadata,
+ * assembles StateSnapshots, computes build digests, and writes to git.
+ */
+import type { LexiconPlugin, ResourceMetadata } from "../lexicon";
+import type { BuildResult } from "../build";
+import type { SerializerResult } from "../serializer";
+import type { StateSnapshot } from "./types";
+import { computeBuildDigest } from "./digest";
+import { writeSnapshot, getHeadCommit, pushState } from "./git";
+import { sortedJsonReplacer } from "../utils";
+
+/** Patterns in attribute names that suggest sensitive data. */
+const SENSITIVE_PATTERNS = [
+  /password/i,
+  /secret/i,
+  /token/i,
+  /private.?key/i,
+  /credential/i,
+  /connection.?string/i,
+];
+
+/**
+ * Check for potential sensitive data in resource attributes and return warnings.
+ */
+function checkSensitiveData(
+  resources: Record<string, ResourceMetadata>,
+): string[] {
+  const warnings: string[] = [];
+  for (const [name, meta] of Object.entries(resources)) {
+    if (!meta.attributes) continue;
+    for (const attrName of Object.keys(meta.attributes)) {
+      if (SENSITIVE_PATTERNS.some((p) => p.test(attrName))) {
+        warnings.push(
+          `Potential sensitive data in ${name}.attributes.${attrName} — ensure it is scrubbed`,
+        );
+      }
+    }
+  }
+  return warnings;
+}
+
+/**
+ * Validate ResourceMetadata entries — resources must have at least type and status.
+ * Returns { valid, dropped, warnings }.
+ */
+function validateResources(
+  resources: Record<string, ResourceMetadata>,
+): {
+  valid: Record<string, ResourceMetadata>;
+  dropped: string[];
+  warnings: string[];
+} {
+  const valid: Record<string, ResourceMetadata> = {};
+  const dropped: string[] = [];
+  const warnings: string[] = [];
+
+  for (const [name, meta] of Object.entries(resources)) {
+    if (!meta.type || !meta.status) {
+      dropped.push(name);
+      warnings.push(`Dropped ${name}: missing type or status`);
+      continue;
+    }
+    valid[name] = meta;
+  }
+
+  // Check for sensitive data in valid resources
+  warnings.push(...checkSensitiveData(valid));
+
+  return { valid, dropped, warnings };
+}
+
+export interface TakeSnapshotResult {
+  snapshots: StateSnapshot[];
+  commit: string;
+  warnings: string[];
+  errors: string[];
+}
+
+/**
+ * Take state snapshots for all plugins that implement describeResources.
+ */
+export async function takeSnapshot(
+  environment: string,
+  plugins: LexiconPlugin[],
+  buildResult: BuildResult,
+  opts?: { cwd?: string },
+): Promise<TakeSnapshotResult> {
+  const warnings: string[] = [];
+  const errors: string[] = [];
+  const snapshots: StateSnapshot[] = [];
+
+  const headCommit = await getHeadCommit(opts);
+  const timestamp = new Date().toISOString();
+  const digest = computeBuildDigest(buildResult);
+
+  for (const plugin of plugins) {
+    if (!plugin.describeResources) continue;
+
+    // Get serialized build output for this lexicon
+    const rawOutput = buildResult.outputs.get(plugin.name);
+    const buildOutput =
+      rawOutput === undefined
+        ? ""
+        : typeof rawOutput === "string"
+          ? rawOutput
+          : (rawOutput as SerializerResult).primary;
+
+    // Get entity names for this lexicon
+    const entityNames: string[] = [];
+    for (const [name, entity] of buildResult.entities) {
+      if (entity.lexicon === plugin.name) {
+        entityNames.push(name);
+      }
+    }
+
+    try {
+      const resources = await plugin.describeResources({
+        environment,
+        buildOutput,
+        entityNames,
+      });
+
+      const { valid, dropped, warnings: validationWarnings } =
+        validateResources(resources);
+      warnings.push(...validationWarnings);
+
+      if (dropped.length > 0) {
+        warnings.push(
+          `${plugin.name}: dropped ${dropped.length} invalid resource(s)`,
+        );
+      }
+
+      if (Object.keys(valid).length === 0) {
+        errors.push(`${plugin.name}: no valid resources returned`);
+        continue;
+      }
+
+      const snapshot: StateSnapshot = {
+        lexicon: plugin.name,
+        environment,
+        commit: headCommit,
+        timestamp,
+        resources: valid,
+        digest,
+      };
+
+      snapshots.push(snapshot);
+    } catch (err) {
+      errors.push(
+        `${plugin.name}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  // Write all successful snapshots to git
+  let commitSha = "";
+  for (const snapshot of snapshots) {
+    const json = JSON.stringify(snapshot, sortedJsonReplacer, 2);
+    commitSha = await writeSnapshot(
+      snapshot.environment,
+      snapshot.lexicon,
+      json,
+      opts,
+    );
+  }
+
+  // Push to remote
+  if (snapshots.length > 0) {
+    await pushState(opts);
+  }
+
+  return {
+    snapshots,
+    commit: commitSha,
+    warnings,
+    errors,
+  };
+}