@intentius/chant-lexicon-aws 0.124.31 → 0.124.32

package/dist/components/apply.js

@@ -0,0 +1,752 @@
+/**
+ * apply family — the most cloud-shaped family (see docs/components/cloud-boundary).
+ * AWS leaves for this starter set: cfn-deploy, ecs-update-service,
+ * lambda-deploy, s3-sync, cdn-invalidate, run-migration.
+ *
+ * `cfn-deploy` carries declarative safety options (changeset preview,
+ * `onReplace`, `stageGsi`) — sticky per-resource knowledge (a DynamoDB GSI
+ * updates one at a time; a key-schema change forces replacement) lives inside
+ * the capability, configured by options, never scripted per component. See
+ * docs/components/capabilities.mdx#stickiness-lives-in-the-capability.
+ *
+ * `cfn-deploy` and `ecs-update-service` are real implementations (#557, epic
+ * #551) over the injectable `CloudExecutor` (./cloud-executor.ts).
+ * `lambda-deploy` gained a real implementation in #558 (epic #551) — the one
+ * new capability the fourth, genuinely different validation component
+ * (image-processor-lambda) needed; see ../SPRAWL-VALIDATION.md. `s3-sync`,
+ * `cdn-invalidate`, and `run-migration` are also real over the same executor —
+ * `run-migration` dispatches on its target transport (ECS one-off task, Lambda
+ * invoke, or SSM host command).
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { computePlanDigest } from "@intentius/chant/lifecycle/plan-digest";
+import { defaultCloudExecutor } from "./cloud-executor.js";
+/** CloudFormation's wording when a change set has nothing to apply — the stack
+ * is already current. AWS phrases it "The submitted information didn't contain
+ * changes."; `aws cloudformation deploy` reports "No updates are to be
+ * performed."; keep both plus a bare "no changes" for other backends/Floci. */
+const NO_CHANGE_REASON = /(did ?n['’]?t|does ?n['’]?t|did not|does not) contain changes|no updates are to be performed|no changes/i;
+/**
+ * True when CloudFormation reports the change set has nothing to apply. AWS
+ * surfaces this as a FAILED change set whose `StatusReason` names the empty
+ * diff (executing it then errors); when no reason is available, a FAILED set
+ * with zero proposed changes is the same no-op. A FAILED set with any other
+ * reason is a genuine create failure and must NOT be treated as a no-op.
+ */
+export function isNoopChangeSet(changeSet) {
+    if (changeSet.status !== "FAILED")
+        return false;
+    return changeSet.statusReason
+        ? NO_CHANGE_REASON.test(changeSet.statusReason)
+        : changeSet.changes.length === 0;
+}
+// ── cfn-deploy ───────────────────────────────────────────────────────────────
+/**
+ * Whether a proposed change replaces its resource. CloudFormation's
+ * `Replacement: Conditional` counts: the replacement depends on a value it
+ * resolves only while applying, so a reviewer has to read it as one (#4084).
+ */
+export function cfnChangeReplaces(change) {
+    return change.replacement || change.replacementMode === "Conditional";
+}
+/**
+ * One CloudFormation resource change as a change-set entry (#4084). The
+ * address is the logical id, which is also the entity name the aws
+ * lexicon's graph IR gives the resource, so the entry maps onto its node
+ * (#4022). `Add` is a create, `Modify` an update or (when it replaces) a
+ * replace, `Remove` a delete, `Import` an import that changes nothing else,
+ * and `Dynamic` an update CloudFormation could not describe further.
+ */
+export function cfnChangeEntry(member, change) {
+    const attributes = [...new Set(change.details ?? [])].sort().map((path) => ({ path }));
+    // A change inside a nested stack (#3997) sits under the nested stacks'
+    // logical ids, the way a terraform address sits under its module.
+    const module = change.nestedStack?.length ? change.nestedStack.join("/") : undefined;
+    const base = {
+        member,
+        lexicon: "aws",
+        planner: "chant",
+        address: module ? `${module}/${change.logicalResourceId}` : change.logicalResourceId,
+        type: change.resourceType,
+        name: change.logicalResourceId,
+        ...(module ? { module } : {}),
+        attributes,
+    };
+    switch (change.action) {
+        case "Add":
+            return { ...base, action: "create" };
+        case "Remove":
+            return { ...base, action: "delete", disruption: "destroy" };
+        case "Import":
+            return { ...base, action: "no-op", importing: true };
+        case "Dynamic":
+            return { ...base, action: cfnChangeReplaces(change) ? "replace" : "update", disruption: cfnChangeReplaces(change) ? "replace" : "unknown" };
+        default:
+            return cfnChangeReplaces(change)
+                ? { ...base, action: "replace", disruption: "replace" }
+                : { ...base, action: "update", disruption: "in-place" };
+    }
+}
+/**
+ * The changes `onReplace: "block"` refuses: those CloudFormation says replace
+ * their resource (`Replacement: True`). `run` and `plan` refuse on the same
+ * set, so a plan that passes is one `run` would not block (#3997).
+ */
+function blockedReplacements(changes) {
+    return changes.filter((c) => c.replacement);
+}
+function isCfnPlanArtifact(value) {
+    const v = value;
+    return v?.kind === "cfn-deploy-plan" && typeof v.stack === "string" && typeof v.changesDigest === "string";
+}
+/**
+ * A digest over a change set's changes as entries, independent of the change
+ * set's name and of the order CloudFormation lists them in. A change set with
+ * nothing to apply digests as no entries.
+ */
+export function cfnChangesDigest(stack, changeSet) {
+    const entries = isNoopChangeSet(changeSet) ? [] : changeSet.changes.map((c) => cfnChangeEntry(stack, c));
+    entries.sort((a, b) => a.address.localeCompare(b.address) || a.action.localeCompare(b.action));
+    return computePlanDigest("cfn-deploy-changes", { stack, entries });
+}
+/**
+ * Thrown by `run` when the change set it created proposes other changes than
+ * the change set its plan read (#3997): the stack, the template or the
+ * parameters moved between the plan and the apply. The change set is deleted
+ * unexecuted. `planMoved` is core's mark for a moved plan
+ * (`isPlanMovedError`), so the command that applied it exits 3.
+ */
+export class CfnPlanMovedError extends Error {
+    constructor(stack, planned, now) {
+        super(`cfn-deploy "${stack}": refusing to apply. The change set proposes other changes than the plan that was approved ` +
+            `(planned ${planned}, now ${now}); the stack, its template or its parameters changed since. Plan it again.`);
+        this.stack = stack;
+        this.planned = planned;
+        this.now = now;
+        this.planMoved = true;
+        this.name = "CfnPlanMovedError";
+    }
+}
+/** The template's bytes as a digest, or `null` when it cannot be read here (the change set then reports why). */
+function templateDigest(path) {
+    try {
+        return `sha256:${createHash("sha256").update(readFileSync(path)).digest("hex")}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * What a `cfn-deploy` plan binds: the environment, the stack, the template's
+ * bytes and the parameters as resolved, and the stacks whose outputs were
+ * not known yet. The proposed changes are not in it; they are the member's
+ * entries, which the change-set document's digest binds (#4084).
+ */
+function cfnPlanDigest(ctx, stack, input, parameters, unresolved) {
+    return computePlanDigest("cfn-deploy-plan", {
+        env: ctx.env,
+        stack,
+        template: input.template,
+        templateDigest: templateDigest(input.template),
+        parameters,
+        unresolved,
+    });
+}
+/**
+ * Plan a `cfn-deploy` step without changing the stack (#4084): create a
+ * change set for the template and the resolved parameters, read the changes
+ * it proposes, and delete it without executing it. A stack that does not
+ * exist yet gets a CREATE change set, so every resource reads as a create,
+ * and the empty `REVIEW_IN_PROGRESS` stack CloudFormation made to hold it is
+ * deleted too. A change set with nothing to apply (`isNoopChangeSet`) gives
+ * a member with no entries. A step whose parameters read outputs that are
+ * not known yet, from a stack the same run applies first, creates no change
+ * set: its member gets a hole saying whose outputs it waits on, and no
+ * artifact, so `run` plans it afresh.
+ *
+ * With `onReplace: "block"` (the default), a change set that replaces a
+ * resource fails the plan with {@link CfnReplacementBlockedError}, so the
+ * refusal shows in the pull request's plan rather than at apply (#3997).
+ * Otherwise the result carries a {@link CfnPlanArtifact} that `run` checks
+ * its own change set against.
+ *
+ * The plan answers the outputs the stack will have (#3999), from the
+ * outputs it has now (`DescribeStacks`) and the change set: an output keeps
+ * its value when every resource its template `Value` reads keeps its
+ * physical resource, which an in-place `Modify` does and an `Add`, a
+ * `Remove` or a replacement does not ({@link cfnPlannedOutputs}). An output
+ * that reads a parameter, an import or a condition is known only after
+ * apply. A wrong guess costs a round, never a wrong apply: a dependent whose
+ * input applies as another value is held back and planned again.
+ */
+async function planCfnDeploy(executor, ctx, input) {
+    const stack = input.stack ?? ctx.component;
+    const raw = { ...(input.inputs ?? {}), ...(input.imageRef !== undefined ? { ImageRef: input.imageRef } : {}) };
+    const parameters = {};
+    const missing = [];
+    for (const [key, value] of Object.entries(raw)) {
+        if (value === undefined || value === null) {
+            parameters[key] = null;
+            missing.push(key);
+        }
+        else
+            parameters[key] = typeof value === "string" ? value : JSON.stringify(value);
+    }
+    const unresolved = [...(ctx.unresolvedInputs ?? [])].sort();
+    const planDigest = cfnPlanDigest(ctx, stack, input, parameters, unresolved);
+    const member = (holes) => ({
+        member: stack,
+        lexicon: "aws",
+        planner: "chant",
+        status: "planned",
+        planDigest,
+        holes,
+    });
+    if (unresolved.length > 0 || missing.length > 0) {
+        const reason = unresolved.length > 0
+            ? `inputs from ${unresolved.join(", ")}; re-checked on apply`
+            : `inputs ${missing.sort().join(", ")} are known only at apply; re-checked on apply`;
+        return {
+            member: stack,
+            planDigest,
+            changeSet: { member: member([{ address: stack, type: "AWS::CloudFormation::Stack", reason }]), entries: [] },
+        };
+    }
+    const changeSet = await executor.cloudformation.createChangeSet({
+        stackName: stack,
+        templatePath: input.template,
+        parameters: flattenCfnInputs(input),
+    });
+    try {
+        if (isNoopChangeSet(changeSet)) {
+            const artifact = { kind: "cfn-deploy-plan", stack, changesDigest: cfnChangesDigest(stack, changeSet) };
+            // Nothing to apply, so the outputs the stack has are the ones it will have (#3999).
+            const standing = await standingOutputs(executor, stack);
+            const outputs = standing ? { known: { ...standing }, unknown: [] } : undefined;
+            return { member: stack, planDigest, artifact, changeSet: { member: member([]), entries: [] }, ...(outputs ? { outputs } : {}) };
+        }
+        if (changeSet.status === "FAILED") {
+            throw new Error(`cfn-deploy "${stack}": CloudFormation could not create a change set to plan it${changeSet.statusReason ? `: ${changeSet.statusReason}` : ""}`);
+        }
+        const blocked = blockedReplacements(changeSet.changes);
+        if (blocked.length > 0 && (input.onReplace ?? "block") === "block")
+            throw new CfnReplacementBlockedError(stack, blocked);
+        const entries = changeSet.changes.map((c) => cfnChangeEntry(stack, c));
+        const artifact = { kind: "cfn-deploy-plan", stack, changesDigest: cfnChangesDigest(stack, changeSet) };
+        const outputs = changeSet.stackCreated ? undefined : await plannedStackOutputs(executor, stack, input.template, changeSet.changes);
+        return { member: stack, planDigest, artifact, changeSet: { member: member([]), entries }, ...(outputs ? { outputs } : {}) };
+    }
+    finally {
+        await cleanUpPlanChangeSet(executor, changeSet);
+    }
+}
+/**
+ * Delete a plan's change set, and the empty stack a CREATE change set made
+ * when no stack existed before. A failure to clean up does not fail the
+ * plan: the change set holds nothing that applies, and the next CREATE
+ * change set reuses an empty stack left behind.
+ */
+async function cleanUpPlanChangeSet(executor, changeSet) {
+    try {
+        await executor.cloudformation.deleteChangeSet({ stackName: changeSet.stackName, changeSetName: changeSet.changeSetName });
+    }
+    catch (err) {
+        console.error(`cfn-deploy plan "${changeSet.stackName}": could not delete change set ${changeSet.changeSetName}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (changeSet.stackCreated && executor.cloudformation.deleteStackShell) {
+        try {
+            await executor.cloudformation.deleteStackShell(changeSet.stackName);
+        }
+        catch (err) {
+            console.error(`cfn-deploy plan "${changeSet.stackName}": could not delete the empty stack its CREATE change set made: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+/** The stack's outputs as they stand, or `undefined` when they cannot be read. */
+async function standingOutputs(executor, stack) {
+    try {
+        return { ...(await executor.cloudformation.describeStack(stack)).outputs };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * What the plan says of the stack's outputs once `changes` apply: none to
+ * say for a template with no `Outputs`, which needs no `DescribeStacks`.
+ */
+async function plannedStackOutputs(executor, stack, templatePath, changes) {
+    const template = readTemplate(templatePath);
+    if (!template || typeof template !== "object")
+        return undefined;
+    if (Object.keys(template.Outputs ?? {}).length === 0)
+        return { known: {}, unknown: [] };
+    return cfnPlannedOutputs(template, changes, await standingOutputs(executor, stack));
+}
+/** The template at `path` as JSON, or `undefined` when it cannot be read or parsed here. */
+function readTemplate(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * What a template's `Value` reads (#3999): the logical ids it names through
+ * `Ref`, `Fn::GetAtt` and `Fn::Sub`, and whether it reads anything this plan
+ * cannot follow (`Fn::ImportValue`, a condition's `Fn::If`, or an intrinsic
+ * it does not know).
+ */
+function valueReads(value) {
+    const ids = new Set();
+    let opaque = false;
+    const sub = (text) => {
+        for (const m of text.matchAll(/\$\{([^}!][^}]*)\}/g))
+            ids.add(m[1].split(".")[0]);
+    };
+    const walk = (v) => {
+        if (Array.isArray(v))
+            return v.forEach(walk);
+        if (v === null || typeof v !== "object")
+            return;
+        const entries = Object.entries(v);
+        if (entries.length === 1) {
+            const [key, arg] = entries[0];
+            if (key === "Ref") {
+                if (typeof arg === "string")
+                    ids.add(arg);
+                else
+                    opaque = true;
+                return;
+            }
+            if (key === "Fn::GetAtt") {
+                if (Array.isArray(arg) && typeof arg[0] === "string")
+                    ids.add(arg[0]);
+                else if (typeof arg === "string")
+                    ids.add(arg.split(".")[0]);
+                else
+                    opaque = true;
+                return;
+            }
+            if (key === "Fn::Sub") {
+                if (typeof arg === "string")
+                    sub(arg);
+                else if (Array.isArray(arg) && typeof arg[0] === "string") {
+                    const vars = (arg[1] ?? {});
+                    for (const m of arg[0].matchAll(/\$\{([^}!][^}]*)\}/g))
+                        if (!(m[1] in vars))
+                            ids.add(m[1].split(".")[0]);
+                    walk(vars);
+                }
+                else
+                    opaque = true;
+                return;
+            }
+            if (key === "Fn::Join" || key === "Fn::Select" || key === "Fn::Split" || key === "Fn::Base64")
+                return walk(arg);
+            if (key.startsWith("Fn::") || key === "Condition") {
+                opaque = true;
+                return;
+            }
+        }
+        entries.forEach(([, x]) => walk(x));
+    };
+    walk(value);
+    return { ids, opaque };
+}
+/**
+ * The outputs a stack will have once `changes` apply (#3999), from its
+ * template and the outputs it has now. An output is known, at the value it
+ * has now, when its `Value` reads only pseudo parameters and resources whose
+ * physical resource the change set keeps (no `Add`, `Remove`, `Import` or
+ * `Dynamic`, no replacement, no change in a nested stack under it). One
+ * that reads a parameter, an import or a condition, one the stack does not
+ * have yet, and every output of a template this cannot read, is unknown.
+ * `undefined` when there is no template or no standing stack to read from.
+ */
+export function cfnPlannedOutputs(template, changes, standing) {
+    if (!standing || template === null || typeof template !== "object")
+        return undefined;
+    const t = template;
+    const parameters = new Set(Object.keys(t.Parameters ?? {}));
+    const moved = new Set();
+    for (const c of changes) {
+        const id = c.nestedStack?.[0] ?? c.logicalResourceId;
+        const keeps = !c.nestedStack && c.action === "Modify" && !c.replacement && c.replacementMode !== "True" && c.replacementMode !== "Conditional";
+        if (!keeps)
+            moved.add(id);
+    }
+    const known = {};
+    const unknown = [];
+    for (const [name, output] of Object.entries(t.Outputs ?? {}).sort(([a], [b]) => a.localeCompare(b))) {
+        const { ids, opaque } = valueReads(output?.Value);
+        const stays = !opaque && output?.Condition === undefined && name in standing &&
+            [...ids].every((id) => id.startsWith("AWS::") || (!parameters.has(id) && !moved.has(id)));
+        if (stays)
+            known[name] = standing[name];
+        else
+            unknown.push(name);
+    }
+    return { known, unknown };
+}
+/** Whether a CloudFormation error says the stack does not exist. */
+const STACK_MISSING = /does not exist/i;
+/**
+ * Thrown when a changeset proposes a resource replacement and `onReplace` is
+ * `"block"` (the default) — refusing to apply rather than silently destroying
+ * and recreating a resource, which for a stateful resource (a DynamoDB table,
+ * an RDS instance) means data loss. Carries the specific resources CloudFormation
+ * proposed replacing, so the caller/human reviewing the changeset knows exactly
+ * what was refused.
+ */
+export class CfnReplacementBlockedError extends Error {
+    constructor(stack, replacements) {
+        super(`cfn-deploy "${stack}": refusing changeset — it would replace ${replacements.length} resource(s) ` +
+            `(${replacements.map((r) => r.logicalResourceId).join(", ")}) and onReplace is "block". ` +
+            `Re-run with onReplace: "allow" or "snapshot-first" to proceed.`);
+        this.stack = stack;
+        this.replacements = replacements;
+        this.name = "CfnReplacementBlockedError";
+    }
+}
+/**
+ * Deploy a CloudFormation stack: create a changeset, apply the declarative
+ * safety policy against its proposed changes, then execute (or refuse) it and
+ * wait for the stack to reach a terminal status.
+ *
+ * - `onReplace: "block"` (default) — `CfnReplacementBlockedError` if any
+ *   change requires replacement; the changeset is left/deleted unexecuted.
+ * - `onReplace: "allow"` — executes regardless of replacement.
+ * - `onReplace: "snapshot-first"` — takes a `snapshot-before`-style capture
+ *   (via `executor.cloudformation`'s DynamoDB/RDS-aware snapshot, when the
+ *   replaced resource is a stateful type) before executing.
+ * - `stageGsi` records intent only in this phase (the real add→backfill→remove
+ *   staging is DynamoDB-specific choreography layered on top of the plain
+ *   changeset apply; Phase 1 surfaces the option and passes it through
+ *   uninterpreted rather than half-implementing GSI staging, since staging
+ *   requires a second follow-up deploy the single-step `cfn-deploy` capability
+ *   does not orchestrate on its own).
+ *
+ * Rollback: trigger CloudFormation's native `rollback-stack` — the stack's own
+ * automatic-rollback mechanism restores the last known-good state.
+ */
+export function createCfnDeployCapability(executor = defaultCloudExecutor()) {
+    return {
+        kind: "cfn-deploy",
+        plan(ctx, input) {
+            return planCfnDeploy(executor, ctx, input);
+        },
+        async outputs(ctx, input) {
+            // The outputs the stack has now, for a dependent planned before it
+            // applies (#3183). A stack that does not exist yet has none.
+            try {
+                return (await executor.cloudformation.describeStack(input.stack ?? ctx.component)).outputs;
+            }
+            catch (err) {
+                if (STACK_MISSING.test(err instanceof Error ? err.message : String(err)))
+                    return {};
+                throw err;
+            }
+        },
+        async run(ctx, input) {
+            const stack = input.stack ?? ctx.component;
+            const onReplace = input.onReplace ?? "block";
+            const changeSet = await executor.cloudformation.createChangeSet({
+                stackName: stack,
+                templatePath: input.template,
+                parameters: flattenCfnInputs(input),
+            });
+            // Handed the plan the approver approved (#3997), apply only a change
+            // set that proposes the same changes. Anything else means the stack,
+            // the template or the parameters moved since the plan.
+            const planned = ctx.plans?.[stack];
+            if (isCfnPlanArtifact(planned)) {
+                const now = cfnChangesDigest(stack, changeSet);
+                if (now !== planned.changesDigest) {
+                    await cleanUpPlanChangeSet(executor, changeSet);
+                    throw new CfnPlanMovedError(stack, planned.changesDigest, now);
+                }
+            }
+            // An unchanged stack yields a change set with nothing to apply.
+            // `execute-change-set` rejects it ("The submitted information didn't
+            // contain changes"), which would fail this component and stop the whole
+            // run — so a re-run of `--components all` dies on the first already-current
+            // stack. Treat it as an idempotent no-op success instead: delete the empty
+            // change set and report the stack's current status/outputs so downstream
+            // steps still get real outputs and the run proceeds (#960).
+            if (isNoopChangeSet(changeSet)) {
+                await executor.cloudformation.deleteChangeSet({
+                    stackName: stack,
+                    changeSetName: changeSet.changeSetName,
+                });
+                const { stackStatus, outputs } = await executor.cloudformation.describeStack(stack);
+                return { stackStatus, outputs };
+            }
+            const replacements = blockedReplacements(changeSet.changes);
+            let snapshotId;
+            if (replacements.length > 0 && onReplace === "block") {
+                await executor.cloudformation.deleteChangeSet({
+                    stackName: stack,
+                    changeSetName: changeSet.changeSetName,
+                });
+                throw new CfnReplacementBlockedError(stack, replacements);
+            }
+            if (replacements.length > 0 && onReplace === "snapshot-first") {
+                // Phase 1: record which resources were replaced so the caller/audit
+                // trail has the fact captured; a dedicated `snapshot-before` capability
+                // handles resource-specific (DynamoDB/RDS/OpenSearch) capture and is
+                // composed ahead of `cfn-deploy` in the component's own phase list
+                // when the sticky resource needs a real point-in-time backup.
+                snapshotId = `pending-snapshot:${stack}:${replacements.map((r) => r.logicalResourceId).join(",")}`;
+            }
+            await executor.cloudformation.executeChangeSet({
+                stackName: stack,
+                changeSetName: changeSet.changeSetName,
+            });
+            const { stackStatus, outputs } = await executor.cloudformation.waitForStack(stack);
+            // `waitForStack` returns on any terminal (`*_COMPLETE`/`*_FAILED`) status,
+            // including the failure ones: a create that fails rolls back to
+            // `ROLLBACK_COMPLETE`, an update to `UPDATE_ROLLBACK_COMPLETE`, and hard
+            // failures end in `*_FAILED`. Treating those as success would report a
+            // failed deploy as green (and hand downstream steps an empty `outputs`),
+            // so throw — the same fail-closed contract the rest of the release model
+            // relies on.
+            // A missing status is fail-closed too: Floci's describe-stacks can omit
+            // StackStatus mid-rollback, and `undefined.includes` would throw a TypeError
+            // that masks the real deploy failure (#947).
+            if (!stackStatus || stackStatus.includes("ROLLBACK") || stackStatus.endsWith("_FAILED")) {
+                throw new Error(`cfn-deploy "${stack}": stack reached ${stackStatus ?? "an indeterminate status"} — the deploy failed and was rolled back. Inspect the stack events for the resource that failed to create/update.`);
+            }
+            return { stackStatus, outputs, ...(snapshotId ? { snapshotId } : {}) };
+        },
+        async rollback(ctx, input) {
+            const stack = input.stack ?? ctx.component;
+            try {
+                await executor.cloudformation.rollbackStack(stack);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                // Local emulators (Floci) don't implement RollbackStack → `UnknownAction`.
+                // The stack is already in a terminal failed state; degrade to a clear
+                // message instead of crashing the compensation phase (#947).
+                if (/UnknownAction|not supported/i.test(message)) {
+                    console.error(`cfn-deploy rollback "${stack}": the target doesn't support RollbackStack (a local emulator such as Floci) — skipping automated rollback. Original: ${message}`);
+                    return;
+                }
+                throw err;
+            }
+        },
+    };
+}
+/** Flatten the wired `inputs` map plus `imageRef` (already resolved by the driver) to plain string CloudFormation parameters. */
+function flattenCfnInputs(input) {
+    const params = {};
+    for (const [key, value] of Object.entries(input.inputs ?? {})) {
+        params[key] = typeof value === "string" ? value : JSON.stringify(value);
+    }
+    if (input.imageRef)
+        params.ImageRef = input.imageRef;
+    return Object.keys(params).length > 0 ? params : undefined;
+}
+/** Default `cfn-deploy` capability, backed by the real `CloudExecutor`. */
+export const cfnDeployCapability = createCfnDeployCapability();
+/**
+ * Roll a new task definition/image out to an ECS service via `UpdateService`.
+ * Before the update, `run` reads the service with `describe-services` and
+ * records the task definition it was running in its output. The rollback sends
+ * that previous task definition back (and the previous desired count, when the
+ * step changed it). The step's own `imageRef` is never the rollback target:
+ * it is the revision the step just rolled out, so re-sending it restores
+ * nothing (#2609). When the previous task definition could not be read, the
+ * rollback fails with a message naming the service rather than report a
+ * restore that changed nothing (#2605). A component that needs a specific
+ * task definition restored can still give itself an explicit rollback phase,
+ * such as `rollback-previous` with that `taskDefinition`.
+ */
+export function createEcsUpdateServiceCapability(executor = defaultCloudExecutor()) {
+    return {
+        kind: "ecs-update-service",
+        async run(_ctx, input) {
+            // A failed read only costs the rollback its target; the forward update
+            // still runs, and the rollback then fails saying it has nothing to restore.
+            const before = await executor.ecs.describeService(input.cluster, input.service).catch(() => undefined);
+            const { deploymentId } = await executor.ecs.updateService({
+                cluster: input.cluster,
+                service: input.service,
+                taskDefinition: input.imageRef,
+                desiredCount: input.desiredCount,
+                forceNewDeployment: input.forceNewDeployment,
+            });
+            return {
+                deploymentId,
+                ...(before?.taskDefinition ? { previousTaskDefinition: before.taskDefinition } : {}),
+                ...(before && input.desiredCount !== undefined ? { previousDesiredCount: before.desiredCount } : {}),
+            };
+        },
+        async rollback(_ctx, input, output) {
+            const previous = output?.previousTaskDefinition;
+            if (!previous) {
+                throw new Error(`ecs-update-service rollback: the task definition service "${input.service}" ran before the step ` +
+                    `was not recorded, so there is nothing to roll back to; ` +
+                    `give the component a rollback phase that names the taskDefinition`);
+            }
+            await executor.ecs.rollbackService({
+                cluster: input.cluster,
+                service: input.service,
+                taskDefinition: previous,
+                desiredCount: output?.previousDesiredCount,
+            });
+        },
+    };
+}
+/** Default `ecs-update-service` capability, backed by the real `CloudExecutor`. */
+export const ecsUpdateServiceCapability = createEcsUpdateServiceCapability();
+/**
+ * Update a Lambda function's code to a new container image, wait for the
+ * update to apply, and (by default) publish an immutable version and repoint
+ * `alias` at it — the same digest-promotion invariant every other apply verb
+ * follows (`imageRef`/`codeRef` is a resolved `publish-image` digest, never a
+ * rebuild). Rollback restores whatever version `alias` pointed at before this
+ * step ran (captured up front), repointing the alias back — mirroring
+ * `ecs-update-service`'s best-effort re-apply style rather than a native
+ * automatic rollback (Lambda has none for code updates).
+ */
+export function createLambdaDeployCapability(executor = defaultCloudExecutor()) {
+    const previousVersionByTarget = new Map();
+    return {
+        kind: "lambda-deploy",
+        async run(_ctx, input) {
+            const alias = input.alias ?? "live";
+            if (!previousVersionByTarget.has(input.functionName)) {
+                previousVersionByTarget.set(input.functionName, await executor.lambda.getAliasVersion(input.functionName, alias));
+            }
+            const { functionArn } = await executor.lambda.updateFunctionCode({
+                functionName: input.functionName,
+                imageUri: input.codeRef,
+            });
+            const { status } = await executor.lambda.waitForUpdate(input.functionName);
+            if (status !== "Successful") {
+                throw new Error(`lambda-deploy "${input.functionName}": code update ended "${status}"`);
+            }
+            if (input.publish === false) {
+                return { version: "$LATEST", functionArn };
+            }
+            const published = await executor.lambda.publishVersion({ functionName: input.functionName });
+            await executor.lambda.updateAlias({ functionName: input.functionName, alias, version: published.version });
+            return { version: published.version, functionArn: published.functionArn };
+        },
+        async rollback(_ctx, input) {
+            const alias = input.alias ?? "live";
+            const previousVersion = previousVersionByTarget.get(input.functionName);
+            if (!previousVersion)
+                return; // no prior alias version recorded — nothing to restore.
+            await executor.lambda.updateAlias({ functionName: input.functionName, alias, version: previousVersion });
+        },
+    };
+}
+/** Default `lambda-deploy` capability, backed by the real `CloudExecutor`. */
+export const lambdaDeployCapability = createLambdaDeployCapability();
+/** Sync a directory of static assets to an S3 bucket via `aws s3 sync` (endpoint-aware through the `CloudExecutor`). */
+export function createS3SyncCapability(executor = defaultCloudExecutor()) {
+    return {
+        kind: "s3-sync",
+        rollbackPolicy: "needs-opt-out",
+        async run(_ctx, input) {
+            return executor.s3.sync({ from: input.from, to: input.to, delete: input.delete });
+        },
+    };
+}
+/** Default `s3-sync` capability, backed by the real `CloudExecutor`. */
+export const s3SyncCapability = createS3SyncCapability();
+/** Invalidate CDN cache paths after a content update (e.g. following `s3-sync`), via `aws cloudfront create-invalidation`. */
+export function createCdnInvalidateCapability(executor = defaultCloudExecutor()) {
+    return {
+        kind: "cdn-invalidate",
+        rollbackPolicy: "needs-opt-out",
+        async run(_ctx, input) {
+            return executor.cloudfront.createInvalidation({
+                distributionId: input.distributionId,
+                paths: input.paths ?? ["/*"],
+            });
+        },
+    };
+}
+/** Default `cdn-invalidate` capability, backed by the real `CloudExecutor`. */
+export const cdnInvalidateCapability = createCdnInvalidateCapability();
+/**
+ * A runner that reports its outcome does so as a trailing JSON object
+ * `{"applied":bool,"version":"..."}` — on stdout (host) or in the Lambda
+ * response payload. Parse the last such line; when the runner emits nothing
+ * parseable, fall back to `applied` = "the process exited cleanly" and an empty
+ * version (an ECS task exposes only its exit code — no captured stdout — so it
+ * always takes this fallback).
+ */
+function parseMigrationReport(text, appliedFallback) {
+    for (const line of text.split("\n").map((l) => l.trim()).reverse()) {
+        if (!line.startsWith("{"))
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed.applied === "boolean" || typeof parsed.version === "string") {
+                return { applied: parsed.applied ?? appliedFallback, version: parsed.version ?? "" };
+            }
+        }
+        catch {
+            // not the report line — keep scanning older lines.
+        }
+    }
+    return { applied: appliedFallback, version: "" };
+}
+/**
+ * Run a database/schema migration against a target as a deploy step, dispatching
+ * on the target transport (ECS one-off task, Lambda invoke, or SSM host command)
+ * through the injectable `CloudExecutor`. A non-clean outcome (non-zero exit, a
+ * Lambda `FunctionError`) throws so the phase fails rather than proceeding on an
+ * unmigrated schema.
+ */
+export function createRunMigrationCapability(executor = defaultCloudExecutor()) {
+    return {
+        kind: "run-migration",
+        rollbackPolicy: "needs-opt-out",
+        async run(_ctx, input) {
+            const target = input.target;
+            switch (target.via) {
+                case "ecs-task": {
+                    const { taskArn } = await executor.ecs.runTask({
+                        cluster: target.cluster,
+                        taskDefinition: target.taskDefinition,
+                        container: target.container,
+                        command: target.command,
+                        launchType: target.launchType,
+                        subnets: target.subnets,
+                        securityGroups: target.securityGroups,
+                        assignPublicIp: target.assignPublicIp,
+                    });
+                    const result = await executor.ecs.waitForTask(target.cluster, taskArn);
+                    if (result.exitCode !== 0) {
+                        throw new Error(`run-migration (ecs-task ${target.cluster}): task ${result.lastStatus} with exit ${result.exitCode ?? "none"}${result.stoppedReason ? ` (${result.stoppedReason})` : ""}`);
+                    }
+                    return { applied: true, version: "" };
+                }
+                case "lambda": {
+                    const res = await executor.lambda.invoke({ functionName: target.function, payload: target.payload });
+                    if (res.functionError) {
+                        throw new Error(`run-migration (lambda ${target.function}): ${res.functionError} — ${res.payload.trim()}`);
+                    }
+                    return parseMigrationReport(res.payload, true);
+                }
+                case "host": {
+                    const { stdout, exitCode } = await executor.host.exec({ host: target.host, command: target.command, cwd: target.cwd });
+                    if (exitCode !== 0) {
+                        throw new Error(`run-migration (host ${target.host}): command exited ${exitCode}`);
+                    }
+                    return parseMigrationReport(stdout, true);
+                }
+            }
+        },
+    };
+}
+/** Default `run-migration` capability, backed by the real `CloudExecutor`. */
+export const runMigrationCapability = createRunMigrationCapability();