@aws-blocks/core 0.1.13 → 0.1.18

package/dist/scripts/console.js

@@ -3,6 +3,34 @@
 import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { trackCommand } from '../telemetry/trackCommand.js';
+function resolveRegion() {
+    const fromEnv = process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION;
+    if (fromEnv)
+        return fromEnv;
+    try {
+        const fromConfig = execFileSync('aws', ['configure', 'get', 'region'], { encoding: 'utf-8' }).trim();
+        if (fromConfig)
+            return fromConfig;
+    }
+    catch {
+        // aws CLI not configured — fall through to default.
+    }
+    return 'us-east-1';
+}
+/** Launch the URL in the default browser. Best-effort: no opener (headless/CI) is not a failure. */
+function openInBrowser(url) {
+    const opener = process.platform === 'darwin' ? 'open' :
+        process.platform === 'win32' ? 'cmd' :
+            'xdg-open';
+    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    try {
+        execFileSync(opener, args, { stdio: 'ignore' });
+    }
+    catch {
+        // Headless environment (CI, remote shell) — the URL is already printed above.
+        console.log('(Could not launch a browser automatically — open the URL above manually.)');
+    }
+}
 export async function openConsole(options) {
     return trackCommand('console', async () => {
         let stackName;
@@ -16,10 +44,10 @@ export async function openConsole(options) {
         else {
             throw new Error('Must provide either stackId or outputsFile');
         }
-        const region = execFileSync('aws', ['configure', 'get', 'region'], { encoding: 'utf-8' }).trim() || 'us-east-1';
+        const region = resolveRegion();
         const stackUrl = `https://${region}.console.aws.amazon.com/cloudformation/home?region=${region}#/stacks?filteringText=${encodeURIComponent(stackName)}`;
         console.log('Opening AWS Console...');
         console.log(stackUrl);
-        execFileSync('open', [stackUrl], { stdio: 'inherit' });
+        openInBrowser(stackUrl);
     });
 }

package/dist/scripts/deploy-stream.d.ts

@@ -0,0 +1,181 @@
+/** What to do with a signal that arrives while a deploy is in flight. */
+export type DeploySignalAction = 'defer' | 'abort';
+export interface DeploySignalResponse {
+    action: DeploySignalAction;
+    /** Operator-facing line explaining what happened and how to force an abort. */
+    message: string;
+    /**
+     * True when this signal is a duplicate delivery of one the operator already
+     * sent (see {@link SIGNAL_COALESCE_MS}), so the caller can skip logging it
+     * twice.
+     */
+    coalesced?: boolean;
+}
+/** Signals whose delivery we take over while a deploy is in flight. */
+export declare const DEPLOY_SIGNALS: readonly NodeJS.Signals[];
+/** Default gap (ms) of silence after which the runner prints a progress heartbeat. */
+export declare const DEFAULT_HEARTBEAT_MS = 30000;
+/** Grace (ms) given to the child tree to exit after an operator-requested abort. */
+export declare const ABORT_GRACE_MS = 10000;
+/**
+ * Grace (ms) we wait after the child exits for its stdout/stderr pipes to end,
+ * so the last CloudFormation lines are relayed before we resolve. Bounded
+ * because a lingering grandchild could hold the pipe open forever; losing a
+ * trailing line is strictly better than hanging a finished deploy.
+ */
+export declare const STREAM_FLUSH_GRACE_MS = 2000;
+/**
+ * Window (ms) in which repeated SIGTERMs count as ONE operator request.
+ *
+ * A single external signal reaches this process more than once. `npm run deploy`
+ * runs `npm -> sh -> tsx -> node`, so a process-group SIGTERM is delivered to
+ * the node process directly AND relayed to it a second time by `tsx`, which
+ * forwards SIGTERM/SIGINT to its child. Measured on a real deploy: one
+ * `kill -TERM -<pgid>` produced two SIGTERMs about 50ms apart. Without this
+ * window the second delivery is read as "the operator insisted" and the deploy
+ * is abandoned, which is the exact failure this module exists to prevent.
+ *
+ * 2s is far longer than a delivery burst (tens of ms) and far shorter than a
+ * deliberate repeat (a human running `kill` twice, or a supervisor's
+ * SIGTERM-then-escalate cycle), so both intents stay distinguishable.
+ */
+export declare const SIGNAL_COALESCE_MS = 2000;
+/**
+ * Decide how to answer a signal that arrives while CloudFormation is still
+ * converging. This is the whole "decouple the CLI lifecycle from the in-flight
+ * deploy" policy, kept pure so it can be asserted directly.
+ *
+ * - `SIGHUP` → always `defer`. A hangup means the terminal or parent shell went
+ *   away (a backgrounded `npm run deploy &`, a closed SSH session). The deploy
+ *   is server-side work that is already paid for; killing the CLI here is what
+ *   produced the phantom failures, so we keep streaming instead. Duplicate
+ *   deliveries inside {@link SIGNAL_COALESCE_MS} are coalesced so one hangup
+ *   logs one line, not one per delivery.
+ * - `SIGTERM` → `defer` the first time. A lone SIGTERM is almost always
+ *   process-group collateral (a harness reaping the parent shell, a supervisor
+ *   tidying up) rather than a deliberate "stop the deploy", so it only warns.
+ *   Repeats inside {@link SIGNAL_COALESCE_MS} are duplicate *deliveries* of that
+ *   same signal (the group delivers it, then `tsx` relays it) and are coalesced
+ *   into the first. A SIGTERM after that window is a deliberate repeat and
+ *   aborts. A SIGKILL follow-up (`docker stop`, most CI cancels) is uncatchable
+ *   and still ends the process immediately, so this cannot wedge a shutdown.
+ * - `SIGINT` → always `abort`. Ctrl-C is unambiguous, interactive intent, so it
+ *   stays responsive on the first press.
+ *
+ * @param signal - the signal received.
+ * @param msSinceFirstDeferral - ms since the first deferral of *this* signal, or
+ *   `null` when this signal has not been deferred yet. Each signal is tracked
+ *   separately, so a deferred SIGHUP never consumes the SIGTERM abort budget
+ *   (and a repeated SIGHUP is deduped the same way a repeated SIGTERM is).
+ * @param coalesceWindowMs - see {@link SIGNAL_COALESCE_MS}.
+ */
+export declare function decideSignalResponse(signal: NodeJS.Signals, msSinceFirstDeferral: number | null, coalesceWindowMs?: number): DeploySignalResponse;
+/**
+ * Split a byte stream into whole lines across chunk boundaries.
+ *
+ * The child's output arrives in arbitrary chunks, so a naive
+ * `chunk.toString().split('\n')` emits torn lines (and drops the tail). This
+ * keeps the partial trailing line buffered until it completes; {@link flush}
+ * returns whatever is left when the stream ends (CDK's final line has no
+ * trailing newline).
+ */
+export declare function createLineAssembler(): {
+    push(chunk: string): string[];
+    flush(): string[];
+};
+/** Human-readable elapsed time (`45s`, `4m 05s`) for progress lines. */
+export declare function formatElapsed(ms: number): string;
+export interface CdkDeployArgsOptions {
+    /** Project root passed to synth as `--context projectRoot=…`. */
+    projectRoot: string;
+    /** Path (relative to the project root) CDK writes stack outputs to. */
+    outputsFile: string;
+}
+/**
+ * Build the `cdk deploy` argv used by `npm run deploy`.
+ *
+ * Two of these flags exist purely so the deploy is observable — losing either
+ * one brings back the 0-byte stdout:
+ *
+ * - `--ci`: the CDK CLI picks its log stream as `isCI ? stdout : stderr`, so
+ *   without it every CloudFormation event goes to **stderr** and a caller
+ *   capturing stdout (`npm run deploy > deploy.log`) sees nothing for the whole
+ *   multi-minute deploy. With it, progress goes to stdout and only error-level
+ *   messages stay on stderr.
+ * - `--progress events`: print one line per resource transition instead of the
+ *   redrawing progress bar. The bar needs a TTY, which a piped/backgrounded
+ *   deploy does not have, and a half-rendered bar is not a usable progress
+ *   signal in a log file.
+ */
+export declare function buildCdkDeployArgs({ projectRoot, outputsFile }: CdkDeployArgsOptions): string[];
+/** Minimal sink surface so tests can capture the relayed streams. */
+export interface OutputSink {
+    write(chunk: string): unknown;
+}
+/** Minimal signal-registration surface ({@link process} satisfies it). */
+export interface SignalRegistry {
+    on(signal: NodeJS.Signals, handler: () => void): unknown;
+    off(signal: NodeJS.Signals, handler: () => void): unknown;
+}
+export interface RunStreamingOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Prefix used by the runner's own progress/status lines. Defaults to `deploy`. */
+    label?: string;
+    /** Idle gap before a heartbeat line is printed. `0` disables heartbeats. */
+    heartbeatMs?: number;
+    /** Where child stdout and runner progress lines go. Defaults to `process.stdout`. */
+    stdout?: OutputSink;
+    /** Where child stderr goes. Defaults to `process.stderr`. */
+    stderr?: OutputSink;
+    /** Injected for tests. */
+    now?: () => number;
+    /** Injected for tests: signal registration seam. */
+    signalTarget?: SignalRegistry;
+}
+/** Raised when the child exits non-zero, is killed, or the operator aborts. */
+export declare class DeployProcessError extends Error {
+    readonly exitCode: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly aborted: boolean;
+    constructor(message: string, details?: {
+        exitCode?: number | null;
+        signal?: NodeJS.Signals | null;
+        aborted?: boolean;
+    });
+}
+/**
+ * Run a long deployment command, relaying its output line by line as it happens
+ * and keeping it alive across a stray SIGTERM/SIGHUP.
+ *
+ * Behaviour that matters to callers:
+ * - **Streamed, non-empty stdout.** Child stdout is relayed to `stdout` the
+ *   moment a line completes (never buffered until exit) and child stderr to
+ *   `stderr`, so `npm run deploy | tee` shows CloudFormation progress live.
+ * - **Idle heartbeat.** While the child is silent for `heartbeatMs`, a
+ *   `still deploying` line with elapsed time is written to `stdout`, so a
+ *   ten-minute RDS resource never looks like a hung process.
+ * - **Own process group (POSIX only).** The child is spawned `detached` on
+ *   POSIX, so a process-group signal aimed at the parent shell
+ *   (`kill -TERM -pgid`, a harness reaping a backgrounded job) cannot kill the
+ *   CDK CLI behind our back; this runner is the only thing that signals it.
+ *   Windows has neither process groups nor OS-delivered SIGTERM/SIGHUP, so the
+ *   signal resilience below does not apply there — a `taskkill` on the tree ends
+ *   the deploy, and the abort path reaps by pid via `terminateProcessTree`.
+ * - **No stdin.** The child gets `ignore` for stdin so a backgrounded deploy
+ *   can never be stopped by SIGTTIN trying to read a terminal it no longer
+ *   owns; the caller must keep passing `--require-approval never`.
+ * - **Signal policy (POSIX).** See {@link decideSignalResponse}: a deferred
+ *   signal only logs (which itself doubles as a progress signal on stdout),
+ *   while an abort reaps the child tree and throws a {@link DeployProcessError}
+ *   with `aborted: true`. Repeat deliveries of the same signal inside
+ *   {@link SIGNAL_COALESCE_MS} log once, not once per delivery.
+ * - **Streams stay separated.** Child stdout and child stderr are relayed to
+ *   their own sinks and never merged, so a deploy failure reason (which the CDK
+ *   CLI keeps on stderr even under `--ci`) stays on stderr while progress is on
+ *   stdout.
+ *
+ * Resolves when the child exits 0; otherwise throws {@link DeployProcessError}.
+ */
+export declare function runStreaming(command: string, args: string[], options?: RunStreamingOptions): Promise<void>;
+//# sourceMappingURL=deploy-stream.d.ts.map

