@intentius/chant-lexicon-aws 0.124.31 → 0.124.33

package/dist/components/cloud-executor.js

@@ -0,0 +1,576 @@
+/**
+ * Injectable cloud I/O boundary for the AWS-leaf capability implementations
+ * (#557, epic #551), living in the aws lexicon so a project's cloud verbs are
+ * contributed by its active lexicon rather than baked into core (see
+ * docs/components/cloud-boundary). Every AWS-leaf capability here goes through
+ * a `CloudExecutor` instead of shelling out directly, so:
+ *
+ *  - production code gets a real executor that shells out to the `aws` and
+ *    `docker` CLIs (this codebase shells out to native CLIs rather than
+ *    depending on AWS SDK v3 packages);
+ *  - tests get a `MockCloudExecutor` (./__tests__/mock-cloud-executor.ts) that
+ *    records calls and returns canned results — no live AWS, no live docker.
+ *
+ * The `docker` client is genuinely agnostic and shared: its type + real
+ * implementation (`realDocker`) come from core; only the AWS-specific clients
+ * (ECR, CloudFormation, ECS, CodeDeploy, Lambda, EMR, SSM host, S3, CloudFront,
+ * snapshot) are defined here.
+ */
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { realDocker } from "@intentius/chant/components/verbs/cloud-executor";
+import { q } from "@intentius/chant/components/verbs/process-runner";
+import { ownershipStackTagsForBody } from "../ownership.js";
+const execFileAsync = promisify(exec);
+// ── Real executor — shells out to `docker`/`aws`; used outside tests ────────
+/**
+ * Inject `--endpoint-url` into an `aws …` command when an endpoint is set, so the
+ * same component can target a local AWS emulator (Floci, LocalStack, …) or any
+ * custom endpoint without a wrapper. We add the flag ourselves rather than rely
+ * on the CLI reading `AWS_ENDPOINT_URL` — older `aws` v2 releases (<2.13) don't.
+ * Non-`aws` commands (docker, …) pass through untouched.
+ */
+export function applyAwsEndpoint(command, endpoint) {
+    if (!endpoint || !/^aws\s/.test(command))
+        return command;
+    return command.replace(/^aws\s/, `aws --endpoint-url ${q(endpoint)} `);
+}
+/**
+ * argv-form of {@link applyAwsEndpoint}: insert `--endpoint-url <endpoint>` right
+ * after `aws` (argv[0]) when an endpoint is set, so a *spawned* `aws …` call (live
+ * acquisition, `graph --live`) targets a local emulator instead of real AWS.
+ * Non-`aws` argvs pass through untouched. Same reason as the string form — older
+ * `aws` v2 (<2.13) ignores `AWS_ENDPOINT_URL`.
+ */
+export function applyAwsEndpointArgv(argv, endpoint) {
+    if (!endpoint || argv[0] !== "aws")
+        return argv;
+    return [argv[0], "--endpoint-url", endpoint, ...argv.slice(1)];
+}
+function run(command) {
+    return execFileAsync(applyAwsEndpoint(command, process.env.AWS_ENDPOINT_URL), {
+        maxBuffer: 64 * 1024 * 1024,
+    });
+}
+const realEcr = {
+    async login(registry) {
+        await run(`aws ecr get-login-password | docker login --username AWS --password-stdin ${q(registry)}`);
+    },
+};
+/**
+ * CREATE for a stack that doesn't exist (or is stuck in REVIEW_IN_PROGRESS from
+ * a prior unexecuted CREATE), else UPDATE; and whether a stack existed at all.
+ */
+async function cfnChangeSetType(stackName) {
+    try {
+        const { stdout } = await run(`aws cloudformation describe-stacks --stack-name ${q(stackName)}`);
+        const status = JSON.parse(stdout).Stacks?.[0]?.StackStatus;
+        return { type: status === "REVIEW_IN_PROGRESS" ? "CREATE" : "UPDATE", existed: true };
+    }
+    catch {
+        return { type: "CREATE", existed: false }; // describe-stacks errors when the stack doesn't exist
+    }
+}
+/**
+ * The `--capabilities` a deploy needs for a template. `CAPABILITY_NAMED_IAM` is
+ * always required (chant emits named IAM roles); `CAPABILITY_AUTO_EXPAND` is added
+ * whenever the template declares a top-level `Transform` macro (e.g.
+ * `AWS::SecretsManager-2020-07-23` for a HostedRotationLambda rotation, or SAM) —
+ * the macro expands into nested stacks/resources during change-set creation, and
+ * CloudFormation refuses without the acknowledgement.
+ */
+export function awsDeployCapabilities(template) {
+    return awsDeployCapabilityList(template).join(" ");
+}
+/** {@link awsDeployCapabilities} as a list, for the CFN API's `Capabilities.member.N` params. */
+export function awsDeployCapabilityList(template) {
+    return template.Transform !== undefined
+        ? ["CAPABILITY_NAMED_IAM", "CAPABILITY_AUTO_EXPAND"]
+        : ["CAPABILITY_NAMED_IAM"];
+}
+/**
+ * {@link awsDeployCapabilityList} for a raw template body. A body that isn't
+ * JSON gets the default list; the deploy itself reports the real problem.
+ */
+export function awsDeployCapabilitiesForBody(body) {
+    try {
+        return awsDeployCapabilityList(JSON.parse(body));
+    }
+    catch {
+        return ["CAPABILITY_NAMED_IAM"];
+    }
+}
+/** Whether a template body declares an `AWS::CloudFormation::Stack` resource. A body that isn't JSON declares none here. */
+export function templateHasNestedStacks(body) {
+    try {
+        const resources = JSON.parse(body).Resources ?? {};
+        return Object.values(resources).some((r) => r?.Type === "AWS::CloudFormation::Stack");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A described change set's changes as {@link CfnChange}s, and the changes of
+ * every nested change set it names, each marked with the nested stacks it
+ * sits in (#3997). `describeNested` describes a nested change set by its ARN.
+ */
+export async function readCfnChanges(described, describeNested, nestedStack = []) {
+    const out = [];
+    for (const c of described.Changes ?? []) {
+        const rc = c.ResourceChange;
+        out.push({
+            action: rc.Action,
+            logicalResourceId: rc.LogicalResourceId,
+            resourceType: rc.ResourceType,
+            replacement: rc.Replacement === "True",
+            ...(rc.Replacement === "True" || rc.Replacement === "False" || rc.Replacement === "Conditional" ? { replacementMode: rc.Replacement } : {}),
+            details: rc.Details?.map((d) => d.Target?.Name).filter((x) => !!x),
+            ...(nestedStack.length > 0 ? { nestedStack } : {}),
+        });
+        if (rc.ResourceType === "AWS::CloudFormation::Stack" && rc.ChangeSetId) {
+            out.push(...(await readCfnChanges(await describeNested(rc.ChangeSetId), describeNested, [...nestedStack, rc.LogicalResourceId])));
+        }
+    }
+    return out;
+}
+const realCloudFormation = {
+    async createChangeSet(args) {
+        const changeSetName = `cs-${Date.now()}`;
+        const params = Object.entries(args.parameters ?? {})
+            .map(([k, v]) => `ParameterKey=${k},ParameterValue=${v}`)
+            .join(" ");
+        const paramFlag = params ? ` --parameters ${params}` : "";
+        // A change set defaults to type UPDATE, which fails on a stack that doesn't
+        // exist yet ("Stack ... does not exist"). Pick CREATE for a new stack, and
+        // for one still in REVIEW_IN_PROGRESS (a prior CREATE change set never
+        // executed), mirroring what `aws cloudformation deploy` does under the hood.
+        const { type: changeSetType, existed } = await cfnChangeSetType(args.stackName);
+        let body = "";
+        try {
+            body = readFileSync(args.templatePath, "utf8");
+        }
+        catch { /* unreadable template — create-change-set reports it */ }
+        const capabilities = awsDeployCapabilitiesForBody(body).join(" ");
+        // The template's ownership marker becomes the STACK's own tags (#1222) —
+        // the identity stack-level teardown verifies before a DeleteStack. Same
+        // source as the applier's `Tags.member.N`: `Metadata["chant:ownership"]`.
+        const stackTags = Object.entries(ownershipStackTagsForBody(body))
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => q(`Key=${k},Value=${v}`))
+            .join(" ");
+        const tagsFlag = stackTags ? ` --tags ${stackTags}` : "";
+        // A template with nested stacks gets their change sets too, so a plan
+        // shows what changes inside each child, not only that the child changes
+        // (#3997). Executing the root change set executes the nested ones.
+        const nestedFlag = templateHasNestedStacks(body) ? " --include-nested-stacks" : "";
+        await run(`aws cloudformation create-change-set --stack-name ${q(args.stackName)} --change-set-name ${q(changeSetName)} ` +
+            `--change-set-type ${changeSetType} ` +
+            `--template-body file://${args.templatePath} --capabilities ${capabilities}${paramFlag}${tagsFlag}${nestedFlag}`);
+        await run(`aws cloudformation wait change-set-create-complete --stack-name ${q(args.stackName)} --change-set-name ${q(changeSetName)}`).catch(() => undefined); // "no changes" also lands here; describe below reports the real status.
+        const { stdout } = await run(`aws cloudformation describe-change-set --stack-name ${q(args.stackName)} --change-set-name ${q(changeSetName)}`);
+        const described = JSON.parse(stdout);
+        const describeNested = async (changeSetId) => JSON.parse((await run(`aws cloudformation describe-change-set --change-set-name ${q(changeSetId)}`)).stdout);
+        return {
+            changeSetName,
+            stackName: args.stackName,
+            status: described.Status,
+            statusReason: described.StatusReason ?? undefined,
+            isCreate: described.Status === "CREATE_COMPLETE" && !described.Changes?.length,
+            changeSetType,
+            stackCreated: !existed,
+            changes: await readCfnChanges(described, describeNested),
+        };
+    },
+    async executeChangeSet(args) {
+        await run(`aws cloudformation execute-change-set --stack-name ${q(args.stackName)} --change-set-name ${q(args.changeSetName)}`);
+    },
+    async deleteChangeSet(args) {
+        await run(`aws cloudformation delete-change-set --stack-name ${q(args.stackName)} --change-set-name ${q(args.changeSetName)}`);
+    },
+    async describeStack(stackName) {
+        const { stdout } = await run(`aws cloudformation describe-stacks --stack-name ${q(stackName)}`);
+        const described = JSON.parse(stdout);
+        const stack = described.Stacks[0];
+        const outputs = {};
+        for (const o of stack?.Outputs ?? [])
+            outputs[o.OutputKey] = o.OutputValue;
+        return { stackStatus: stack?.StackStatus ?? "UNKNOWN", outputs };
+    },
+    async waitForStack(stackName, opts) {
+        const intervalMs = opts?.intervalMs ?? 10000;
+        const deadline = opts?.timeoutMs ? Date.now() + opts.timeoutMs : undefined;
+        while (true) {
+            const status = await realCloudFormation.describeStack(stackName);
+            if (!status.stackStatus.endsWith("_IN_PROGRESS"))
+                return status;
+            if (deadline && Date.now() > deadline)
+                throw new Error(`waitForStack "${stackName}" timed out`);
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        }
+    },
+    async rollbackStack(stackName) {
+        await run(`aws cloudformation rollback-stack --stack-name ${q(stackName)}`);
+    },
+    async deleteStackShell(stackName) {
+        let status;
+        try {
+            status = (await realCloudFormation.describeStack(stackName)).stackStatus;
+        }
+        catch {
+            return false; // gone already
+        }
+        if (status !== "REVIEW_IN_PROGRESS")
+            return false;
+        await run(`aws cloudformation delete-stack --stack-name ${q(stackName)}`);
+        return true;
+    },
+};
+/** Deployment id from an ECS `update-service` response. Tolerant of Floci, whose
+ * `service` omits `deployments` entirely (real AWS always includes it) — guards
+ * the index, not just `.id` (#937). Exported for testing. */
+export function ecsDeploymentId(described) {
+    return described.service.deployments?.[0]?.id ?? "";
+}
+/** Whether an ECS service is steady (running == desired, ≤1 active deployment).
+ * Tolerant of Floci's missing `deployments` field. Exported for testing. */
+export function ecsServiceStable(svc) {
+    const running = svc?.runningCount ?? 0;
+    const desired = svc?.desiredCount ?? 0;
+    return running === desired && (svc?.deployments?.length ?? 0) <= 1;
+}
+const realEcs = {
+    async updateService(args) {
+        const parts = [`aws ecs update-service`, `--cluster ${q(args.cluster)}`, `--service ${q(args.service)}`];
+        if (args.taskDefinition)
+            parts.push(`--task-definition ${q(args.taskDefinition)}`);
+        if (args.desiredCount !== undefined)
+            parts.push(`--desired-count ${args.desiredCount}`);
+        if (args.forceNewDeployment)
+            parts.push(`--force-new-deployment`);
+        const { stdout } = await run(parts.join(" "));
+        const described = JSON.parse(stdout);
+        return { deploymentId: ecsDeploymentId(described) };
+    },
+    async describeService(cluster, service) {
+        const { stdout } = await run(`aws ecs describe-services --cluster ${q(cluster)} --services ${q(service)}`);
+        const described = JSON.parse(stdout);
+        const svc = described.services?.[0];
+        return {
+            runningCount: svc?.runningCount ?? 0,
+            desiredCount: svc?.desiredCount ?? 0,
+            stable: ecsServiceStable(svc),
+            ...(svc?.taskDefinition ? { taskDefinition: svc.taskDefinition } : {}),
+        };
+    },
+    async rollbackService(args) {
+        // The executor records no previous task definition itself, so a rollback
+        // without one would leave the service as it is and still report success (#2605).
+        // Callers read it with describeService before they update (#2609).
+        if (!args.taskDefinition) {
+            throw new Error(`ecs rollback of service "${args.service}" on "${args.cluster}" needs the taskDefinition to roll back to`);
+        }
+        await realEcs.updateService(args);
+    },
+    async runTask(args) {
+        const parts = [
+            `aws ecs run-task`,
+            `--cluster ${q(args.cluster)}`,
+            `--task-definition ${q(args.taskDefinition)}`,
+            `--launch-type ${args.launchType ?? "FARGATE"}`,
+        ];
+        if (args.subnets?.length) {
+            const net = {
+                awsvpcConfiguration: {
+                    subnets: args.subnets,
+                    securityGroups: args.securityGroups ?? [],
+                    assignPublicIp: args.assignPublicIp ? "ENABLED" : "DISABLED",
+                },
+            };
+            parts.push(`--network-configuration ${q(JSON.stringify(net))}`);
+        }
+        if (args.command?.length) {
+            const overrides = { containerOverrides: [{ name: args.container ?? "", command: args.command }] };
+            parts.push(`--overrides ${q(JSON.stringify(overrides))}`);
+        }
+        const { stdout } = await run(parts.join(" "));
+        const described = JSON.parse(stdout);
+        const taskArn = described.tasks[0]?.taskArn;
+        if (!taskArn)
+            throw new Error(`ecs run-task on "${args.cluster}" started no task: ${JSON.stringify(described.failures ?? [])}`);
+        return { taskArn };
+    },
+    async waitForTask(cluster, taskArn) {
+        await run(`aws ecs wait tasks-stopped --cluster ${q(cluster)} --tasks ${q(taskArn)}`);
+        const { stdout } = await run(`aws ecs describe-tasks --cluster ${q(cluster)} --tasks ${q(taskArn)}`);
+        const described = JSON.parse(stdout);
+        const task = described.tasks[0];
+        return {
+            lastStatus: task?.lastStatus ?? "UNKNOWN",
+            exitCode: task?.containers?.[0]?.exitCode,
+            ...(task?.stoppedReason ? { stoppedReason: task.stoppedReason } : {}),
+        };
+    },
+};
+const realCodeDeploy = {
+    async createDeployment(args) {
+        const revisionFlag = args.revision.type === "s3"
+            ? `--s3-location bundleType=zip,bucket=${q(args.revision.uri.replace("s3://", "").split("/")[0])},key=${q(args.revision.uri.replace("s3://", "").split("/").slice(1).join("/"))}`
+            : `--github-location repository=${q(args.revision.repository)},commitId=${q(args.revision.commitId)}`;
+        const { stdout } = await run(`aws deploy create-deployment --application-name ${q(args.application)} ` +
+            `--deployment-group-name ${q(args.deploymentGroup)} --revision revisionType=${args.revision.type === "s3" ? "S3" : "GitHub"},${revisionFlag}`);
+        const described = JSON.parse(stdout);
+        return { deploymentId: described.deploymentId };
+    },
+    async waitForDeployment(deploymentId, opts) {
+        const intervalMs = opts?.intervalMs ?? 10000;
+        const deadline = opts?.timeoutMs ? Date.now() + opts.timeoutMs : undefined;
+        while (true) {
+            const { stdout } = await run(`aws deploy get-deployment --deployment-id ${q(deploymentId)}`);
+            const described = JSON.parse(stdout);
+            const status = described.deploymentInfo.status;
+            if (["Succeeded", "Failed", "Stopped"].includes(status))
+                return { status, terminal: true };
+            if (deadline && Date.now() > deadline)
+                throw new Error(`waitForDeployment "${deploymentId}" timed out`);
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        }
+    },
+    async stopAndRollback(deploymentId) {
+        // CodeDeploy's native auto-rollback-on-failure already reverts to the last
+        // known-good revision when a deployment fails; explicitly stopping with
+        // rollback covers the case where the caller is compensating a deployment
+        // that is still in flight.
+        await run(`aws deploy stop-deployment --deployment-id ${q(deploymentId)} --auto-rollback-enabled`);
+    },
+};
+const realHost = {
+    async copyFile(args) {
+        // SSM Run Command, per the same transport `copy-to-host` documents: stage
+        // the tarball via an S3 hop (`aws s3 cp` then a remote `aws s3 cp` inside
+        // the command document) is the common pattern for files too large for an
+        // inline SSM document; kept to a single conceptual step here since the
+        // executor boundary is what tests substitute, not this shell recipe.
+        await run(`aws ssm send-command --instance-ids ${q(args.host)} --document-name AWS-RunShellScript ` +
+            `--parameters ${q(JSON.stringify({ commands: [`aws s3 cp ${args.from} ${args.to}`] }))}`);
+    },
+    async dockerLoad(args) {
+        const { stdout } = await run(`aws ssm send-command --instance-ids ${q(args.host)} --document-name AWS-RunShellScript ` +
+            `--parameters ${q(JSON.stringify({ commands: [`docker load -i ${args.path}`] }))}`);
+        const match = stdout.match(/[Ll]oaded image(?: ID)?:\s*(\S+)/);
+        return { digest: match?.[1] ?? stdout.trim() };
+    },
+    async exec(args) {
+        const command = args.cwd ? `cd ${args.cwd} && ${args.command}` : args.command;
+        const { stdout: idOut } = await run(`aws ssm send-command --instance-ids ${q(args.host)} --document-name AWS-RunShellScript ` +
+            `--parameters ${q(JSON.stringify({ commands: [command] }))} --query 'Command.CommandId' --output text`);
+        const commandId = idOut.trim();
+        for (;;) {
+            await sleep(2000);
+            const { stdout } = await run(`aws ssm get-command-invocation --command-id ${q(commandId)} --instance-id ${q(args.host)} --output json`).catch(() => ({ stdout: "" }));
+            if (!stdout)
+                continue; // invocation not registered yet
+            const inv = JSON.parse(stdout);
+            if (["Success", "Failed", "Cancelled", "TimedOut"].includes(inv.Status)) {
+                if (inv.Status !== "Success") {
+                    throw new Error(`remote-exec on ${args.host} ${inv.Status}: ${inv.StandardErrorContent?.trim() ?? ""}`);
+                }
+                return { stdout: inv.StandardOutputContent ?? "", exitCode: inv.ResponseCode ?? 0 };
+            }
+        }
+    },
+};
+const realLambda = {
+    async updateFunctionCode(args) {
+        const { stdout } = await run(`aws lambda update-function-code --function-name ${q(args.functionName)} --image-uri ${q(args.imageUri)}`);
+        const described = JSON.parse(stdout);
+        return { functionArn: described.FunctionArn };
+    },
+    async waitForUpdate(functionName) {
+        await run(`aws lambda wait function-updated-v2 --function-name ${q(functionName)}`);
+        const { stdout } = await run(`aws lambda get-function --function-name ${q(functionName)}`);
+        const described = JSON.parse(stdout);
+        return { status: described.Configuration.LastUpdateStatus };
+    },
+    async publishVersion(args) {
+        const { stdout } = await run(`aws lambda publish-version --function-name ${q(args.functionName)}`);
+        const described = JSON.parse(stdout);
+        return { version: described.Version, functionArn: described.FunctionArn };
+    },
+    async updateAlias(args) {
+        const { stdout } = await run(`aws lambda update-alias --function-name ${q(args.functionName)} --name ${q(args.alias)} --function-version ${q(args.version)}`);
+        const described = JSON.parse(stdout);
+        return { aliasArn: described.AliasArn };
+    },
+    async getAliasVersion(functionName, alias) {
+        try {
+            const { stdout } = await run(`aws lambda get-alias --function-name ${q(functionName)} --name ${q(alias)}`);
+            const described = JSON.parse(stdout);
+            return described.FunctionVersion;
+        }
+        catch {
+            return undefined; // alias does not exist yet (first deploy) — nothing to restore on rollback.
+        }
+    },
+    async invoke(args) {
+        // `aws lambda invoke` writes the response payload to a file arg and its
+        // metadata (StatusCode/FunctionError) to stdout, so use a throwaway temp
+        // dir for both the request payload (fileb:// — raw bytes, version-agnostic)
+        // and the response, and clean it up regardless of outcome.
+        const dir = mkdtempSync(join(tmpdir(), "chant-lambda-"));
+        const outFile = join(dir, "response.json");
+        try {
+            let payloadFlag = "";
+            if (args.payload !== undefined) {
+                const payloadFile = join(dir, "payload.json");
+                writeFileSync(payloadFile, args.payload);
+                payloadFlag = ` --payload fileb://${payloadFile}`;
+            }
+            const { stdout } = await run(`aws lambda invoke --function-name ${q(args.functionName)}${payloadFlag} ${q(outFile)}`);
+            const meta = JSON.parse(stdout);
+            return {
+                statusCode: meta.StatusCode,
+                payload: readFileSync(outFile, "utf8"),
+                ...(meta.FunctionError ? { functionError: meta.FunctionError } : {}),
+            };
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    },
+};
+const realEmr = {
+    async startJobRun(args) {
+        const parts = [
+            `aws emr-serverless start-job-run`,
+            `--application-id ${q(args.clusterOrApplicationId)}`,
+            `--execution-role-arn ${q(args.executionRoleArn ?? "")}`,
+            `--job-driver ${q(JSON.stringify({ sparkSubmit: { entryPoint: args.jar, entryPointArguments: args.args ?? [] } }))}`,
+        ];
+        const { stdout } = await run(parts.join(" "));
+        const described = JSON.parse(stdout);
+        return { runId: described.jobRunId };
+    },
+    async addStep(args) {
+        const step = {
+            Name: args.name,
+            ActionOnFailure: args.actionOnFailure ?? "CONTINUE",
+            HadoopJarStep: { Jar: args.jar, Args: args.args ?? [] },
+        };
+        const { stdout } = await run(`aws emr add-steps --cluster-id ${q(args.clusterId)} --steps ${q(JSON.stringify([step]))}`);
+        const described = JSON.parse(stdout);
+        const stepId = described.StepIds?.[0];
+        if (!stepId)
+            throw new Error(`emr add-steps on "${args.clusterId}" returned no step id`);
+        return { stepId };
+    },
+    async describeJobRun(runId) {
+        const { stdout } = await run(`aws emr-serverless get-job-run --job-run-id ${q(runId)}`);
+        const described = JSON.parse(stdout);
+        return { state: described.jobRun.state };
+    },
+    async waitForJobRun(runId, opts) {
+        const intervalMs = opts?.intervalMs ?? 10000;
+        const deadline = opts?.timeoutMs ? Date.now() + opts.timeoutMs : undefined;
+        const terminal = new Set(["COMPLETED", "FAILED", "CANCELLED"]);
+        while (true) {
+            const status = await realEmr.describeJobRun(runId);
+            if (terminal.has(status.state))
+                return status;
+            if (deadline && Date.now() > deadline)
+                throw new Error(`waitForJobRun "${runId}" timed out`);
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        }
+    },
+    async cancelJobRun(runId) {
+        await run(`aws emr-serverless cancel-job-run --job-run-id ${q(runId)}`);
+    },
+};
+const realS3 = {
+    async sync(args) {
+        const flags = args.delete ? " --delete" : "";
+        const { stdout } = await run(`aws s3 sync ${q(args.from)} ${q(args.to)}${flags} --no-progress`);
+        // `aws s3 sync` prints one `upload: …` / `delete: …` line per object touched.
+        const count = (re) => stdout.split("\n").filter((l) => re.test(l)).length;
+        return { uploaded: count(/^upload:/), deleted: count(/^delete:/) };
+    },
+    async cp(args) {
+        await run(`aws s3 cp ${q(args.from)} ${q(args.to)} --no-progress`);
+    },
+};
+const realCloudFront = {
+    async createInvalidation(args) {
+        const paths = args.paths.map(q).join(" ");
+        const { stdout } = await run(`aws cloudfront create-invalidation --distribution-id ${q(args.distributionId)} --paths ${paths}`);
+        const id = JSON.parse(stdout).Invalidation?.Id;
+        return { invalidationId: id ?? "" };
+    },
+};
+const realSnapshot = {
+    async create({ resource, resourceKind }) {
+        const id = `${resource}-${Date.now()}`;
+        switch (resourceKind) {
+            case "dynamodb-table": {
+                const { stdout } = await run(`aws dynamodb create-backup --table-name ${q(resource)} --backup-name ${q(id)} --query 'BackupDetails.BackupArn' --output text`);
+                return { snapshotId: stdout.trim() };
+            }
+            case "rds-instance": {
+                const { stdout } = await run(`aws rds create-db-snapshot --db-instance-identifier ${q(resource)} --db-snapshot-identifier ${q(id)} --query 'DBSnapshot.DBSnapshotArn' --output text`);
+                return { snapshotId: stdout.trim() };
+            }
+            case "ebs-volume": {
+                const { stdout } = await run(`aws ec2 create-snapshot --volume-id ${q(resource)} --description ${q(`chant snapshot-before ${id}`)} --query 'SnapshotId' --output text`);
+                return { snapshotId: stdout.trim() };
+            }
+            case "opensearch-domain":
+                // OpenSearch manual snapshots require a pre-registered S3 repository + a
+                // signed _snapshot REST call, not a one-shot CLI verb — out of scope here.
+                throw new Error(`snapshot-before: opensearch-domain needs a registered S3 snapshot repository; not yet supported (resource "${resource}")`);
+        }
+    },
+    async restore({ resource, snapshotId }) {
+        // Dispatch by the snapshot-id shape produced by `create` above.
+        if (snapshotId.includes(":dynamodb:") || snapshotId.includes("/backup/")) {
+            await run(`aws dynamodb restore-table-from-backup --target-table-name ${q(resource)} --backup-arn ${q(snapshotId)}`);
+            await run(`aws dynamodb wait table-exists --table-name ${q(resource)}`);
+            return;
+        }
+        if (snapshotId.includes(":rds:") || snapshotId.startsWith("rds:")) {
+            await run(`aws rds restore-db-instance-from-db-snapshot --db-instance-identifier ${q(resource)} --db-snapshot-identifier ${q(snapshotId)}`);
+            await run(`aws rds wait db-instance-available --db-instance-identifier ${q(resource)}`);
+            return;
+        }
+        throw new Error(`rollback-previous: cannot infer the restore mechanism from snapshot id "${snapshotId}" (expected a DynamoDB or RDS backup ARN)`);
+    },
+};
+/** Build a `CloudExecutor` that shells out to real `docker`/`aws` CLIs and probes real bolt ports. Never used in tests. */
+export function realCloudExecutor() {
+    return {
+        docker: realDocker,
+        ecr: realEcr,
+        cloudformation: realCloudFormation,
+        ecs: realEcs,
+        codeDeploy: realCodeDeploy,
+        lambda: realLambda,
+        emr: realEmr,
+        host: realHost,
+        s3: realS3,
+        cloudfront: realCloudFront,
+        snapshot: realSnapshot,
+    };
+}
+/** Lazily-constructed process-wide default so importing a capability module never shells out at import time. */
+let defaultExecutor;
+/** The default `CloudExecutor` each capability factory falls back to when none is supplied. */
+export function defaultCloudExecutor() {
+    if (!defaultExecutor)
+        defaultExecutor = realCloudExecutor();
+    return defaultExecutor;
+}
+/** Sleep for `ms`. Shared by every polling capability (`wait-*`) between attempts. */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}