@intentius/chant 0.124.13 → 0.124.14

package/dist/components/promote.js

@@ -0,0 +1,549 @@
+/**
+ * Promote a release to another environment without rebuilding (#2530).
+ *
+ * `chant run --components <name> --env prod` runs the component's whole
+ * `deploy` composition, and a composition that builds (a `Build` phase with
+ * `docker-build`) builds again in prod. The release ledger already knows which
+ * digest staging is running, so a promote reads that record and deploys the
+ * same artifact to the target environment instead.
+ *
+ * The mechanism is a transform on the composition, not a change to the driver:
+ *
+ *  - build-time steps (`BUILD_STEP_KINDS`) are removed, so nothing is built;
+ *  - the publish step stays. It moves the archived bytes to the target
+ *    environment, which is what "promote by digest" means in the build-archive
+ *    model, and its output is checked against the recorded digest. A publish
+ *    that produces any other digest fails the step, and so the component,
+ *    before anything after it runs;
+ *  - gates, apply, verify and every other step run exactly as a normal deploy
+ *    to the target environment would run them, so the target's gates apply.
+ *    A gate approval is bound to the target environment, the transformed
+ *    composition and the digest being deployed (#2574), so an approval for a
+ *    plain deploy or for another release does not pass it.
+ *
+ * A composition the transform cannot pin to one recorded digest is refused
+ * before anything runs: one with no publish step (nothing would carry the
+ * digest), one with more than one (the ledger records one digest per
+ * component), and one whose remaining steps read an output of a removed build
+ * step (it would resolve to nothing).
+ *
+ * A rollback (#2531) is the same run against one environment's own earlier
+ * release. There the publish step is replaced by the recorded digest rather
+ * than run, since the environment already received that artifact when the
+ * release was first deployed (see `withoutBuildSteps`'s `pinDigest`). A
+ * redeploy (#2604) is a rollback to the release the ledger already records as
+ * current, for an environment a failed deploy left running something else.
+ *
+ * The driver stays capability-agnostic. The two kind lists below are data, in
+ * the same spirit as `DEPLOY_UNIT_RULES` (./deploy-units.ts).
+ */
+import { parseWiringRef } from "../lint/rules/comp/support.js";
+import { latestPerComponent } from "../lifecycle/release-ledger.js";
+import { CapabilityRegistry } from "./capability.js";
+import { runInterpretDriver, DriverRunFailure, } from "./driver.js";
+/**
+ * Step kinds that produce an artifact at build time: the build family, and the
+ * SBOM steps that read the freshly built archive. A promote removes them.
+ */
+export const BUILD_STEP_KINDS = [
+    "docker-build",
+    "zip-package",
+    "jvm-build",
+    "generate-sbom",
+    "extract-config-bom",
+];
+/**
+ * The publish family (the same set COMP001 recognises, plus the
+ * `publish-asset` alias). Its output digest is the one a release record binds.
+ */
+export const PUBLISH_STEP_KINDS = [
+    "publish-image",
+    "publish-artifact",
+    "publish-asset",
+    "load-image-on-host",
+];
+/**
+ * Pick one release of `component` out of an environment's records: the latest
+ * one, or, when `digest` is given, the latest one that recorded that digest.
+ * A digest the ledger never recorded for the component is an error.
+ */
+export function selectRelease(records, component, env, digest) {
+    const own = records.filter((r) => r.component === component);
+    if (own.length === 0)
+        return { error: `no release of "${component}" is recorded in "${env}"` };
+    if (digest === undefined)
+        return { record: latestPerComponent(own).get(component) };
+    const matching = own.filter((r) => r.digest === digest);
+    if (matching.length === 0) {
+        return {
+            error: `digest ${digest} is not recorded for "${component}" in "${env}"; ` +
+                `its recorded digests are ${[...new Set(own.map((r) => r.digest))].join(", ")}`,
+        };
+    }
+    return { record: latestPerComponent(matching).get(component) };
+}
+/**
+ * Read `--digest <component>=<digest>` values (#2602) into a component-to-
+ * digest map. A value with no `=` is left to the single-component form
+ * (`--component <name> --digest <digest>`), so it is an error here. An empty
+ * digest is an error too: a generated promote job passes one when the job that
+ * deployed the component recorded no release, and promoting whatever is
+ * latest instead is the thing the pin is there to prevent.
+ */
+export function parseDigestPins(values) {
+    const pins = {};
+    for (const value of values) {
+        const at = value.indexOf("=");
+        if (at < 0)
+            return { error: "--digest picks one release of one component, so it needs --component <name>, or the form <component>=<digest>" };
+        const component = value.slice(0, at);
+        const digest = value.slice(at + 1);
+        if (component === "")
+            return { error: `--digest ${value} names no component` };
+        if (digest === "") {
+            return { error: `--digest ${value} names no digest; the run that deployed "${component}" recorded no release for it` };
+        }
+        if (component in pins && pins[component] !== digest) {
+            return { error: `--digest pins "${component}" twice, to ${pins[component]} and ${digest}` };
+        }
+        pins[component] = digest;
+    }
+    return { pins };
+}
+/**
+ * Decide which releases a promote deploys. With `component`, exactly that
+ * component's latest source release (or the one recording `digest`). With
+ * `pins` (#2602), exactly the pinned components, each at the source release
+ * recording its pinned digest. Otherwise, the latest source release of every
+ * component this checkout declares; a recorded component the checkout no
+ * longer declares is reported and left alone, since there is no composition
+ * to deploy it with.
+ */
+export function planPromotion(input) {
+    const { from, to, sourceRecords, declared, component, digest, pins } = input;
+    if (from === to)
+        return { error: `--from and --to name the same environment ("${from}")` };
+    if (digest !== undefined && component === undefined) {
+        return { error: "--digest picks one release of one component, so it needs --component <name>" };
+    }
+    if (pins !== undefined && Object.keys(pins).length > 0) {
+        if (component !== undefined) {
+            return { error: "--digest <component>=<digest> names its own component, so it does not take --component" };
+        }
+        const items = [];
+        for (const [name, pinned] of Object.entries(pins).sort(([a], [b]) => a.localeCompare(b))) {
+            if (!declared.includes(name))
+                return { error: `component "${name}" is not declared in this checkout` };
+            const picked = selectRelease(sourceRecords, name, from, pinned);
+            if ("error" in picked)
+                return picked;
+            items.push({ component: name, digest: picked.record.digest, source: picked.record });
+        }
+        return { from, to, items, notPromoted: [] };
+    }
+    if (component !== undefined) {
+        if (!declared.includes(component)) {
+            return { error: `component "${component}" is not declared in this checkout` };
+        }
+        const picked = selectRelease(sourceRecords, component, from, digest);
+        if ("error" in picked)
+            return picked;
+        return { from, to, items: [{ component, digest: picked.record.digest, source: picked.record }], notPromoted: [] };
+    }
+    const latest = latestPerComponent(sourceRecords);
+    const items = [];
+    const notPromoted = [];
+    for (const [name, record] of [...latest].sort(([a], [b]) => a.localeCompare(b))) {
+        if (declared.includes(name))
+            items.push({ component: name, digest: record.digest, source: record });
+        else
+            notPromoted.push({ component: name, reason: "recorded but not declared in this checkout" });
+    }
+    if (items.length === 0) {
+        return { error: `nothing to promote: no component declared here has a release recorded in "${from}"` };
+    }
+    return { from, to, items, notPromoted };
+}
+/**
+ * Decide which release a rollback restores: the release of `component` in
+ * `env` given by `digest`, or by default the most recent release whose digest
+ * differs from the current one. Restoring the release already current is
+ * refused, since there is nothing to roll back.
+ */
+export function planRollback(input) {
+    const { env, records, declared, component, digest } = input;
+    if (!declared.includes(component)) {
+        return { error: `component "${component}" is not declared in this checkout` };
+    }
+    const own = records.filter((r) => r.component === component);
+    const current = latestPerComponent(own).get(component);
+    if (!current)
+        return { error: `no release of "${component}" is recorded in "${env}"` };
+    let target;
+    if (digest !== undefined) {
+        const picked = selectRelease(own, component, env, digest);
+        if ("error" in picked)
+            return picked;
+        target = picked.record;
+    }
+    else {
+        const earlier = own.filter((r) => r.digest !== current.digest);
+        if (earlier.length === 0) {
+            return { error: `"${component}" has no earlier release in "${env}" with a digest other than the current ${current.digest}` };
+        }
+        target = latestPerComponent(earlier).get(component);
+    }
+    if (target.digest === current.digest) {
+        return { error: `${target.digest} is already the current release of "${component}" in "${env}"; nothing to roll back` };
+    }
+    return { from: env, to: env, items: [{ component, digest: target.digest, source: target }], notPromoted: [] };
+}
+/**
+ * Decide what a redeploy deploys: the release of `component` the ledger in
+ * `env` records as current. A deploy that fails partway records nothing, so
+ * after one the ledger still names the last good release while the
+ * environment may be running part of the failed one. `digest`, when given,
+ * has to be that current digest. It guards against a deploy recorded since
+ * the caller last looked; any earlier release is a rollback.
+ */
+export function planRedeploy(input) {
+    const { env, records, declared, component, digest } = input;
+    if (!declared.includes(component)) {
+        return { error: `component "${component}" is not declared in this checkout` };
+    }
+    const current = latestPerComponent(records.filter((r) => r.component === component)).get(component);
+    if (!current)
+        return { error: `no release of "${component}" is recorded in "${env}"` };
+    if (digest !== undefined && digest !== current.digest) {
+        return {
+            error: `${digest} is not the current release of "${component}" in "${env}" (that is ${current.digest}); ` +
+                `use \`chant components rollback ${env} --component ${component} --digest ${digest}\` to restore an earlier release`,
+        };
+    }
+    return { from: env, to: env, items: [{ component, digest: current.digest, source: current }], notPromoted: [] };
+}
+function isGate(step) {
+    return step.kind === "gate";
+}
+function isPhase(step) {
+    return typeof step.phase === "string" && Array.isArray(step.steps);
+}
+/**
+ * The build steps that write the archive a promote's publish step reads, each
+ * to its `into` path. The SBOM steps are left out: a promote refuses a step
+ * that reads their output, so it never needs it.
+ */
+export const ARCHIVE_STEP_KINDS = ["docker-build", "zip-package", "jvm-build"];
+/**
+ * The paths `component`'s build steps write its archive to, in composition
+ * order without repeats (#2575). A generated pipeline carries these files from
+ * the job that deployed to the source environment to the job that promotes,
+ * since a promote publishes from the archive on disk. Throws when an `into` is
+ * not a literal path, such as a wiring reference or an `$env.` value, because
+ * a generator cannot name a file that is only known at run time.
+ */
+export function promoteArchivePaths(component) {
+    const paths = [];
+    const walk = (phases) => {
+        for (const phase of phases) {
+            for (const step of phase.steps) {
+                if (isPhase(step))
+                    walk([step]);
+                else if (!isGate(step) && ARCHIVE_STEP_KINDS.includes(step.kind)) {
+                    const into = step.into;
+                    if (typeof into !== "string" || into === "" || into.startsWith("@") || into.startsWith("$")) {
+                        throw new Error(`component "${component.name}": the ${step.kind} step in phase "${phase.phase}" writes to ` +
+                            `${JSON.stringify(into)}, which is not a literal path, so a generated promote job cannot carry its archive`);
+                    }
+                    if (!paths.includes(into))
+                        paths.push(into);
+                }
+            }
+        }
+    };
+    walk(component.deploy);
+    return paths;
+}
+/**
+ * Whether `component`'s deploy has a publish step (#2602). Only such a
+ * component records a release when it deploys, so only its release can be
+ * promoted; a generated pipeline pins exactly these components' digests.
+ */
+export function hasPublishStep(component) {
+    const walk = (steps) => steps.some((step) => isPhase(step) ? walk(step.steps) : !isGate(step) && PUBLISH_STEP_KINDS.includes(step.kind));
+    return walk(component.deploy);
+}
+/**
+ * The step a rollback puts where the publish step was: it publishes nothing
+ * and returns the recorded digest, so `@Publish.digest` resolves to it.
+ */
+export const RECORDED_DIGEST_KIND = "recorded-digest";
+/** The capability behind {@link RECORDED_DIGEST_KIND}. */
+export const recordedDigestCapability = {
+    kind: RECORDED_DIGEST_KIND,
+    rollbackPolicy: "none-by-design",
+    async run(_ctx, input) {
+        return { digest: input.digest };
+    },
+};
+/**
+ * Remove every build-time step from `component`'s `deploy` composition and
+ * check that what is left can be pinned to one recorded digest. A phase left
+ * with nothing to run is dropped. `rollback` phases are untouched.
+ *
+ * With `pinDigest` (a rollback, #2531, or a redeploy, #2604), the publish step is replaced too, by a
+ * {@link RECORDED_DIGEST_KIND} step carrying that digest: the environment
+ * already received the artifact when the release being restored was
+ * deployed, and the archive it came from is usually long gone. Only the
+ * digest is known then, so a step reading any other publish output (such as
+ * `@Publish.uri`) is refused.
+ */
+export function withoutBuildSteps(component, opts = {}) {
+    const verb = opts.verb ?? (opts.pinDigest === undefined ? "a promote" : "a rollback");
+    const removed = [];
+    /** Phases a build step was removed from, and whether anything else is left in them. */
+    const emptied = new Map();
+    /** Phases a publish step was pinned in, and whether anything else is left in them. */
+    const pinned = new Map();
+    let publishSteps = 0;
+    const kept = [];
+    const strip = (phase) => {
+        const steps = [];
+        let lostBuildStep = false;
+        let pinnedHere = false;
+        for (const step of phase.steps) {
+            if (isGate(step)) {
+                steps.push(step);
+            }
+            else if (isPhase(step)) {
+                const nested = strip(step);
+                if (nested)
+                    steps.push(nested);
+            }
+            else if (BUILD_STEP_KINDS.includes(step.kind)) {
+                removed.push(step.kind);
+                lostBuildStep = true;
+            }
+            else if (PUBLISH_STEP_KINDS.includes(step.kind)) {
+                publishSteps++;
+                if (opts.pinDigest === undefined) {
+                    kept.push(step);
+                    steps.push(step);
+                }
+                else {
+                    removed.push(step.kind);
+                    pinnedHere = true;
+                    steps.push({
+                        kind: RECORDED_DIGEST_KIND,
+                        digest: opts.pinDigest,
+                        replaces: step.kind,
+                        noRollback: "publishes nothing; it hands on a digest the environment already received",
+                    });
+                }
+            }
+            else {
+                kept.push(step);
+                steps.push(step);
+            }
+        }
+        const otherWork = steps.some((s) => !isGate(s) && s.kind !== RECORDED_DIGEST_KIND);
+        if (lostBuildStep)
+            emptied.set(phase.phase, !otherWork && !pinnedHere);
+        if (pinnedHere)
+            pinned.set(phase.phase, !otherWork);
+        // A phase holding only gates after the strip still decides them.
+        if (steps.length === 0)
+            return undefined;
+        return { ...phase, steps };
+    };
+    const deploy = component.deploy.map(strip).filter((p) => p !== undefined);
+    if (publishSteps === 0) {
+        return {
+            error: `component "${component.name}" has no publish step, so nothing in its deploy carries a recorded digest; ` +
+                `${verb} would deploy whatever its current source produces`,
+        };
+    }
+    if (publishSteps > 1) {
+        return {
+            error: `component "${component.name}" has ${publishSteps} publish steps, but its release record carries one digest`,
+        };
+    }
+    for (const step of kept) {
+        const { kind: _kind, ...fields } = step;
+        for (const ref of refsIn(fields)) {
+            if (ref.kind === "prior-step" && emptied.get(ref.phaseName) === true) {
+                return {
+                    error: `component "${component.name}" reads "@${ref.phaseName}.${ref.field}", an output of a build step ` +
+                        `${verb} does not run`,
+                };
+            }
+            const readsPinned = (ref.kind === "prior-step" && pinned.get(ref.phaseName) === true && ref.field !== "digest") ||
+                (ref.kind === "component-artifact" && ref.componentName === component.name && ref.field !== "digest" && pinned.size > 0);
+            if (readsPinned) {
+                const spelled = ref.kind === "prior-step" ? `@${ref.phaseName}.${ref.field}` : `@${ref.componentName}.publish.${ref.field}`;
+                return {
+                    error: `component "${component.name}" reads "${spelled}", but ${verb} knows only the recorded digest; ` +
+                        `wire the digest instead`,
+                };
+            }
+        }
+    }
+    return { component: { ...component, deploy }, removed };
+}
+/** Every same-project wiring reference anywhere in a step's fields (cross-stack `stackOutput` objects excluded). */
+function refsIn(value) {
+    const refs = [];
+    const walk = (v) => {
+        if (typeof v === "string") {
+            const ref = parseWiringRef(v);
+            if (ref)
+                refs.push(ref);
+        }
+        else if (Array.isArray(v)) {
+            v.forEach(walk);
+        }
+        else if (v && typeof v === "object" && !("stackOutput" in v)) {
+            Object.values(v).forEach(walk);
+        }
+    };
+    walk(value);
+    return refs;
+}
+/**
+ * A registry whose publish-family capabilities check what they published
+ * against the digest being promoted for that component. A mismatch fails the
+ * step, which fails the component through the driver's ordinary path. Every
+ * other capability is passed through untouched, and the recorded-digest step a
+ * rollback's composition carries is added.
+ */
+export function checkPublishedDigest(registry, expected) {
+    const checked = new CapabilityRegistry();
+    if (!registry.has(RECORDED_DIGEST_KIND))
+        checked.register(recordedDigestCapability);
+    for (const kind of registry.kinds()) {
+        const inner = registry.resolve(kind);
+        if (!PUBLISH_STEP_KINDS.includes(kind)) {
+            checked.register(inner);
+            continue;
+        }
+        const wrapped = {
+            kind,
+            ...(inner.rollbackPolicy ? { rollbackPolicy: inner.rollbackPolicy } : {}),
+            async run(ctx, input) {
+                let output;
+                try {
+                    output = await inner.run(ctx, input);
+                }
+                catch (err) {
+                    throw new Error(`${kind} could not publish from the build archive: ${err instanceof Error ? err.message : String(err)}. ` +
+                        `A promote publishes the archive the source release was built from, so it has to run where that archive is on disk`);
+                }
+                const want = expected.get(ctx.component);
+                const got = output?.digest;
+                if (want !== undefined && got !== want) {
+                    throw new Error(`${kind} published ${typeof got === "string" ? got : "no digest"}, but the release being promoted recorded ${want}; ` +
+                        `the build archive on disk is not the one that release was built from`);
+                }
+                return output;
+            },
+            ...(inner.rollback
+                ? { rollback: (ctx, input, output) => inner.rollback(ctx, input, output) }
+                : {}),
+        };
+        checked.register(wrapped);
+    }
+    return checked;
+}
+/**
+ * Deploy the plan's components to `plan.to`, in dependency order. A
+ * `dependsOn` edge to a component outside the promotion is dropped, the same
+ * way a single-component `chant run --components` runs without its
+ * dependencies; their outputs come from `componentOutputs`. Returns the
+ * driver's result for every outcome, including a failure.
+ */
+export async function runPromotion(options) {
+    const { plan } = options;
+    const names = new Set(plan.items.map((i) => i.component));
+    const targets = options.components
+        .filter((c) => names.has(c.name))
+        .map((c) => ({ ...c, dependsOn: (c.dependsOn ?? []).filter((d) => names.has(d)) }));
+    const expected = new Map(plan.items.map((i) => [i.component, i.digest]));
+    try {
+        return await runInterpretDriver(targets, checkPublishedDigest(options.registry, expected), {
+            env: plan.to,
+            componentOutputs: options.componentOutputs ?? {},
+            // #2574: a gate approval for this promote or rollback is bound to the
+            // release it deploys, as well as the environment and composition.
+            releases: expected,
+            // #3061: the workload's service.version and vcs.ref.head.revision are the earlier release's own.
+            releaseIdentity: (component) => {
+                const item = plan.items.find((i) => i.component === component);
+                return item ? { version: item.digest, revision: item.source.gitSha } : undefined;
+            },
+            ...(options.onProgress ? { onProgress: options.onProgress } : {}),
+            ...(options.gates ? { gates: options.gates } : {}),
+            ...(options.now ? { now: options.now } : {}),
+        });
+    }
+    catch (err) {
+        if (err instanceof DriverRunFailure)
+            return err.result;
+        throw err;
+    }
+}
+/** Who approved the last gate a component passed in this run, if any. */
+export function gateApprover(result) {
+    let approver;
+    for (const record of result?.records ?? []) {
+        if (record.approval)
+            approver = record.approval.resolvedBy;
+    }
+    return approver;
+}
+/** The fields a promote, a rollback and a redeploy record share: the artifact is the earlier release's own. */
+function sharedRecord(item, env, run) {
+    const { source } = item;
+    return {
+        component: item.component,
+        env,
+        digest: item.digest,
+        gitSha: source.gitSha,
+        runId: run.runId,
+        ...(run.runOrigin ? { runOrigin: run.runOrigin } : {}),
+        timestamp: run.timestamp,
+        actor: run.actor,
+        ...(run.approver ? { approver: run.approver } : {}),
+        ...(source.manifestDigest ? { manifestDigest: source.manifestDigest } : {}),
+        ...(source.inputDigest ? { inputDigest: source.inputDigest } : {}),
+    };
+}
+/** Name an earlier record the way `promotedFrom`, `restores` and `redeploys` do. */
+function refTo(record) {
+    return { env: record.env, runId: record.runId, timestamp: record.timestamp };
+}
+/**
+ * The release record a successful promotion appends to the target ledger.
+ * The digest, git sha and archive identities are the source release's own,
+ * since the artifact is the one built there; `promotedFrom` names that
+ * release.
+ */
+export function promotionRecord(item, to, run) {
+    return { ...sharedRecord(item, to, run), promotedFrom: refTo(item.source) };
+}
+/**
+ * The release record a successful rollback appends. Like a promotion's, it
+ * carries the restored release's artifact identities; `restores` names that
+ * release.
+ */
+export function rollbackRecord(item, env, run) {
+    return { ...sharedRecord(item, env, run), restores: refTo(item.source) };
+}
+/**
+ * The release record a successful redeploy appends. It carries the current
+ * release's artifact identities, as a rollback's carries the restored one's;
+ * `redeploys` names that release. The environment's current digest does not
+ * change, and the record says when it was last put back.
+ */
+export function redeployRecord(item, env, run) {
+    return { ...sharedRecord(item, env, run), redeploys: refTo(item.source) };
+}

