@aws-blocks/core 0.1.3 → 0.1.7

package/dist/scripts/dev-server-supervisor.test.js

@@ -0,0 +1,551 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { spawn } from 'node:child_process';
+import { createConnection, createServer } from 'node:net';
+import { readFileSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { evaluateFrontendRespawn, DEFAULT_FRONTEND_RESPAWN_POLICY, waitForPortFree, shouldCreditFrontendReady, } from './dev-server.js';
+import { killFrontendTree, windowsTreeKill, terminateProcessTree, isProcessGroupAlive, KILL_GRACE_MS, } from './process-tree.js';
+const isWindows = process.platform === 'win32';
+// The real-process integration test spawns OS processes and depends on
+// wall-clock timing; gate it behind RUN_SLOW_TESTS so the default test run
+// stays deterministic and fast. The pure unit tests below always run.
+const runSlowTests = !!process.env.RUN_SLOW_TESTS;
+function getFreePort() {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.on('error', reject);
+        srv.listen(0, '127.0.0.1', () => {
+            const addr = srv.address();
+            const port = typeof addr === 'object' && addr ? addr.port : 0;
+            srv.close(() => resolve(port));
+        });
+    });
+}
+function isPortOpen(port) {
+    return new Promise((resolve) => {
+        const sock = createConnection({ port, host: '127.0.0.1' }, () => {
+            sock.destroy();
+            resolve(true);
+        });
+        sock.on('error', () => { sock.destroy(); resolve(false); });
+        sock.setTimeout(300, () => { sock.destroy(); resolve(false); });
+    });
+}
+async function waitFor(predicate, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (await predicate())
+            return true;
+        await new Promise((r) => setTimeout(r, 50));
+    }
+    return predicate();
+}
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+// Poll across a bounded window, returning false the instant the port closes.
+// More robust than a single post-`delay` snapshot on a busy/slow host: it
+// asserts the port stays bound for the whole window rather than at one moment.
+async function staysOpen(port, windowMs) {
+    const deadline = Date.now() + windowMs;
+    while (Date.now() < deadline) {
+        if (!(await isPortOpen(port)))
+            return false;
+        await delay(50);
+    }
+    return true;
+}
+// ── evaluateFrontendRespawn ────────────────────────────────────────────────
+describe('evaluateFrontendRespawn — bounded auto-respawn policy', () => {
+    it('allows the first restart with the base backoff', () => {
+        const now = 1_000_000;
+        const d = evaluateFrontendRespawn([], now);
+        assert.strictEqual(d.restart, true);
+        assert.strictEqual(d.delayMs, DEFAULT_FRONTEND_RESPAWN_POLICY.backoffMs);
+        assert.deepStrictEqual(d.recent, [now]);
+    });
+    it('backs off exponentially with the number of recent restarts', () => {
+        const now = 1_000_000;
+        // one recent restart already → 500 * 2^1
+        assert.strictEqual(evaluateFrontendRespawn([now - 100], now).delayMs, 1000);
+        // three recent → 500 * 2^3
+        assert.strictEqual(evaluateFrontendRespawn([now - 30, now - 20, now - 10], now).delayMs, 4000);
+    });
+    it('caps the backoff at maxBackoffMs', () => {
+        const now = 1_000_000;
+        // four recent → 500 * 2^4 = 8000, capped to 5000
+        const d = evaluateFrontendRespawn([now - 4, now - 3, now - 2, now - 1], now);
+        assert.strictEqual(d.restart, true);
+        assert.strictEqual(d.delayMs, DEFAULT_FRONTEND_RESPAWN_POLICY.maxBackoffMs);
+    });
+    it('stops restarting once the budget within the window is exhausted', () => {
+        const now = 1_000_000;
+        const recent = [now - 5, now - 4, now - 3, now - 2, now - 1]; // 5 == maxRestarts
+        const d = evaluateFrontendRespawn(recent, now);
+        assert.strictEqual(d.restart, false);
+        assert.strictEqual(d.delayMs, 0);
+        assert.strictEqual(d.recent.length, DEFAULT_FRONTEND_RESPAWN_POLICY.maxRestarts);
+    });
+    it('forgets restarts that fall outside the sliding window', () => {
+        const now = 1_000_000;
+        const { windowMs } = DEFAULT_FRONTEND_RESPAWN_POLICY;
+        const recent = [
+            now - windowMs - 1, // stale
+            now - windowMs - 2, // stale
+            now - windowMs - 3, // stale
+            now - windowMs - 4, // stale
+            now - 100, // in-window
+        ];
+        const d = evaluateFrontendRespawn(recent, now);
+        assert.strictEqual(d.restart, true);
+        // only the one in-window timestamp survives → backoff 500 * 2^1
+        assert.strictEqual(d.delayMs, 1000);
+        assert.deepStrictEqual(d.recent, [now - 100, now]);
+    });
+    it('honors a custom policy', () => {
+        const now = 0;
+        const policy = { maxRestarts: 1, windowMs: 1000, backoffMs: 100, maxBackoffMs: 200 };
+        assert.strictEqual(evaluateFrontendRespawn([], now, policy).delayMs, 100);
+        assert.strictEqual(evaluateFrontendRespawn([now], now, policy).restart, false);
+    });
+});
+// ── killFrontendTree (unit, injected spies) ─────────────────────────────────
+describe('killFrontendTree — signal routing', () => {
+    function makeChild(pid) {
+        const calls = [];
+        const child = {
+            pid,
+            kill(signal) { calls.push(signal); return true; },
+        };
+        return { child, calls };
+    }
+    it('signals the whole process group on POSIX (negative pid)', () => {
+        const { child, calls } = makeChild(4242);
+        const groupCalls = [];
+        killFrontendTree(child, 'SIGTERM', 'linux', (pid, sig) => { groupCalls.push([pid, sig]); });
+        assert.deepStrictEqual(groupCalls, [[-4242, 'SIGTERM']]);
+        assert.deepStrictEqual(calls, []); // direct child.kill not used on POSIX
+    });
+    it('reaps the tree via taskkill on Windows (no POSIX group, no direct kill)', () => {
+        const { child, calls } = makeChild(4242);
+        let groupCalled = false;
+        const winPids = [];
+        killFrontendTree(child, 'SIGTERM', 'win32', () => { groupCalled = true; }, (pid) => { winPids.push(pid); return true; });
+        assert.strictEqual(groupCalled, false); // POSIX group kill not used on Windows
+        assert.deepStrictEqual(winPids, [4242]); // taskkill tree-kill invoked with the pid
+        assert.deepStrictEqual(calls, []); // no direct child.kill once taskkill succeeded
+    });
+    it('falls back to a direct child kill on Windows when taskkill cannot run', () => {
+        const { child, calls } = makeChild(4242);
+        killFrontendTree(child, 'SIGTERM', 'win32', () => { }, () => false); // taskkill unavailable → must degrade to child.kill
+        assert.deepStrictEqual(calls, ['SIGTERM']);
+    });
+    it('falls back to a direct child kill when the group signal throws', () => {
+        const { child, calls } = makeChild(4242);
+        killFrontendTree(child, 'SIGKILL', 'linux', () => {
+            throw Object.assign(new Error('ESRCH'), { code: 'ESRCH' });
+        });
+        assert.deepStrictEqual(calls, ['SIGKILL']);
+    });
+    it('uses a direct child kill when there is no pid', () => {
+        const { child, calls } = makeChild(undefined);
+        let groupCalled = false;
+        killFrontendTree(child, 'SIGTERM', 'linux', () => { groupCalled = true; });
+        assert.strictEqual(groupCalled, false);
+        assert.deepStrictEqual(calls, ['SIGTERM']);
+    });
+    it('never group-signals pid <= 1 (defensive)', () => {
+        const { child, calls } = makeChild(1);
+        let groupCalled = false;
+        killFrontendTree(child, 'SIGTERM', 'linux', () => { groupCalled = true; });
+        assert.strictEqual(groupCalled, false);
+        assert.deepStrictEqual(calls, ['SIGTERM']);
+    });
+});
+// ── windowsTreeKill (unit, injected runner) ─────────────────────────────────
+describe('windowsTreeKill — taskkill tree-kill command', () => {
+    it('invokes `taskkill /T /F /PID <pid>` and reports success', () => {
+        const runs = [];
+        const ok = windowsTreeKill(4242, (cmd, args) => { runs.push([cmd, args]); return { status: 0 }; });
+        assert.strictEqual(ok, true);
+        assert.deepStrictEqual(runs, [['taskkill', ['/T', '/F', '/PID', '4242']]]);
+    });
+    it('treats an already-gone tree (non-zero exit, no spawn error) as handled', () => {
+        const ok = windowsTreeKill(4242, () => ({ status: 128 })); // 128 = "process not found"
+        assert.strictEqual(ok, true);
+    });
+    it('reports failure when taskkill cannot be spawned (caller then falls back)', () => {
+        const ok = windowsTreeKill(4242, () => ({ status: null, error: new Error('ENOENT') }));
+        assert.strictEqual(ok, false);
+    });
+    it('reports failure when taskkill runs but returns a non-zero, non-128 status', () => {
+        // taskkill spawned fine (no error) but FAILED to reap the tree — e.g. exit 1
+        // = access denied. It must NOT be treated as handled, or the caller skips
+        // its child.kill fallback and silently leaks the tree.
+        assert.strictEqual(windowsTreeKill(4242, () => ({ status: 1 })), false);
+        // A taskkill killed by a signal (status null, no spawn error) is likewise
+        // not a successful reap.
+        assert.strictEqual(windowsTreeKill(4242, () => ({ status: null })), false);
+    });
+    it('never throws even if the runner throws', () => {
+        const ok = windowsTreeKill(4242, () => { throw new Error('boom'); });
+        assert.strictEqual(ok, false);
+    });
+});
+// ── isProcessGroupAlive (unit, injected kill + platform) ────────────────────
+// Scopes the post-exit group SIGKILL: a `-pid` signal is only PID-reuse-safe
+// while a group member is still alive, so terminateProcessTree probes here and
+// skips the reap once the group has drained.
+describe('isProcessGroupAlive — group-liveness probe (signal 0)', () => {
+    const esrch = () => { throw Object.assign(new Error('ESRCH'), { code: 'ESRCH' }); };
+    const eperm = () => { throw Object.assign(new Error('EPERM'), { code: 'EPERM' }); };
+    it('probes the GROUP with signal 0 (negative pid, no real signal) and reports alive on success', () => {
+        const calls = [];
+        const alive = isProcessGroupAlive(4242, 'linux', (pid, sig) => { calls.push([pid, sig]); });
+        assert.strictEqual(alive, true);
+        assert.deepStrictEqual(calls, [[-4242, 0]]); // group probe, signal 0 = existence check only
+    });
+    it('reports drained (false) when the group is gone (ESRCH)', () => {
+        assert.strictEqual(isProcessGroupAlive(4242, 'linux', esrch), false);
+    });
+    it('reports alive (true) when the group exists but is not ours to signal (EPERM)', () => {
+        assert.strictEqual(isProcessGroupAlive(4242, 'linux', eperm), true);
+    });
+    it('always reports alive on Windows (no process groups; taskkill is PID-tree-scoped)', () => {
+        let probed = false;
+        const alive = isProcessGroupAlive(4242, 'win32', () => { probed = true; });
+        assert.strictEqual(alive, true);
+        assert.strictEqual(probed, false); // never probes on Windows
+    });
+});
+// ── killFrontendTree (integration, real shell + grandchild) ─────────────────
+// Opt-in: spawns real OS processes and relies on wall-clock timing, so it is
+// gated behind RUN_SLOW_TESTS to keep the default `npm test` deterministic.
+// POSIX-only because it asserts process-group reaping.
+const integrationSkip = !runSlowTests
+    ? 'set RUN_SLOW_TESTS=1 to run (spawns real processes)'
+    : isWindows
+        ? 'POSIX-only (relies on process groups)'
+        : false;
+describe('killFrontendTree — reaps a real detached shell tree', { skip: integrationSkip }, () => {
+    it('frees a port held by a grandchild that survives a direct child kill', { timeout: 30000 }, async () => {
+        const port = await getFreePort();
+        // getFreePort() closes its probe listener before this grandchild binds,
+        // so on a busy host another process can grab the port in that gap. Retry
+        // briefly on EADDRINUSE (creating a fresh server each attempt) instead of
+        // exiting on the first error, so the shell→node→port topology under test
+        // is reliably established; bail only on a non-transient error or once the
+        // retry budget (~5s) is exhausted.
+        const inner = `const net=require('net');` +
+            `const port=${port};` +
+            `let tries=0;` +
+            `(function bind(){` +
+            `const s=net.createServer(c=>c.destroy());` +
+            `s.on('error',e=>{` +
+            `if(e.code==='EADDRINUSE'&&tries++<50){setTimeout(bind,100);return;}` +
+            `process.exit(1);` +
+            `});` +
+            `s.listen(port,'127.0.0.1');` +
+            `})();` +
+            `setInterval(()=>{},1e9);`;
+        // Run node as a backgrounded child of the shell (then `wait`): this gives
+        // the shell→node parent/grandchild topology of `shell: true` without any
+        // exec-optimization. SIGTERM to the shell does NOT propagate to the
+        // backgrounded node, so the node is orphaned and keeps the port — exactly
+        // the leak the fix must reap via a process-group kill.
+        const cmd = `${JSON.stringify(process.execPath)} -e ${JSON.stringify(inner)} & wait`;
+        const child = spawn(cmd, { shell: true, detached: true, stdio: 'ignore' });
+        try {
+            assert.ok(await waitFor(() => isPortOpen(port), 10000), 'frontend grandchild should bind the port');
+            // Direct kill of only the shell parent (what the old cleanup did): the
+            // backgrounded node grandchild is orphaned, survives, and keeps the
+            // port bound — this is exactly the :3100 502 leak.
+            child.kill('SIGTERM');
+            // Poll across a bounded window instead of a single post-`delay`
+            // snapshot so a slow/busy host can't race the assertion.
+            assert.ok(await staysOpen(port, 600), 'direct child kill must NOT free the port (demonstrates the orphan bug)');
+            // The shell parent is now gone, so the group kill below is exercised as
+            // a POST-EXIT reap — the exact case the reconciled kill policy relies on:
+            // the orphaned grandchild keeps the process group alive (pgid === the
+            // exited shell's pid), so `process.kill(-pid)` still targets our group.
+            assert.ok(await waitFor(async () => child.exitCode !== null || child.signalCode !== null, 5000), 'shell parent should have exited after SIGTERM (sets up the post-exit reap)');
+            // Group kill reaps the entire tree and frees the port — the fix. It
+            // works even though the shell parent has already exited (asserted above).
+            killFrontendTree(child, 'SIGKILL');
+            assert.ok(await waitFor(async () => !(await isPortOpen(port)), 10000), 'group kill must free the port (the fix)');
+        }
+        finally {
+            // Belt-and-suspenders: never leak the node grandchild if an assert throws.
+            if (child.pid) {
+                try {
+                    process.kill(-child.pid, 'SIGKILL');
+                }
+                catch { /* gone */ }
+            }
+        }
+    });
+});
+// ── terminateProcessTree (integration, detached NON-shell tree) ─────────────
+// Mirrors the sandbox `cdk watch` topology (npx → cdk → node, no shell) that
+// finding #1 switched from a bare `cdkWatch.kill()` to `terminateProcessTree`.
+// Opt-in + POSIX-only for the same reasons as the shell-tree test above.
+describe('terminateProcessTree — reaps a detached non-shell tree (cdk-watch shape)', { skip: integrationSkip }, () => {
+    it('group-reaps an npx-style parent whose grandchild holds a port, even post-exit', { timeout: 30000 }, async () => {
+        const port = await getFreePort();
+        // Grandchild (stands in for cdk-watch's node): binds the port and idles.
+        // Retry on EADDRINUSE like the shell-tree test, since getFreePort()
+        // releases its probe listener before this grandchild can rebind.
+        const inner = `const net=require('net');` +
+            `const port=${port};` +
+            `let tries=0;` +
+            `(function bind(){` +
+            `const s=net.createServer(c=>c.destroy());` +
+            `s.on('error',e=>{` +
+            `if(e.code==='EADDRINUSE'&&tries++<50){setTimeout(bind,100);return;}` +
+            `process.exit(1);` +
+            `});` +
+            `s.listen(port,'127.0.0.1');` +
+            `})();` +
+            `setInterval(()=>{},1e9);`;
+        // Parent (stands in for `npx`): spawns the port-binding grandchild as a
+        // normal (NON-detached) child, then idles. No shell anywhere — the
+        // cdk-watch shape. Spawning the PARENT `detached` makes it a process-group
+        // leader (pgid === parent.pid) that the grandchild inherits, so a single
+        // `process.kill(-pid)` reaches both.
+        const parent = `const cp=require('child_process');` +
+            `cp.spawn(process.execPath,['-e',${JSON.stringify(inner)}],{stdio:'ignore'});` +
+            `setInterval(()=>{},1e9);`;
+        const child = spawn(process.execPath, ['-e', parent], { detached: true, stdio: 'ignore' });
+        try {
+            assert.ok(await waitFor(() => isPortOpen(port), 10000), 'grandchild should bind the port');
+            // A direct kill of ONLY the parent (what the old bare `cdkWatch.kill()`
+            // did) orphans the grandchild, which survives still holding the port —
+            // the exact shell/parent-only-kill leak finding #1 eliminates.
+            child.kill('SIGTERM');
+            assert.ok(await staysOpen(port, 600), 'direct parent kill must NOT free the port (demonstrates the orphan)');
+            assert.ok(await waitFor(async () => child.exitCode !== null || child.signalCode !== null, 5000), 'parent should have exited after SIGTERM (sets up the post-exit reap)');
+            // terminateProcessTree now takes the post-exit branch (parent already
+            // gone) and issues a group SIGKILL via the shared killFrontendTree,
+            // reaping the orphaned grandchild and freeing the port — what the new
+            // `terminateProcessTree(cdkWatch, …)` call guarantees in sandbox.ts.
+            const reaped = await terminateProcessTree(child, 2000);
+            assert.strictEqual(reaped, true, 'post-exit terminateProcessTree resolves true');
+            assert.ok(await waitFor(async () => !(await isPortOpen(port)), 10000), 'group kill must free the port held by the grandchild (the fix)');
+        }
+        finally {
+            // Belt-and-suspenders: never leak the grandchild if an assert throws.
+            if (child.pid) {
+                try {
+                    process.kill(-child.pid, 'SIGKILL');
+                }
+                catch { /* gone */ }
+            }
+        }
+    });
+});
+// ── group SIGTERM → nested node handler (sandbox dev-server teardown) ────────
+// Verifies the load-bearing claim in sandbox.ts: a *group* SIGTERM (what
+// killFrontendTree issues on POSIX, via terminateProcessTree) actually reaches
+// the nested node dev server so its OWN SIGTERM handler (the :3100 drain) runs —
+// not merely that the tree gets reaped. Opt-in + POSIX-only like the reaping
+// tests above.
+describe('group SIGTERM reaches a nested node child and runs its SIGTERM handler', { skip: integrationSkip }, () => {
+    it('delivers a group SIGTERM to a detached shell→node child whose node handler observes it', { timeout: 30000 }, async () => {
+        const port = await getFreePort();
+        const marker = join(tmpdir(), `blocks-sigterm-${process.pid}-${Date.now()}.flag`);
+        // node grandchild: install a SIGTERM handler that RECORDS it observed the
+        // signal (writes the marker) before exiting, THEN bind the port to
+        // announce readiness. Installing the handler before binding guarantees the
+        // test never sends SIGTERM before the handler exists (which would
+        // default-terminate node and flake the assertion). Retry on EADDRINUSE
+        // like the reaping tests, since getFreePort() releases its probe listener.
+        const inner = `const net=require('net'),fs=require('fs');` +
+            `process.on('SIGTERM',()=>{try{fs.writeFileSync(${JSON.stringify(marker)},'sigterm');}catch{}process.exit(0);});` +
+            `let tries=0;` +
+            `(function bind(){` +
+            `const s=net.createServer(c=>c.destroy());` +
+            `s.on('error',e=>{` +
+            `if(e.code==='EADDRINUSE'&&tries++<50){setTimeout(bind,100);return;}` +
+            `process.exit(1);` +
+            `});` +
+            `s.listen(${port},'127.0.0.1');` +
+            `})();` +
+            `setInterval(()=>{},1e9);`;
+        // shell → node grandchild, backgrounded with `& wait` so the shell stays
+        // the live group leader — the exact `shell: true` + detached topology the
+        // dev server uses, where a group signal must fan out to the nested node.
+        const cmd = `${JSON.stringify(process.execPath)} -e ${JSON.stringify(inner)} & wait`;
+        const child = spawn(cmd, { shell: true, detached: true, stdio: 'ignore' });
+        try {
+            assert.ok(await waitFor(() => isPortOpen(port), 10000), 'nested node should install its SIGTERM handler then bind the port (ready)');
+            assert.ok(child.pid && child.pid > 1, 'child must have a real pid to group-signal');
+            // The group SIGTERM under test: exactly what killFrontendTree does on
+            // POSIX (`process.kill(-pid, 'SIGTERM')`) and what the sandbox dev-server
+            // teardown relies on to trigger the node's own terminateFrontend handler.
+            // The `if (child.pid)` guard (asserted above) narrows the type without a
+            // non-null assertion — matching the finally-block pattern used in this file.
+            if (child.pid)
+                process.kill(-child.pid, 'SIGTERM');
+            // Assert the node handler OBSERVED the signal (wrote the marker) — i.e.
+            // the group SIGTERM reached the *nested* node, not just the shell.
+            const observed = await waitFor(async () => {
+                try {
+                    return readFileSync(marker, 'utf8') === 'sigterm';
+                }
+                catch {
+                    return false;
+                }
+            }, 10000);
+            assert.ok(observed, 'the nested node SIGTERM handler must run on a group SIGTERM');
+        }
+        finally {
+            if (child.pid) {
+                try {
+                    process.kill(-child.pid, 'SIGKILL');
+                }
+                catch { /* gone */ }
+            }
+            try {
+                unlinkSync(marker);
+            }
+            catch { /* never created */ }
+        }
+    });
+});
+// ── shouldCreditFrontendReady (unit) ────────────────────────────────────────
+// Guards the restart-budget reset: a liveness-only port probe must not credit a
+// foreign listener, or the maxRestarts cap is neutralized and Vite hot-loops.
+describe('shouldCreditFrontendReady — credit only our own live child', () => {
+    const liveChild = () => ({ exitCode: null, signalCode: null });
+    it('credits the probe when our spawned child is still the live frontend', () => {
+        const child = liveChild();
+        assert.strictEqual(shouldCreditFrontendReady(child, child), true);
+    });
+    it('does NOT credit a foreign listener (a different or absent current child)', () => {
+        const child = liveChild();
+        assert.strictEqual(shouldCreditFrontendReady(child, liveChild()), false);
+        assert.strictEqual(shouldCreditFrontendReady(child, null), false);
+    });
+    it('does NOT credit a child that already exited (lost the --strictPort bind race)', () => {
+        const exited = { exitCode: 1, signalCode: null };
+        assert.strictEqual(shouldCreditFrontendReady(exited, exited), false);
+        const killed = { exitCode: null, signalCode: 'SIGKILL' };
+        assert.strictEqual(shouldCreditFrontendReady(killed, killed), false);
+    });
+    it('does NOT credit when there is no child', () => {
+        assert.strictEqual(shouldCreditFrontendReady(null, null), false);
+    });
+});
+// ── terminateProcessTree (unit, injected killTree + sleep) ──────────────────
+// The shared SIGTERM->SIGKILL escalation used by both the dev server and the
+// sandbox entrypoint. Dependencies are injected so the policy is exercised
+// without spawning real processes or real timers.
+describe('terminateProcessTree — escalation + post-exit reap', () => {
+    const immediate = (_ms) => Promise.resolve();
+    const never = (_ms) => new Promise(() => { });
+    function makeAwaitableChild(initial = {}) {
+        let exitListener = null;
+        const child = {
+            pid: 4242,
+            exitCode: initial.exitCode ?? null,
+            signalCode: initial.signalCode ?? null,
+            kill() { return true; },
+            once(_event, listener) { exitListener = listener; return child; },
+        };
+        const fireExit = (code = 0, signal = null) => {
+            child.exitCode = code;
+            child.signalCode = signal;
+            exitListener?.();
+        };
+        return { child, fireExit };
+    }
+    it('issues a single best-effort group SIGKILL when the child already exited and its group is still alive', async () => {
+        const { child } = makeAwaitableChild({ exitCode: 0 });
+        const sent = [];
+        // Group still has a live member (an orphaned grandchild) → reap it.
+        const ok = await terminateProcessTree(child, 1500, (_c, s) => { sent.push(s); }, never, () => true);
+        assert.strictEqual(ok, true);
+        assert.deepStrictEqual(sent, ['SIGKILL']); // post-exit reap: no SIGTERM, no await
+    });
+    it('skips the post-exit group SIGKILL when the whole group has already drained', async () => {
+        const { child } = makeAwaitableChild({ exitCode: 0 });
+        const sent = [];
+        // The group has fully drained: a `-pid` SIGKILL risks signalling a recycled,
+        // unrelated group, and there is nothing of ours left to reap — so skip it.
+        const ok = await terminateProcessTree(child, 1500, (_c, s) => { sent.push(s); }, never, () => false);
+        assert.strictEqual(ok, true); // still resolves true (the child has exited)
+        assert.deepStrictEqual(sent, []); // no signal sent into the drained group
+    });
+    it('SIGTERMs the tree and resolves without escalating when it exits in time', async () => {
+        const { child, fireExit } = makeAwaitableChild();
+        const sent = [];
+        const ok = await terminateProcessTree(child, 1500, (_c, s) => {
+            sent.push(s);
+            if (s === 'SIGTERM')
+                fireExit(0, null); // clean exit wins the grace race
+        }, never);
+        assert.strictEqual(ok, true);
+        assert.deepStrictEqual(sent, ['SIGTERM']);
+    });
+    it('escalates to a tree SIGKILL when the child lingers past the grace window', async () => {
+        const { child, fireExit } = makeAwaitableChild();
+        const sent = [];
+        const ok = await terminateProcessTree(child, 1500, (_c, s) => {
+            sent.push(s);
+            if (s === 'SIGKILL')
+                fireExit(null, 'SIGKILL'); // dies only on SIGKILL
+        }, immediate);
+        assert.deepStrictEqual(sent, ['SIGTERM', 'SIGKILL']);
+        assert.strictEqual(ok, true);
+    });
+    it('reports false when the child is still alive after the SIGKILL grace', async () => {
+        const { child } = makeAwaitableChild();
+        const sent = [];
+        const ok = await terminateProcessTree(child, 1500, (_c, s) => { sent.push(s); }, immediate);
+        assert.deepStrictEqual(sent, ['SIGTERM', 'SIGKILL']);
+        assert.strictEqual(ok, false);
+    });
+    it('waits graceMs for the SIGTERM grace and the shorter KILL_GRACE_MS after SIGKILL', async () => {
+        const { child } = makeAwaitableChild();
+        const sent = [];
+        const slept = [];
+        // Resolve every sleep immediately (so both grace races resolve) but record
+        // the requested durations to prove which grace each escalation step uses.
+        const recordingSleep = (ms) => { slept.push(ms); return Promise.resolve(); };
+        const ok = await terminateProcessTree(child, 1500, (_c, s) => { sent.push(s); }, recordingSleep);
+        assert.deepStrictEqual(sent, ['SIGTERM', 'SIGKILL']);
+        // First grace == the injectable SIGTERM graceMs; second == the fixed,
+        // deliberately shorter post-SIGKILL grace constant.
+        assert.deepStrictEqual(slept, [1500, KILL_GRACE_MS]);
+        assert.ok(KILL_GRACE_MS < 1500, 'the post-SIGKILL grace must be shorter than the SIGTERM grace');
+        assert.strictEqual(ok, false); // child never fired exit
+    });
+});
+// ── waitForPortFree (real sockets, fast + deterministic) ────────────────────
+// Asserts the "wait for the port to free before exiting" invariant that the
+// post-exit terminate path used to drop.
+describe('waitForPortFree — waits for the listener to release the port', () => {
+    it('returns promptly when nothing holds the port', async () => {
+        const port = await getFreePort();
+        const t0 = Date.now();
+        await waitForPortFree(port, 2000);
+        assert.ok(Date.now() - t0 < 1000, 'should return quickly when the port is already free');
+    });
+    it('keeps polling while the port is held, then resolves once it closes', async () => {
+        const port = await getFreePort();
+        const srv = createServer((c) => c.destroy());
+        await new Promise((res) => srv.listen(port, '127.0.0.1', () => res()));
+        // A short bounded wait must consume ~its whole budget while the port is held;
+        // it can only return early if it (wrongly) sees the held port as free.
+        const t0 = Date.now();
+        await waitForPortFree(port, 300);
+        assert.ok(Date.now() - t0 >= 250, 'must keep polling while the port is held');
+        await new Promise((res) => srv.close(() => res()));
+        // Once free, a generous-timeout call returns promptly.
+        const t1 = Date.now();
+        await waitForPortFree(port, 3000);
+        assert.ok(Date.now() - t1 < 1500, 'should resolve soon after the port frees');
+    });
+});

