@intentius/chant 0.18.29 → 0.18.31

package/src/components/run-progress.ts

@@ -0,0 +1,117 @@
+/**
+ * Structured progress events for `chant run --components <sel> --progress-json`
+ * (behold roadmap M3: a consumer that renders live wave/phase/step progress
+ * instead of tailing raw logs).
+ *
+ * This is purely additive observation over the interpret driver's existing
+ * wave -> component -> phase -> step execution loop (./driver.ts): an
+ * optional `onProgress` callback, threaded through
+ * `runInterpretDriver`/`runComponentDeploy`/`runPhase` (and the CLI's
+ * single-component path, ./cli-support.ts's `runComponents`), that never
+ * changes run ordering, gating, `onFailure`, rollback, or exit codes — it
+ * only reports what already happened, as it happens. See ./driver.ts's
+ * module doc for what actually executes; streaming progress on the *durable*
+ * (Temporal) path is a separate, later concern (Temporal already exposes
+ * durable run state via `chant run status`/`log`).
+ *
+ * `RunProgressEvent` is a discriminated union on `type`, one JSON object per
+ * NDJSON line (see `ndjsonProgressSink` below and
+ * ../cli/handlers/run.ts's `--progress-json` wiring).
+ */
+
+/** Terminal status for a wave/component/phase/run — mirrors DriverStepRecord's ok/fail split, collapsed to the two outcomes a consumer renders progress against. */
+export type RunProgressStatus = "ok" | "failed";
+
+/** The run is about to start. `waves` are the parallel-safe waves the run will attempt, in order (see resolveComponentGraph) — 1-based wave numbers in every other event index into this array. */
+export interface RunStartEvent {
+  type: "run-start";
+  waves: string[][];
+}
+
+/** A wave is about to start; its components may run concurrently (independent components share a wave). */
+export interface WaveStartEvent {
+  type: "wave-start";
+  /** 1-based wave number. */
+  wave: number;
+  components: string[];
+}
+
+/** A component within a wave is about to start its `deploy` composition. */
+export interface ComponentStartEvent {
+  type: "component-start";
+  wave: number;
+  component: string;
+}
+
+/** A named phase of a component's composition is about to run its steps. Emitted for nested (fan-out) phases too, keyed by the nested phase's own name. */
+export interface PhaseStartEvent {
+  type: "phase-start";
+  component: string;
+  phase: string;
+}
+
+/** A single capability step within a phase — one event when it starts, one when it settles. */
+export interface StepEvent {
+  type: "step";
+  component: string;
+  phase: string;
+  step: string;
+  status: "running" | "ok" | "failed";
+  /** Present only alongside `status: "failed"`, when the capability threw. */
+  error?: string;
+}
+
+/** A phase finished — `ok` if every step in it succeeded, `failed` if any step failed (the phase's remaining steps were skipped, per the driver's fail-fast-within-a-phase semantics). */
+export interface PhaseDoneEvent {
+  type: "phase-done";
+  component: string;
+  phase: string;
+  status: RunProgressStatus;
+}
+
+/** A component's `deploy` composition finished (after any saga rollback + component-level `rollback` phases the driver ran on failure). */
+export interface ComponentDoneEvent {
+  type: "component-done";
+  wave: number;
+  component: string;
+  status: RunProgressStatus;
+}
+
+/** A wave finished — `failed` if any component in it failed, which also stops the run before any later wave starts. */
+export interface WaveDoneEvent {
+  type: "wave-done";
+  wave: number;
+  status: RunProgressStatus;
+}
+
+/** The run finished. Mirrors the driver's own terminal `DriverRunResult.ok` / exit code. */
+export interface RunDoneEvent {
+  type: "run-done";
+  status: RunProgressStatus;
+}
+
+export type RunProgressEvent =
+  | RunStartEvent
+  | WaveStartEvent
+  | ComponentStartEvent
+  | PhaseStartEvent
+  | StepEvent
+  | PhaseDoneEvent
+  | ComponentDoneEvent
+  | WaveDoneEvent
+  | RunDoneEvent;
+
+/** A sink that receives progress events as they occur. The driver only ever calls this — it never writes to a stream directly, so it stays testable without stdout. */
+export type RunProgressSink = (event: RunProgressEvent) => void;
+
+/**
+ * Build a sink that writes `JSON.stringify(event) + "\n"` to `write` (default:
+ * `process.stdout.write`), one line per event, as they happen — the
+ * `--progress-json` CLI wiring's sink (../cli/handlers/run.ts). Kept separate
+ * from `driver-output.ts`'s end-of-run renderers: this emits *during* the
+ * run, one line at a time; `renderDriverJson`/`renderDriverHuman` render the
+ * completed `DriverRunResult` once, after the run finishes.
+ */
+export function ndjsonProgressSink(write: (chunk: string) => void = (s) => void process.stdout.write(s)): RunProgressSink {
+  return (event) => write(JSON.stringify(event) + "\n");
+}