package/dist/components/registry.js

@@ -0,0 +1,34 @@
+/**
+ * The starter capability registry — one `CapabilityRegistry` pre-seeded with
+ * every verb in the starter set (epic #551, issue #554). All stubs; no cloud
+ * calls except for the #557/#558 AWS leaves (real implementations).
+ *
+ * Phase 2 (#559) promotes this convention to a first-class plugin contract
+ * (./capability-plugin.ts): the starter verb set now ships as
+ * `starterCapabilityPlugin` (./starter-plugin.ts), and `createCapabilityRegistry`
+ * below builds its registry from that plugin's `capabilities()` instead of
+ * registering each verb inline. This is a pure refactor — same kinds, same
+ * capability instances, same registration order — so every existing caller
+ * (the driver, the pilots, ./registry.test.ts) is unaffected. New code
+ * should prefer `buildCapabilityRegistry` (./capability-plugin-loader.ts),
+ * which additionally supports loading third-party capability plugins on top
+ * of this same starter set, the way lexicons are discovered today.
+ */
+import { CapabilityRegistry } from "./capability.js";
+import { starterCapabilityPlugin, STARTER_VERB_FAMILIES } from "./starter-plugin.js";
+/** Build a fresh `CapabilityRegistry` containing every starter-set verb stub. */
+export function createCapabilityRegistry() {
+    const registry = new CapabilityRegistry();
+    for (const capability of starterCapabilityPlugin.capabilities()) {
+        registry.register(capability);
+    }
+    return registry;
+}
+/**
+ * Every `kind` in the starter verb set, grouped by family — useful for tests
+ * and docs generation. Re-exported here (source of truth moved to
+ * ./starter-plugin.ts to avoid a module cycle with `starterCapabilityPlugin`)
+ * so every existing import of `STARTER_VERB_FAMILIES` from this module keeps
+ * working unchanged.
+ */
+export { STARTER_VERB_FAMILIES };

package/dist/components/run-progress.js

@@ -0,0 +1,33 @@
+/**
+ * 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 from a hosted
+ * runtime is a separate, later concern (`chant run status`/`log` already ask
+ * one for the run state it keeps).
+ *
+ * `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).
+ */
+/**
+ * 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, for both the
+ * `--components` driver's `RunProgressEvent`s and the Op path's
+ * `StepRecord`s, chant #1676). 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 = (s) => void process.stdout.write(s)) {
+    return (event) => write(JSON.stringify(event) + "\n");
+}

package/dist/components/sandbox/driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../../src/components/sandbox/driver.ts"],"names":[],"mappings":"AAwCA,MAAM,WAAW,8BAA8B;IAC7C,+EAA+E;IAC/E,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAOD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,8BAA8B,GAAG,MAAM,CAqE7F"}
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../../src/components/sandbox/driver.ts"],"names":[],"mappings":"AA0CA,MAAM,WAAW,8BAA8B;IAC7C,+EAA+E;IAC/E,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAOD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,8BAA8B,GAAG,MAAM,CAqE7F"}