package/dist/scripts/dev-server.d.ts

@@ -4,6 +4,25 @@ export declare const LOCALHOST_PATTERN: RegExp;
  * Reflects back origins matching localhost/127.0.0.1; otherwise returns the fallback.
  */
 export declare function resolveDevCorsOrigin(origin: string): string;
+/** Shape of the client runtime config the browser fetches to discover the API URL. */
+export interface BlocksRuntimeConfig {
+    apiUrl: string;
+    environment: 'local' | 'sandbox';
+}
+/**
+ * Build the runtime config the browser fetches at `${BLOCKS_SANDBOX_PREFIX}/config.json`.
+ * In sandbox mode the browser still targets the localhost front door (the dev
+ * server proxies `/aws-blocks/api` to the deployed API), so the shape is the
+ * same in both modes — only `environment` differs.
+ */
+export declare function buildBlocksConfig(port: number, isSandbox: boolean): BlocksRuntimeConfig;
+/**
+ * True for the reserved runtime-config request the dev server answers itself
+ * (mirroring production, where CloudFront serves `${BLOCKS_SANDBOX_PREFIX}/*`
+ * statically) instead of proxying it to the framework dev server — which only
+ * serves its own static dir (Next.js `public/`, etc.) and would 404.
+ */
+export declare function isBlocksConfigRequest(method: string, pathname: string): boolean;
 export interface DevServerOptions {
     /** Customer-facing port. Default: 3000. */
     port?: number;
@@ -17,5 +36,78 @@ export interface DevServerOptions {
     /** Port the frontend dev server listens on. Default: 3100. */
     frontendPort?: number;
 }
+/** Bounded auto-respawn policy for the frontend dev server. */
+export interface FrontendRespawnPolicy {
+    /** Max restarts allowed within `windowMs` before giving up (prevents hot loops). */
+    maxRestarts: number;
+    /** Sliding window (ms) over which restarts are counted. */
+    windowMs: number;
+    /** Base backoff (ms); doubles for each restart already in the window. */
+    backoffMs: number;
+    /** Upper bound (ms) on any single backoff delay. */
+    maxBackoffMs: number;
+}
+/** Default frontend respawn budget: 5 restarts / 10s, 500ms→5s exponential backoff. */
+export declare const DEFAULT_FRONTEND_RESPAWN_POLICY: FrontendRespawnPolicy;
+/** Outcome of {@link evaluateFrontendRespawn}. */
+export interface RespawnDecision {
+    /** Whether the frontend should be respawned now. */
+    restart: boolean;
+    /** Delay (ms) to wait before respawning when `restart` is true. */
+    delayMs: number;
+    /**
+     * Restart timestamps still inside the window — plus the new attempt when
+     * restarting. The caller persists this for the next decision.
+     */
+    recent: number[];
+}
+/**
+ * Decide whether to auto-respawn the frontend dev server after an unexpected
+ * exit, given the timestamps of restarts not yet "forgiven".
+ *
+ * Semantics — the budget counts only *failing* restarts:
+ * - Timestamps older than `windowMs` are dropped from the sliding window.
+ * - If `maxRestarts` are still within the window, the budget is exhausted and
+ *   the frontend is left down (no hot restart loop) — `restart: false`.
+ * - Otherwise `restart: true` with an exponential backoff (`backoffMs` doubled
+ *   per in-window restart, capped at `maxBackoffMs`) and the new attempt
+ *   appended to `recent`.
+ *
+ * This function is pure; the *meaning* of the budget is enforced by the caller,
+ * which **resets `recentRestarts` to `[]` once a respawn demonstrably succeeds**
+ * (the frontend port becomes bound — see `announceFrontendReady`). As a result
+ * only *consecutive failing* restarts accumulate toward `maxRestarts`: a
+ * frontend that legitimately restarts many times in a burst (e.g.
+ * editor-triggered Vite full reloads) refreshes its budget on each healthy bind
+ * and is never permanently left down — only a genuine crash loop that never
+ * rebinds the port trips the limit.
+ */
+export declare function evaluateFrontendRespawn(recentRestarts: number[], now: number, policy?: FrontendRespawnPolicy): RespawnDecision;
+/**
+ * Wait (bounded) for a TCP port to STOP accepting connections, i.e. for the
+ * listener to actually release the socket. Used after killing the frontend so a
+ * `tsx watch` relaunch can rebind `:3100` cleanly instead of racing the kernel's
+ * socket teardown and hitting `--strictPort` `EADDRINUSE`. Resolves as soon as
+ * the port is free, or once `timeoutMs` elapses (never rejects).
+ */
+export declare function waitForPortFree(port: number, timeoutMs?: number): Promise<void>;
+/**
+ * Decide whether a "frontend is listening" probe should be *credited* as a
+ * successful (re)spawn — and thus reset the restart budget.
+ *
+ * `waitForPort` only proves *something* is listening on `:3100`; it cannot tell
+ * our Vite apart from a foreign listener (a leftover Vite, or a second dev
+ * server). Crediting any listener would let a foreign process on `:3100` make
+ * every `--strictPort`-failing respawn look successful, neutralizing the
+ * `maxRestarts` cap and hot-looping forever. So we credit the probe only when
+ * **our** spawned child is still the live frontend process — same identity and
+ * not yet exited. A child that already exited (e.g. it lost the `--strictPort`
+ * bind race to the foreign listener) is no longer `current`, so it is not
+ * credited and its failed attempt still counts toward the budget.
+ */
+export declare function shouldCreditFrontendReady(child: {
+    exitCode: number | null;
+    signalCode: NodeJS.Signals | null;
+} | null, current: unknown): boolean;
 export declare function startDevServer(options: DevServerOptions): Promise<void>;
 //# sourceMappingURL=dev-server.d.ts.map

package/dist/scripts/dev-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev-server.d.ts","sourceRoot":"","sources":["../../src/scripts/dev-server.ts"],"names":[],"mappings":"AAmCA,eAAO,MAAM,iBAAiB,QAAiD,CAAC;AAEhF;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAmCD,wBAAsB,cAAc,CAAC,OAAO,EAAE,gBAAgB,iBAiP7D"}
+{"version":3,"file":"dev-server.d.ts","sourceRoot":"","sources":["../../src/scripts/dev-server.ts"],"names":[],"mappings":"AAoCA,eAAO,MAAM,iBAAiB,QAAiD,CAAC;AAEhF;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,sFAAsF;AACtF,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,OAAO,GAAG,SAAS,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,mBAAmB,CAKvF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE/E;AAED,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAmCD,+DAA+D;AAC/D,MAAM,WAAW,qBAAqB;IACpC,oFAAoF;IACpF,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,uFAAuF;AACvF,eAAO,MAAM,+BAA+B,EAAE,qBAK7C,CAAC;AAEF,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CACrC,cAAc,EAAE,MAAM,EAAE,EACxB,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,qBAAuD,GAC9D,eAAe,CAOjB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAenF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,EAC5E,OAAO,EAAE,OAAO,GACf,OAAO,CAOT;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,gBAAgB,iBAya7D"}