@intentius/chant 0.15.2 → 0.16.0

package/src/graph-refs.ts

@@ -0,0 +1,196 @@
+/**
+ * Live edge reconstruction (#778, the crux of epic #776).
+ *
+ * A source-derived IR gets its edges from declared AttrRefs. A live IR
+ * (`chant graph --live`) has none — observed resources reference each other by
+ * **physical identifier** buried in their attributes (a subnet's `VpcId`, an
+ * ALB listener's `TargetGroupArn`, an ECS service's `ClusterArn`). This module
+ * reconstructs those relationships from a per-lexicon **reference catalog**.
+ *
+ * Provider-agnostic: the engine here is pure and knows nothing about AWS; each
+ * lexicon ships its own `ReferenceCatalog` (data). Given the live nodes and a
+ * catalog, `reconstructEdges` returns:
+ *   - `edges`       — peer references → IR edges (holder → referenced)
+ *   - `containment` — "inside" references (subnet ∈ VPC) → boundary hints for #779
+ *   - `dangling`    — references whose target isn't in the observed set
+ *
+ * The containment / edge split keeps subnet-in-VPC a boundary box (#779), not a
+ * cluttering line. Deterministic given a fixed node set.
+ */
+import type { IRNode, IREdge } from "./graph-ir";
+
+/** Which attribute paths identify a resource kind (its id / ARN / name / DNS). */
+export interface IdentityRule {
+  kind: string;
+  /** Attr paths whose values are identifiers others reference this kind by. */
+  ids: string[];
+}
+
+/** A reference: an attr path on `from` whose value points at another resource. */
+export interface RefRule {
+  /** Holder kind. */
+  from: string;
+  /** Attr path — supports `a.b` and `arr[].id`. */
+  path: string;
+  /** Which identifier the value is (currently informational; matching is exact). */
+  match?: "id" | "arn" | "name" | "any";
+  /** Constrain the target kind (disambiguates identifier collisions). */
+  targetKind?: string;
+  /** `reference` → an edge; `containment` → a boundary hint (#779), not an edge. */
+  relation: "reference" | "containment";
+  /** Edge / containment label (e.g. "in VPC", "sg", "targets"). */
+  label?: string;
+}
+
+/** A lexicon's reference knowledge — its identity map and reference rules. */
+export interface ReferenceCatalog {
+  identities: IdentityRule[];
+  refs: RefRule[];
+}
+
+/** `child` is contained by `parent` (subnet ∈ VPC). For #779's boundary boxes. */
+export interface ContainmentPair {
+  child: string;
+  parent: string;
+  label?: string;
+}
+
+/** A reference whose target isn't in the observed set (cross-account, unmanaged,
+ * deleted) — surfaced, never turned into a wrong edge. */
+export interface DanglingRef {
+  from: string;
+  path: string;
+  value: string;
+  targetKind?: string;
+}
+
+export interface ReconstructedEdges {
+  edges: IREdge[];
+  containment: ContainmentPair[];
+  dangling: DanglingRef[];
+}
+
+function toStr(v: unknown): string | undefined {
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  return undefined;
+}
+
+/**
+ * Read all scalar values at an attr path. Supports nested keys (`a.b`) and array
+ * fan-out (`arr[]`, `arr[].id`). Returns every scalar found — a path through an
+ * array yields one value per element.
+ */
+export function readPath(obj: unknown, path: string): string[] {
+  let cur: unknown[] = [obj];
+  for (const part of path.split(".")) {
+    const isArr = part.endsWith("[]");
+    const key = isArr ? part.slice(0, -2) : part;
+    const next: unknown[] = [];
+    for (const c of cur) {
+      if (c == null || typeof c !== "object") continue;
+      const val = (c as Record<string, unknown>)[key];
+      if (isArr) {
+        if (Array.isArray(val)) next.push(...val);
+      } else if (val !== undefined) {
+        next.push(val);
+      }
+    }
+    cur = next;
+  }
+  const out: string[] = [];
+  for (const c of cur) {
+    const s = toStr(c);
+    if (s !== undefined) out.push(s);
+  }
+  return out;
+}
+
+/** Merge several lexicons' catalogs into one (concatenate identities + refs). */
+export function mergeCatalogs(catalogs: ReferenceCatalog[]): ReferenceCatalog {
+  return {
+    identities: catalogs.flatMap((c) => c.identities),
+    refs: catalogs.flatMap((c) => c.refs),
+  };
+}
+
+/**
+ * Reconstruct edges + containment from live nodes and a catalog. Pure and
+ * deterministic. Matching is exact on identifier value; identifier collisions
+ * across kinds are disambiguated by `targetKind`. Self-references are dropped.
+ */
+export function reconstructEdges(nodes: IRNode[], catalog: ReferenceCatalog): ReconstructedEdges {
+  // Identity index: identifier value → the node(s) that own it.
+  const index = new Map<string, Array<{ id: string; kind: string }>>();
+  const add = (value: string, id: string, kind: string) => {
+    (index.get(value) ?? index.set(value, []).get(value)!).push({ id, kind });
+  };
+  for (const node of nodes) {
+    // Every node is identified by its own logical id — so references resolved to
+    // a logical id (e.g. a CloudFormation `{Ref: LogicalId}` from exportResources,
+    // #784) match directly — plus its physical id and any catalog identity attrs.
+    add(node.id, node.id, node.kind);
+    if (node.physicalId) add(node.physicalId, node.id, node.kind);
+    for (const rule of catalog.identities) {
+      if (rule.kind !== node.kind) continue;
+      for (const p of rule.ids) for (const v of readPath(node.attrs, p)) add(v, node.id, node.kind);
+    }
+  }
+
+  const edges: IREdge[] = [];
+  const containment: ContainmentPair[] = [];
+  const dangling: DanglingRef[] = [];
+  const seenEdge = new Set<string>();
+  const seenCont = new Set<string>();
+
+  for (const node of nodes) {
+    for (const rule of catalog.refs) {
+      if (rule.from !== node.kind) continue;
+      for (const value of readPath(node.attrs, rule.path)) {
+        const candidates = index.get(value) ?? [];
+        const match = rule.targetKind ? candidates.find((c) => c.kind === rule.targetKind) : candidates[0];
+        if (!match) {
+          dangling.push({ from: node.id, path: rule.path, value, ...(rule.targetKind ? { targetKind: rule.targetKind } : {}) });
+          continue;
+        }
+        if (match.id === node.id) continue; // self-reference (e.g. an SG rule to its own group)
+        if (rule.relation === "containment") {
+          const k = `${node.id}|${match.id}`;
+          if (seenCont.has(k)) continue;
+          seenCont.add(k);
+          containment.push({ child: node.id, parent: match.id, ...(rule.label ? { label: rule.label } : {}) });
+        } else {
+          const via = rule.label ?? rule.path;
+          const k = `${node.id}|${match.id}|${via}`;
+          if (seenEdge.has(k)) continue;
+          seenEdge.add(k);
+          edges.push({ from: node.id, to: match.id, kind: "ref", viaAttr: via });
+        }
+      }
+    }
+  }
+
+  edges.sort((a, b) => `${a.from}|${a.to}|${a.viaAttr}`.localeCompare(`${b.from}|${b.to}|${b.viaAttr}`));
+  containment.sort((a, b) => `${a.child}|${a.parent}`.localeCompare(`${b.child}|${b.parent}`));
+  dangling.sort((a, b) => `${a.from}|${a.path}|${a.value}`.localeCompare(`${b.from}|${b.path}|${b.value}`));
+
+  return { edges, containment, dangling };
+}
+
+/**
+ * Invert containment pairs into grouping metadata (#779): container node id → the
+ * node ids directly inside it. The result is the `IRGroups.byContainer` shape a
+ * renderer draws as boundary boxes. It represents the full nesting *flatly* — a
+ * subnet is both a member of its VPC's entry and a key with its own members —
+ * so a boundary-box renderer recurses it (VPC ⊃ subnet ⊃ resources). Sorted for
+ * determinism.
+ */
+export function containmentGroups(pairs: ContainmentPair[]): Record<string, string[]> {
+  const byParent = new Map<string, Set<string>>();
+  for (const { child, parent } of pairs) {
+    (byParent.get(parent) ?? byParent.set(parent, new Set()).get(parent)!).add(child);
+  }
+  const out: Record<string, string[]> = {};
+  for (const parent of [...byParent.keys()].sort()) out[parent] = [...byParent.get(parent)!].sort();
+  return out;
+}