package/src/lifecycle/observe.test.ts

@@ -62,4 +62,52 @@ describe("observeResources", () => {
     const { observations } = await observeResources("prod", [empty, noObserve], mockBuild());
     expect(observations).toEqual([]);
   });
+
+  it("with no stacks: calls describeResources exactly once with no `stack` key (unchanged single-stack path)", async () => {
+    const calls: Array<{ stack?: string }> = [];
+    const plugins = [
+      awsPlugin((opts) => {
+        calls.push(opts as { stack?: string });
+        return { "web-vpc": { type: "AWS::EC2::VPC", status: "CREATE_COMPLETE" } };
+      }),
+    ];
+    const { observations } = await observeResources("prod", plugins, mockBuild());
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).not.toHaveProperty("stack");
+    expect(Object.keys(observations[0].resources)).toEqual(["web-vpc"]);
+  });
+
+  it("with stacks: [s1, s2] — calls describeResources once per stack and unions the results", async () => {
+    const calls: Array<string | undefined> = [];
+    const plugins = [
+      awsPlugin((opts) => {
+        const stack = (opts as { stack?: string }).stack;
+        calls.push(stack);
+        // Different resources per stack — the multi-stack, per-component case.
+        const resources: Record<string, ResourceMetadata> =
+          stack === "s1"
+            ? { "db-a": { type: "AWS::RDS::DBInstance", status: "AVAILABLE" } }
+            : { "db-b": { type: "AWS::RDS::DBInstance", status: "AVAILABLE" } };
+        return resources;
+      }),
+    ];
+    const { observations, errors } = await observeResources("prod", plugins, mockBuild(), { stacks: ["s1", "s2"] });
+    expect(calls).toEqual(["s1", "s2"]);
+    expect(errors).toEqual([]);
+    expect(observations).toHaveLength(1);
+    expect(Object.keys(observations[0].resources).sort()).toEqual(["db-a", "db-b"]);
+  });
+
+  it("with an empty stacks array — falls back to the single unstacked call", async () => {
+    const calls: Array<{ stack?: string }> = [];
+    const plugins = [
+      awsPlugin((opts) => {
+        calls.push(opts as { stack?: string });
+        return { "web-vpc": { type: "AWS::EC2::VPC", status: "CREATE_COMPLETE" } };
+      }),
+    ];
+    await observeResources("prod", plugins, mockBuild(), { stacks: [] });
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).not.toHaveProperty("stack");
+  });
 });

package/src/lifecycle/observe.ts

@@ -27,14 +27,27 @@ export interface ObserveResult {
  * 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.
+ *
+ * `stacks` (#57) is for a multi-stack, per-component project (e.g. loomster)
+ * where there is no single stack named after the environment — AWS's
+ * single-stack convention (`lexicons/aws/src/plugin.ts`'s `describeResources`,
+ * absent an explicit `stack`) queries a stack that simply doesn't exist there,
+ * so the single-call path always observes zero nodes. When `stacks` is
+ * present and non-empty, each observing plugin's `describeResources` is
+ * called once per stack (same `environment`/`entities`/`entityNames`, only
+ * `stack` varies) and the returned resource maps are unioned — a resource
+ * appears under whichever stack contains its logical id. When `stacks` is
+ * absent or empty, behavior is exactly the single call of before (no `stack`
+ * key at all), so a single-stack project is unaffected.
  */
 export async function observeResources(
   environment: string,
   plugins: ObservationLexicon[],
   buildResult: BuildResult,
-  opts?: { owned?: boolean },
+  opts?: { owned?: boolean; stacks?: string[] },
 ): Promise<ObserveResult> {
   const owned = opts?.owned ?? true;
+  const stacks = opts?.stacks ?? [];
   const observations: LiveObservation[] = [];
   const warnings: string[] = [];
   const errors: string[] = [];
@@ -64,13 +77,29 @@ export async function observeResources(
     }
 
     try {
-      const resources: Record<string, ResourceMetadata> = await plugin.describeResources({
-        environment,
-        buildOutput,
-        entityNames,
-        entities,
-        owned,
-      });
+      let resources: Record<string, ResourceMetadata>;
+      if (stacks.length > 0) {
+        resources = {};
+        for (const stack of stacks) {
+          const perStack = await plugin.describeResources({
+            environment,
+            buildOutput,
+            entityNames,
+            entities,
+            owned,
+            stack,
+          });
+          Object.assign(resources, perStack);
+        }
+      } else {
+        resources = await plugin.describeResources({
+          environment,
+          buildOutput,
+          entityNames,
+          entities,
+          owned,
+        });
+      }
       if (Object.keys(resources).length > 0) {
         observations.push({ lexicon: plugin.name, resources });
       }