package/dist/scripts/deploy-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy-stream.d.ts","sourceRoot":"","sources":["../../src/scripts/deploy-stream.ts"],"names":[],"mappings":"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"}

package/dist/scripts/deploy-stream.js

@@ -0,0 +1,332 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { spawnCommand } from './run-command.js';
+import { terminateProcessTree } from './process-tree.js';
+/** Signals whose delivery we take over while a deploy is in flight. */
+export const DEPLOY_SIGNALS = ['SIGTERM', 'SIGINT', 'SIGHUP'];
+/** Default gap (ms) of silence after which the runner prints a progress heartbeat. */
+export const DEFAULT_HEARTBEAT_MS = 30_000;
+/** Grace (ms) given to the child tree to exit after an operator-requested abort. */
+export const ABORT_GRACE_MS = 10_000;
+/**
+ * Grace (ms) we wait after the child exits for its stdout/stderr pipes to end,
+ * so the last CloudFormation lines are relayed before we resolve. Bounded
+ * because a lingering grandchild could hold the pipe open forever; losing a
+ * trailing line is strictly better than hanging a finished deploy.
+ */
+export const STREAM_FLUSH_GRACE_MS = 2_000;
+/**
+ * Window (ms) in which repeated SIGTERMs count as ONE operator request.
+ *
+ * A single external signal reaches this process more than once. `npm run deploy`
+ * runs `npm -> sh -> tsx -> node`, so a process-group SIGTERM is delivered to
+ * the node process directly AND relayed to it a second time by `tsx`, which
+ * forwards SIGTERM/SIGINT to its child. Measured on a real deploy: one
+ * `kill -TERM -<pgid>` produced two SIGTERMs about 50ms apart. Without this
+ * window the second delivery is read as "the operator insisted" and the deploy
+ * is abandoned, which is the exact failure this module exists to prevent.
+ *
+ * 2s is far longer than a delivery burst (tens of ms) and far shorter than a
+ * deliberate repeat (a human running `kill` twice, or a supervisor's
+ * SIGTERM-then-escalate cycle), so both intents stay distinguishable.
+ */
+export const SIGNAL_COALESCE_MS = 2_000;
+/**
+ * Decide how to answer a signal that arrives while CloudFormation is still
+ * converging. This is the whole "decouple the CLI lifecycle from the in-flight
+ * deploy" policy, kept pure so it can be asserted directly.
+ *
+ * - `SIGHUP` → always `defer`. A hangup means the terminal or parent shell went
+ *   away (a backgrounded `npm run deploy &`, a closed SSH session). The deploy
+ *   is server-side work that is already paid for; killing the CLI here is what
+ *   produced the phantom failures, so we keep streaming instead. Duplicate
+ *   deliveries inside {@link SIGNAL_COALESCE_MS} are coalesced so one hangup
+ *   logs one line, not one per delivery.
+ * - `SIGTERM` → `defer` the first time. A lone SIGTERM is almost always
+ *   process-group collateral (a harness reaping the parent shell, a supervisor
+ *   tidying up) rather than a deliberate "stop the deploy", so it only warns.
+ *   Repeats inside {@link SIGNAL_COALESCE_MS} are duplicate *deliveries* of that
+ *   same signal (the group delivers it, then `tsx` relays it) and are coalesced
+ *   into the first. A SIGTERM after that window is a deliberate repeat and
+ *   aborts. A SIGKILL follow-up (`docker stop`, most CI cancels) is uncatchable
+ *   and still ends the process immediately, so this cannot wedge a shutdown.
+ * - `SIGINT` → always `abort`. Ctrl-C is unambiguous, interactive intent, so it
+ *   stays responsive on the first press.
+ *
+ * @param signal - the signal received.
+ * @param msSinceFirstDeferral - ms since the first deferral of *this* signal, or
+ *   `null` when this signal has not been deferred yet. Each signal is tracked
+ *   separately, so a deferred SIGHUP never consumes the SIGTERM abort budget
+ *   (and a repeated SIGHUP is deduped the same way a repeated SIGTERM is).
+ * @param coalesceWindowMs - see {@link SIGNAL_COALESCE_MS}.
+ */
+export function decideSignalResponse(signal, msSinceFirstDeferral, coalesceWindowMs = SIGNAL_COALESCE_MS) {
+    if (signal === 'SIGINT') {
+        return {
+            action: 'abort',
+            message: '\n🛑 Interrupted. Stopping the CDK CLI — CloudFormation may keep applying the change set server-side.',
+        };
+    }
+    if (signal === 'SIGHUP') {
+        return {
+            action: 'defer',
+            message: '⚠️  Ignoring SIGHUP: the deploy is still running and CloudFormation is still converging. Streaming continues; send SIGTERM twice to abort.',
+            coalesced: msSinceFirstDeferral !== null && msSinceFirstDeferral < coalesceWindowMs,
+        };
+    }
+    if (signal === 'SIGTERM' && msSinceFirstDeferral === null) {
+        return {
+            action: 'defer',
+            message: '⚠️  Ignoring SIGTERM: the deploy is still running and CloudFormation is still converging. Send SIGTERM again to abort (the stack update continues server-side either way).',
+        };
+    }
+    if (signal === 'SIGTERM' && msSinceFirstDeferral !== null && msSinceFirstDeferral < coalesceWindowMs) {
+        // Same signal reaching us twice (process group + a wrapper's relay), not a
+        // second request — keep deploying and stay quiet about the duplicate.
+        return {
+            action: 'defer',
+            message: '',
+            coalesced: true,
+        };
+    }
+    return {
+        action: 'abort',
+        message: `\n🛑 Received ${signal} while deploying. Stopping the CDK CLI — CloudFormation may keep applying the change set server-side.`,
+    };
+}
+/**
+ * Split a byte stream into whole lines across chunk boundaries.
+ *
+ * The child's output arrives in arbitrary chunks, so a naive
+ * `chunk.toString().split('\n')` emits torn lines (and drops the tail). This
+ * keeps the partial trailing line buffered until it completes; {@link flush}
+ * returns whatever is left when the stream ends (CDK's final line has no
+ * trailing newline).
+ */
+export function createLineAssembler() {
+    let buffered = '';
+    return {
+        push(chunk) {
+            buffered += chunk;
+            const lines = buffered.split('\n');
+            buffered = lines.pop() ?? '';
+            return lines.map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line));
+        },
+        flush() {
+            if (!buffered)
+                return [];
+            const last = buffered.endsWith('\r') ? buffered.slice(0, -1) : buffered;
+            buffered = '';
+            return last ? [last] : [];
+        },
+    };
+}
+/** Human-readable elapsed time (`45s`, `4m 05s`) for progress lines. */
+export function formatElapsed(ms) {
+    const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    return minutes > 0 ? `${minutes}m ${String(seconds).padStart(2, '0')}s` : `${seconds}s`;
+}
+/**
+ * Build the `cdk deploy` argv used by `npm run deploy`.
+ *
+ * Two of these flags exist purely so the deploy is observable — losing either
+ * one brings back the 0-byte stdout:
+ *
+ * - `--ci`: the CDK CLI picks its log stream as `isCI ? stdout : stderr`, so
+ *   without it every CloudFormation event goes to **stderr** and a caller
+ *   capturing stdout (`npm run deploy > deploy.log`) sees nothing for the whole
+ *   multi-minute deploy. With it, progress goes to stdout and only error-level
+ *   messages stay on stderr.
+ * - `--progress events`: print one line per resource transition instead of the
+ *   redrawing progress bar. The bar needs a TTY, which a piped/backgrounded
+ *   deploy does not have, and a half-rendered bar is not a usable progress
+ *   signal in a log file.
+ */
+export function buildCdkDeployArgs({ projectRoot, outputsFile }) {
+    return [
+        'cdk',
+        'deploy',
+        '--require-approval',
+        'never',
+        '--ci',
+        '--progress',
+        'events',
+        '--outputs-file',
+        outputsFile,
+        '--context',
+        `projectRoot=${projectRoot}`,
+    ];
+}
+/** Unref'd sleep: a pending flush grace must never keep the process alive. */
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms).unref?.();
+    });
+}
+/** Raised when the child exits non-zero, is killed, or the operator aborts. */
+export class DeployProcessError extends Error {
+    exitCode;
+    signal;
+    aborted;
+    constructor(message, details = {}) {
+        super(message);
+        this.name = 'DeployProcessError';
+        this.exitCode = details.exitCode ?? null;
+        this.signal = details.signal ?? null;
+        this.aborted = details.aborted ?? false;
+    }
+}
+/**
+ * Run a long deployment command, relaying its output line by line as it happens
+ * and keeping it alive across a stray SIGTERM/SIGHUP.
+ *
+ * Behaviour that matters to callers:
+ * - **Streamed, non-empty stdout.** Child stdout is relayed to `stdout` the
+ *   moment a line completes (never buffered until exit) and child stderr to
+ *   `stderr`, so `npm run deploy | tee` shows CloudFormation progress live.
+ * - **Idle heartbeat.** While the child is silent for `heartbeatMs`, a
+ *   `still deploying` line with elapsed time is written to `stdout`, so a
+ *   ten-minute RDS resource never looks like a hung process.
+ * - **Own process group (POSIX only).** The child is spawned `detached` on
+ *   POSIX, so a process-group signal aimed at the parent shell
+ *   (`kill -TERM -pgid`, a harness reaping a backgrounded job) cannot kill the
+ *   CDK CLI behind our back; this runner is the only thing that signals it.
+ *   Windows has neither process groups nor OS-delivered SIGTERM/SIGHUP, so the
+ *   signal resilience below does not apply there — a `taskkill` on the tree ends
+ *   the deploy, and the abort path reaps by pid via `terminateProcessTree`.
+ * - **No stdin.** The child gets `ignore` for stdin so a backgrounded deploy
+ *   can never be stopped by SIGTTIN trying to read a terminal it no longer
+ *   owns; the caller must keep passing `--require-approval never`.
+ * - **Signal policy (POSIX).** See {@link decideSignalResponse}: a deferred
+ *   signal only logs (which itself doubles as a progress signal on stdout),
+ *   while an abort reaps the child tree and throws a {@link DeployProcessError}
+ *   with `aborted: true`. Repeat deliveries of the same signal inside
+ *   {@link SIGNAL_COALESCE_MS} log once, not once per delivery.
+ * - **Streams stay separated.** Child stdout and child stderr are relayed to
+ *   their own sinks and never merged, so a deploy failure reason (which the CDK
+ *   CLI keeps on stderr even under `--ci`) stays on stderr while progress is on
+ *   stdout.
+ *
+ * Resolves when the child exits 0; otherwise throws {@link DeployProcessError}.
+ */
+export async function runStreaming(command, args, options = {}) {
+    const { cwd, env, label = 'deploy', heartbeatMs = DEFAULT_HEARTBEAT_MS, stdout = process.stdout, stderr = process.stderr, now = Date.now, signalTarget = process, } = options;
+    const startedAt = now();
+    let lastOutputAt = startedAt;
+    let aborting = false;
+    let exitObserved = false;
+    // Per signal, when its current deferral window opened. Kept per signal so a
+    // deferred SIGHUP neither consumes the SIGTERM abort budget nor silently
+    // swallows its own log line.
+    const deferredAt = new Map();
+    const child = spawnCommand(command, args, {
+        cwd,
+        env,
+        // stdin ignored (see doc comment); stdout/stderr piped so we can relay them
+        // line by line instead of handing the child our fds and going blind.
+        stdio: ['ignore', 'pipe', 'pipe'],
+        detached: process.platform !== 'win32',
+    });
+    const relay = (stream, sink) => {
+        if (!stream)
+            return;
+        const assembler = createLineAssembler();
+        stream.setEncoding('utf-8');
+        stream.on('data', (chunk) => {
+            lastOutputAt = now();
+            for (const line of assembler.push(chunk))
+                sink.write(`${line}\n`);
+        });
+        stream.on('end', () => {
+            for (const line of assembler.flush())
+                sink.write(`${line}\n`);
+        });
+    };
+    relay(child.stdout, stdout);
+    relay(child.stderr, stderr);
+    const heartbeat = heartbeatMs > 0
+        ? setInterval(() => {
+            if (now() - lastOutputAt < heartbeatMs)
+                return;
+            stdout.write(`⏳ [${label}] still running after ${formatElapsed(now() - startedAt)} — CloudFormation is converging (pid ${child.pid ?? '?'})\n`);
+        }, heartbeatMs)
+        : undefined;
+    // Never let the heartbeat timer be the reason the process stays alive.
+    heartbeat?.unref?.();
+    const exited = new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('exit', (code, signal) => {
+            exitObserved = true;
+            resolve({ code, signal });
+        });
+    });
+    const streamsEnded = Promise.all([child.stdout, child.stderr].map((stream) => new Promise((resolve) => {
+        if (!stream)
+            return resolve();
+        stream.once('end', () => resolve());
+        stream.once('close', () => resolve());
+    })));
+    const handlers = new Map();
+    const removeHandlers = () => {
+        for (const [signal, handler] of handlers)
+            signalTarget.off(signal, handler);
+        handlers.clear();
+    };
+    for (const signal of DEPLOY_SIGNALS) {
+        const handler = () => {
+            // The deploy already finished (we are just draining pipes / reporting):
+            // there is nothing left to defer or abort, and reporting an abort here
+            // would turn a successful deploy into a failure.
+            if (exitObserved)
+                return;
+            const openedAt = deferredAt.get(signal);
+            const { action, message, coalesced } = decideSignalResponse(signal, openedAt === undefined ? null : now() - openedAt);
+            if (action === 'defer') {
+                // A coalesced duplicate is the same signal arriving twice (process group
+                // plus a wrapper relay); log it once, not once per delivery. Anything
+                // outside the window is a fresh request, so it opens a new window and
+                // reports again instead of being muted for the rest of the deploy.
+                if (!coalesced) {
+                    deferredAt.set(signal, now());
+                    lastOutputAt = now();
+                    stdout.write(`${message}\n`);
+                }
+                return;
+            }
+            if (aborting)
+                return; // already tearing down; a repeat signal is a no-op
+            aborting = true;
+            stdout.write(`${message}\n`);
+            // Reap the whole tree (npx → cdk → node), not just the npx parent, so an
+            // abort cannot leave an orphaned CDK CLI still driving the stack.
+            void terminateProcessTree(child, ABORT_GRACE_MS);
+        };
+        handlers.set(signal, handler);
+        signalTarget.on(signal, handler);
+    }
+    try {
+        const { code, signal } = await exited;
+        // Let the pipes drain so a caller reading our stdout sees the child's final
+        // lines (CDK's summary / failure reason) before the terminal status.
+        await Promise.race([streamsEnded, delay(STREAM_FLUSH_GRACE_MS)]);
+        if (aborting) {
+            throw new DeployProcessError(`${command} was aborted by an operator signal after ${formatElapsed(now() - startedAt)}`, { exitCode: code, signal, aborted: true });
+        }
+        if (signal) {
+            throw new DeployProcessError(`${command} was terminated by signal ${signal}`, {
+                exitCode: code,
+                signal,
+            });
+        }
+        if (code !== 0) {
+            throw new DeployProcessError(`${command} ${args.join(' ')} exited with code ${code}`, { exitCode: code });
+        }
+    }
+    finally {
+        if (heartbeat)
+            clearInterval(heartbeat);
+        removeHandlers();
+    }
+}

package/dist/scripts/deploy-stream.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=deploy-stream.test.d.ts.map

package/dist/scripts/deploy-stream.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy-stream.test.d.ts","sourceRoot":"","sources":["../../src/scripts/deploy-stream.test.ts"],"names":[],"mappings":""}