package/src/lexicon.ts

@@ -9,6 +9,11 @@ import type { CompletionContext, CompletionItem, HoverContext, HoverInfo, CodeAc
 import type { McpToolContribution, McpResourceContribution } from "./mcp/types";
 import type { DriverComponent } from "./components/driver";
 import type { RuleMeta } from "./audit/catalog";
+import type { ReferenceCatalog } from "./graph-refs";
+
+// Re-exported so lexicons can author a reference catalog (#778) from the same
+// `@intentius/chant/lexicon` entry they import the plugin contract from.
+export type { ReferenceCatalog, IdentityRule, RefRule } from "./graph-refs";
 
 /**
  * Manifest for a packaged lexicon — metadata embedded in the tarball.
@@ -369,6 +374,26 @@ export interface LexiconPlugin {
     owned?: boolean;
   }): Promise<Record<string, ResourceMetadata>>;
 
+  /**
+   * Reference catalog for live edge reconstruction (#778). Declares how this
+   * lexicon's observed resources reference each other — an identity map (which
+   * attrs identify each kind) plus reference rules (which attr paths point at
+   * other resources, as a peer edge or containment). Consumed by
+   * `chant graph --live` to turn a bag of live nodes into a graph. Data, not a
+   * method. Opt-in.
+   */
+  referenceCatalog?: ReferenceCatalog;
+
+  /**
+   * Enrich live IR node attributes for edge reconstruction (#784). Returns
+   * `nodeId → attributes` with cross-resource references resolved to the
+   * referenced node id, so the reference resolver ({@link referenceCatalog}) can
+   * match them. Opt-in — for lexicons whose `describeResources` metadata is too
+   * thin to carry references (e.g. AWS CloudFormation, where it's sourced from
+   * the fuller `exportResources` config).
+   */
+  enrichLiveAttrs?(options: { environment: string; owned?: boolean }): Promise<Record<string, Record<string, unknown>>>;
+
   /**
    * List runtime artifacts in the given environment. Opt-in.
    *

package/src/lifecycle/observe.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from "vitest";
+import { observeResources } from "./observe";
+import type { ObservationLexicon, ResourceMetadata } from "../lexicon";
+import type { BuildResult } from "../build";
+
+function mockBuild(): BuildResult {
+  return {
+    outputs: new Map<string, string>([["aws", "{}"]]),
+    entities: new Map([
+      ["web-vpc", { lexicon: "aws", entityType: "AWS::EC2::VPC", props: {} }],
+    ]),
+    errors: [],
+  } as unknown as BuildResult;
+}
+
+function awsPlugin(
+  describe: (opts: { owned?: boolean; entityNames: string[] }) => Record<string, ResourceMetadata>,
+): ObservationLexicon {
+  return {
+    name: "aws",
+    serializer: {} as ObservationLexicon["serializer"],
+    describeResources: async (opts) => describe(opts),
+  } as ObservationLexicon;
+}
+
+describe("observeResources", () => {
+  it("collects each plugin's resources as observations, defaulting owned=true", async () => {
+    let sawOwned: boolean | undefined;
+    const plugins = [
+      awsPlugin(({ owned }) => {
+        sawOwned = owned;
+        return { "web-vpc": { type: "AWS::EC2::VPC", status: "CREATE_COMPLETE", physicalId: "vpc-1", ownership: "owned" } };
+      }),
+    ];
+    const { observations, errors } = await observeResources("prod", plugins, mockBuild());
+    expect(sawOwned).toBe(true); // managed-only
+    expect(errors).toEqual([]);
+    expect(observations).toHaveLength(1);
+    expect(observations[0].lexicon).toBe("aws");
+    expect(Object.keys(observations[0].resources)).toEqual(["web-vpc"]);
+  });
+
+  it("passes the declared entity names for scoping", async () => {
+    let names: string[] = [];
+    const plugins = [awsPlugin(({ entityNames }) => { names = entityNames; return {}; })];
+    await observeResources("prod", plugins, mockBuild());
+    expect(names).toEqual(["web-vpc"]);
+  });
+
+  it("collects a throwing plugin into errors instead of failing the whole graph", async () => {
+    const plugins = [
+      awsPlugin(() => { throw new Error("access denied"); }),
+    ];
+    const { observations, errors } = await observeResources("prod", plugins, mockBuild());
+    expect(observations).toEqual([]);
+    expect(errors).toEqual(["aws: access denied"]);
+  });
+
+  it("skips plugins with no describeResources and drops empty results", async () => {
+    const empty = awsPlugin(() => ({}));
+    const noObserve = { name: "gitlab", serializer: {} } as unknown as ObservationLexicon;
+    const { observations } = await observeResources("prod", [empty, noObserve], mockBuild());
+    expect(observations).toEqual([]);
+  });
+});

package/src/lifecycle/observe.ts

@@ -0,0 +1,83 @@
+/**
+ * Live observation without persistence — call each plugin's `describeResources()`
+ * for an environment and collect the results as `LiveObservation[]`, ready to
+ * project into the graph IR (`buildLiveGraphIr`, ../graph-ir.ts) for
+ * `chant graph --live`.
+ *
+ * This is the read half of what `takeSnapshot` (./snapshot.ts) does before it
+ * validates + writes to git: same per-plugin build-output/entities assembly, no
+ * side effects. Snapshotting keeps its own copy for now; a future refactor can
+ * fold both onto this primitive.
+ */
+import type { ObservationLexicon, ResourceMetadata } from "../lexicon";
+import type { BuildResult } from "../build";
+import type { SerializerResult } from "../serializer";
+import type { LiveObservation } from "../graph-ir";
+
+export interface ObserveResult {
+  observations: LiveObservation[];
+  warnings: string[];
+  errors: string[];
+}
+
+/**
+ * Query every plugin that implements `describeResources` for its resources in
+ * `environment`. `owned` (default true for the managed-only diagram, epic #776)
+ * restricts to resources carrying chant's ownership marker; a lexicon with no
+ * marker channel logs and returns everything (its own contract). Plugins that
+ * throw are collected into `errors` and skipped — one failing lexicon never
+ * sinks the whole graph.
+ */
+export async function observeResources(
+  environment: string,
+  plugins: ObservationLexicon[],
+  buildResult: BuildResult,
+  opts?: { owned?: boolean },
+): Promise<ObserveResult> {
+  const owned = opts?.owned ?? true;
+  const observations: LiveObservation[] = [];
+  const warnings: string[] = [];
+  const errors: string[] = [];
+
+  for (const plugin of plugins) {
+    if (!plugin.describeResources) continue;
+
+    // Serialized build output + declared entities for this lexicon — the scope
+    // describeResources needs to know what to look for.
+    const rawOutput = buildResult.outputs.get(plugin.name);
+    const buildOutput =
+      rawOutput === undefined
+        ? ""
+        : typeof rawOutput === "string"
+          ? rawOutput
+          : (rawOutput as SerializerResult).primary;
+
+    const entityNames: string[] = [];
+    const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
+    for (const [name, entity] of buildResult.entities) {
+      if (entity.lexicon !== plugin.name) continue;
+      entityNames.push(name);
+      entities.set(name, {
+        entityType: entity.entityType,
+        props: ("props" in entity && entity.props != null ? entity.props : {}) as Record<string, unknown>,
+      });
+    }
+
+    try {
+      const resources: Record<string, ResourceMetadata> = await plugin.describeResources({
+        environment,
+        buildOutput,
+        entityNames,
+        entities,
+        owned,
+      });
+      if (Object.keys(resources).length > 0) {
+        observations.push({ lexicon: plugin.name, resources });
+      }
+    } catch (err) {
+      errors.push(`${plugin.name}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  return { observations, warnings, errors };
+}

package/src/op/builders.ts

@@ -257,6 +257,27 @@ export const azDelete = (templatePath: string, opts?: Record<string, unknown>):
   return activity("azDelete", { templatePath, ...args }, profile ?? "longInfra");
 };
 
+/**
+ * Deploy a built CloudFormation template by calling the CloudFormation API
+ * directly (create-or-update + poll) — the direct twin of {@link azApply} /
+ * {@link gcpApply} for AWS, targeting a local Floci emulator or real AWS by
+ * endpoint override. Speaks the CFN API over HTTP rather than shelling `aws`
+ * (that path is still `nativeApply({ target: "cloudformation" })`). Provided by
+ * the aws lexicon; loaded when the project lists `aws`. Defaults to the
+ * `longInfra` profile. `opts` requires `stackName`; accepts `endpoint`, `region`,
+ * `capabilities`, `timeoutMs`, `intervalMs`.
+ */
+export const awsApply = (templatePath: string, opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("awsApply", { templatePath, ...args }, profile ?? "longInfra");
+};
+
+/** Delete a CloudFormation stack — the inverse of {@link awsApply}. Defaults to the `longInfra` profile (override via `opts.profile`). `opts` requires `stackName`. */
+export const awsDelete = (templatePath: string, opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("awsDelete", { templatePath, ...args }, profile ?? "longInfra");
+};
+
 /**
  * Apply chant's built GCP (CNRM) resources directly to the GCS REST API,
  * targeting a local floci-gcp emulator or real GCP by endpoint override — the
@@ -277,6 +298,120 @@ export const gcpDelete = (manifestPath: string, opts?: Record<string, unknown>):
   return activity("gcpDelete", { manifestPath, ...args }, profile ?? "longInfra");
 };
 
+// ── Sprites (#762) — imperative, checkpointable sandbox steps ──────────────────
+//
+// The builder and the executor-side activity function share a name (e.g.
+// `spriteCreate`), and that is intentional: the builder here returns an
+// `activity("spriteCreate", ...)` step; `loadActivities` loads the function of
+// the same name from the temporal lexicon to run the HTTP. They live in
+// different modules and are both exported — exactly how `flapsUp`/`flapsDown`
+// already work. Op files import these builders; the executor resolves the
+// function by name. Endpoint override + bearer are read by the activity from
+// `SPRITES_BASE_URL` / `SPRITES_API_TOKEN` (or an explicit `endpoint` arg).
+
+/** Create a sprite with a caller-chosen `name` (used as its id). Defaults to the `longInfra` profile (override via `profile`). */
+export const spriteCreate = (args: {
+  name: string;
+  image?: string;
+  size?: string;
+  policy?: unknown;
+  endpoint?: string;
+  token?: string;
+  profile?: ActivityStep["profile"];
+}): ActivityStep => {
+  const { profile, ...rest } = args;
+  return activity("spriteCreate", rest, profile ?? "longInfra");
+};
+
+/** Run a command in a sprite; a non-zero exit fails the step. Defaults to the `longInfra` profile (override via `profile`). */
+export const spriteExec = (args: {
+  id: string;
+  cmd: string;
+  timeoutMs?: number;
+  endpoint?: string;
+  token?: string;
+  profile?: ActivityStep["profile"];
+}): ActivityStep => {
+  const { profile, ...rest } = args;
+  return activity("spriteExec", rest, profile ?? "longInfra");
+};
+
+/** Checkpoint a sprite under a caller-chosen `comment` (the transactional boundary). Defaults to the `longInfra` profile (override via `profile`). */
+export const spriteCheckpoint = (args: {
+  id: string;
+  comment?: string;
+  endpoint?: string;
+  token?: string;
+  profile?: ActivityStep["profile"];
+}): ActivityStep => {
+  const { profile, ...rest } = args;
+  return activity("spriteCheckpoint", rest, profile ?? "longInfra");
+};
+
+/**
+ * Restore a sprite — the checkpoint-as-compensation step (S5). Target an
+ * explicit `checkpoint` id, or the newest checkpoint carrying `comment`, or (with
+ * neither) the newest checkpoint overall. Defaults to the `longInfra` profile
+ * (override via `profile`).
+ */
+export const spriteRestore = (args: {
+  id: string;
+  checkpoint?: string;
+  comment?: string;
+  endpoint?: string;
+  token?: string;
+  profile?: ActivityStep["profile"];
+}): ActivityStep => {
+  const { profile, ...rest } = args;
+  return activity("spriteRestore", rest, profile ?? "longInfra");
+};
+
+/** List a sprite's checkpoints (`[{ id, comment, create_time, is_auto }]`). Defaults to the `fastIdempotent` profile (override via `profile`). */
+export const listCheckpoints = (args: {
+  id: string;
+  endpoint?: string;
+  token?: string;
+  profile?: ActivityStep["profile"];
+}): ActivityStep => {
+  const { profile, ...rest } = args;
+  return activity("listCheckpoints", rest, profile ?? "fastIdempotent");
+};
+
+/** Destroy a sprite (idempotent). Defaults to the `fastIdempotent` profile (override via `profile`). */
+export const spriteDestroy = (args: {
+  id: string;
+  endpoint?: string;
+  token?: string;
+  profile?: ActivityStep["profile"];
+}): ActivityStep => {
+  const { profile, ...rest } = args;
+  return activity("spriteDestroy", rest, profile ?? "fastIdempotent");
+};
+
+/**
+ * Boot a local spritzer (Fly Sprites API emulator) in Docker — the typed twin of
+ * `flociGcpUp` for Sprites. Resolves to the `spritesUp` activity. Defaults to the
+ * `longInfra` profile (the image may pull); override via `profile`.
+ */
+export const spritesUp = (args: {
+  name?: string;
+  port?: number;
+  image?: string;
+  profile?: ActivityStep["profile"];
+} = {}): ActivityStep => {
+  const { profile, ...rest } = args;
+  return activity("spritesUp", rest, profile ?? "longInfra");
+};
+
+/** Stop and remove the local spritzer container. Resolves to the `spritesDown` activity. Defaults to the `fastIdempotent` profile (override via `profile`). */
+export const spritesDown = (args: {
+  name?: string;
+  profile?: ActivityStep["profile"];
+} = {}): ActivityStep => {
+  const { profile, ...rest } = args;
+  return activity("spritesDown", rest, profile ?? "fastIdempotent");
+};
+
 /**
  * Gate an apply on organizational policy: build the project and run its
  * `lint.policies` over the resolved resources, blocking the workflow on any

package/src/op/emulator-lifecycle.test.ts

@@ -0,0 +1,41 @@
+import { describe, test, expect } from "vitest";
+import { emulatorLifecycle } from "./emulator-lifecycle";
+
+describe("emulatorLifecycle command builders", () => {
+  const emu = emulatorLifecycle({
+    name: "chant-x",
+    image: "org/x:1.0",
+    containerPort: 4200,
+    healthPath: "/_x/health",
+  });
+
+  test("runCommand uses defaults and maps host port to the container port", () => {
+    expect(emu.runCommand()).toBe("docker run -d --rm --name chant-x -p 4200:4200 org/x:1.0");
+  });
+
+  test("runCommand honors name/port/image overrides (host port maps to containerPort)", () => {
+    expect(emu.runCommand({ name: "x2", port: 4599, image: "org/x:2.0" })).toBe(
+      "docker run -d --rm --name x2 -p 4599:4200 org/x:2.0",
+    );
+  });
+
+  test("spec.runArgs and per-call extraArgs precede the image", () => {
+    const e = emulatorLifecycle({
+      name: "n",
+      image: "img:1",
+      containerPort: 80,
+      healthPath: "/h",
+      runArgs: ["--pull", "always"],
+    });
+    expect(e.runCommand({ extraArgs: ["-v", "/sock:/sock"] })).toBe(
+      "docker run -d --rm --name n -p 80:80 --pull always -v /sock:/sock img:1",
+    );
+  });
+
+  test("exists / rm / health / endpoint", () => {
+    expect(emu.existsCommand("n")).toBe("docker ps -q -f name=n");
+    expect(emu.rmCommand("n")).toBe("docker rm -f n");
+    expect(emu.healthUrl(4599)).toBe("http://localhost:4599/_x/health");
+    expect(emu.endpoint(4599)).toBe("http://localhost:4599");
+  });
+});