@aws-blocks/core 0.1.4 → 0.1.10

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

@@ -36,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,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,wBAAsB,cAAc,CAAC,OAAO,EAAE,gBAAgB,iBA8P7D"}
+{"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"}

package/dist/scripts/dev-server.js

@@ -16,6 +16,7 @@ import { parseRpcRequest, successResponse, errorResponseFromCatch, methodNotFoun
 import { redactToJson } from '../redact.js';
 import { buildAndSendEvent } from '../telemetry/client.js';
 import { applyDevMigrations } from './external-migrations-step.js';
+import { killFrontendTree, terminateProcessTree } from './process-tree.js';
 function toBodyStream(text) {
     if (!text)
         return null;
@@ -87,6 +88,86 @@ async function waitForPort(port, maxAttempts = 60) {
     }
     throw new Error(`Frontend server on port ${port} did not start within ${maxAttempts * 500}ms`);
 }
+/** Default frontend respawn budget: 5 restarts / 10s, 500ms→5s exponential backoff. */
+export const DEFAULT_FRONTEND_RESPAWN_POLICY = {
+    maxRestarts: 5,
+    windowMs: 10_000,
+    backoffMs: 500,
+    maxBackoffMs: 5_000,
+};
+/**
+ * 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 function evaluateFrontendRespawn(recentRestarts, now, policy = DEFAULT_FRONTEND_RESPAWN_POLICY) {
+    const recent = recentRestarts.filter((t) => now - t < policy.windowMs);
+    if (recent.length >= policy.maxRestarts) {
+        return { restart: false, delayMs: 0, recent };
+    }
+    const delayMs = Math.min(policy.backoffMs * 2 ** recent.length, policy.maxBackoffMs);
+    return { restart: true, delayMs, recent: [...recent, now] };
+}
+/**
+ * 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 async function waitForPortFree(port, timeoutMs = 2000) {
+    const { setTimeout: sleep } = await import('node:timers/promises');
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const open = await new Promise((resolve) => {
+            const socket = createConnection({ port, host: 'localhost' }, () => {
+                socket.destroy();
+                resolve(true);
+            });
+            socket.on('error', () => { socket.destroy(); resolve(false); });
+            socket.setTimeout(200, () => { socket.destroy(); resolve(false); });
+        });
+        if (!open)
+            return;
+        await sleep(100);
+    }
+}
+/**
+ * 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 function shouldCreditFrontendReady(child, current) {
+    return (!!child &&
+        child === current &&
+        child.exitCode === null &&
+        child.signalCode === null);
+}
 export async function startDevServer(options) {
     const { port = 3000, backendPath, frontendCommand, frontendPort = 3100, } = options;
     const devStartTime = Date.now();
@@ -155,6 +236,165 @@ export async function startDevServer(options) {
         res.writeHead(502);
         res.end('Frontend server unavailable');
     });
+    // ── Frontend supervisor ─────────────────────────────────────────────────
+    // The frontend runs under `shell: true`, so the real dev server (Vite) is a
+    // grandchild of this process. We spawn it `detached` (its own process group)
+    // on POSIX so cleanup/restart can signal the *whole* tree and free the port;
+    // otherwise the orphaned grandchild keeps `:3100` and every `/` request 502s
+    // forever (the proxy target is hardcoded to `frontendPort`). We also bound-
+    // respawn it on unexpected death and suppress all of this during shutdown.
+    //
+    // ── POST-EXIT GROUP-KILL POLICY ─────────────────────────────────────────
+    // The exact bug this supervisor fixes is the shell *exiting* while the
+    // detached grandchild survives, orphaned, still holding `:3100`. Reaping that
+    // orphan REQUIRES a group kill (`process.kill(-pid, …)`) issued *after* the
+    // shell has already exited — so all three post-exit kill sites below agree:
+    // the respawn path, `terminateFrontend`, and the `process.on('exit')` net all
+    // group-kill rather than skip when the shell is already gone.
+    //
+    // Why this is safe against the classic `-pid` PID-reuse hazard:
+    //   1. A surviving grandchild keeps the process group non-empty, so POSIX
+    //      keeps `pid` reserved as the group id — it cannot be recycled as a new
+    //      process id while it is still a live group's id. Hence `-pid` is
+    //      guaranteed to target *our* group precisely when it matters (an orphan
+    //      is still alive in it).
+    //   2. We only ever issue the kill synchronously, the instant we observe the
+    //      shell's exit — there is no intervening `await` that could let the group
+    //      drain and the pid be recycled — so the residual window is minimal.
+    // Residual accepted risk: if the ENTIRE group is already gone *and* `pid` has
+    // since been recycled into a brand-new group leader, `-pid` could signal an
+    // unrelated group. This is an accepted best-effort trade-off — there is then
+    // nothing of ours left to reap, whereas skipping the kill would otherwise
+    // leave `:3100` wedged, which is the failure this PR exists to prevent.
+    //
+    // Where each post-exit kill site lands on this trade-off: the two sites *in
+    // this file* — the respawn reap (in the child's `exit` handler) and the
+    // `process.on('exit')` net — fire synchronously the instant we observe the
+    // exit, so they lean on point (2) above and stay unconditional. The third
+    // path, `terminateFrontend` → `terminateProcessTree` (process-tree.ts), can
+    // run outside that minimal synchronous window, so it additionally PROBES group
+    // liveness (POSIX signal 0) and skips the reap once the group has fully
+    // drained — see its "POST-EXIT GROUP-KILL (scoped)" comment.
+    const usePosixProcessGroups = process.platform !== 'win32';
+    let isShuttingDown = false;
+    let frontendRestarts = [];
+    let respawnTimer = null;
+    const announceFrontendReady = async (child, suffix = '') => {
+        try {
+            await waitForPort(frontendPort);
+            // Reset the restart budget only when OUR child is the one now bound to
+            // `:3100`. `waitForPort` is a liveness-only probe — it cannot tell our
+            // Vite from a foreign listener (a leftover Vite or a second dev server),
+            // and crediting a foreign listener would make every `--strictPort`-failing
+            // respawn look successful, neutralizing the `maxRestarts` cap and
+            // hot-looping forever (see {@link shouldCreditFrontendReady}). Only
+            // *consecutive failing* restarts should count toward the give-up
+            // threshold, so a frontend that legitimately restarts many times (e.g.
+            // editor-triggered Vite full reloads) still never gets left down.
+            if (shouldCreditFrontendReady(child, frontendProcess)) {
+                frontendRestarts = [];
+            }
+            console.log(`\n  ➜  http://localhost:${port}/${suffix}\n`);
+        }
+        catch (e) {
+            console.error(`⚠️  Frontend did not start: ${e.message}`);
+            console.log(`\n  ➜  http://localhost:${port}/  (API only — frontend unavailable)\n`);
+        }
+    };
+    const spawnFrontend = (command) => {
+        const child = spawn(command, {
+            shell: true,
+            // Own process group on POSIX so we can reap the Vite grandchild too.
+            detached: usePosixProcessGroups,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, NODE_OPTIONS: '' },
+        });
+        frontendProcess = child;
+        // Suppress frontend output — only show errors.
+        child.stderr?.on('data', (d) => {
+            const msg = d.toString();
+            if (!msg.includes('DeprecationWarning'))
+                process.stderr.write(msg);
+        });
+        child.on('exit', (code, signal) => {
+            // Ignore exits from a process we've already replaced or torn down.
+            if (child !== frontendProcess)
+                return;
+            frontendProcess = null;
+            if (isShuttingDown)
+                return;
+            // Reap any orphaned grandchild left in this child's group so `:3100` is
+            // free before we respawn — otherwise `--strictPort` makes the new Vite
+            // exit on bind and we'd spin until the restart budget is gone. The shell
+            // has already exited here (we are inside its `exit` handler), so this is a
+            // post-exit group kill; it is issued synchronously in this handler and is
+            // safe against PID reuse — see POST-EXIT GROUP-KILL POLICY above.
+            killFrontendTree(child, 'SIGKILL');
+            const decision = evaluateFrontendRespawn(frontendRestarts, Date.now());
+            frontendRestarts = decision.recent;
+            const why = `code=${code ?? 'null'}, signal=${signal ?? 'null'}`;
+            if (!decision.restart) {
+                console.error(`⚠️  Frontend dev server exited (${why}) and exceeded ` +
+                    `${DEFAULT_FRONTEND_RESPAWN_POLICY.maxRestarts} restarts within ` +
+                    `${DEFAULT_FRONTEND_RESPAWN_POLICY.windowMs / 1000}s — leaving it down. ` +
+                    `Fix the error above, then restart \`npm run dev\`.`);
+                return;
+            }
+            console.error(`⚠️  Frontend dev server exited (${why}); restarting in ${decision.delayMs}ms…`);
+            respawnTimer = setTimeout(() => {
+                respawnTimer = null;
+                if (isShuttingDown)
+                    return;
+                // Before relaunching, wait (bounded) for `:3100` to actually free —
+                // mirroring the graceful `terminateFrontend` path. The synchronous
+                // post-exit SIGKILL above only *initiates* teardown of the orphaned
+                // group; the kernel can still hold the listening socket for a beat, and a
+                // relaunched `--strictPort` Vite would then hit `EADDRINUSE` and burn a
+                // restart-budget slot on a race that isn't a real crash. The budget was
+                // already debited above, so this never double-counts a restart; re-check
+                // `isShuttingDown` after the await, since a shutdown signal can land while
+                // we wait (`waitForPortFree` is bounded, so it can't deadlock shutdown).
+                void (async () => {
+                    await waitForPortFree(frontendPort);
+                    if (isShuttingDown)
+                        return;
+                    const next = spawnFrontend(command);
+                    await announceFrontendReady(next, '  (frontend restarted)');
+                })();
+            }, decision.delayMs);
+            // INTENTIONAL unref: the listening HTTP `server` (created below) owns this
+            // process's lifetime — the backoff timer must NOT, by itself, keep the
+            // event loop alive. Without unref a pending respawn timer would hold the
+            // process up during shutdown (or after the server has closed), delaying or
+            // blocking a clean exit. This never drops a legitimately-needed respawn:
+            // `cleanup` explicitly clears this timer, and both the timer body and the
+            // awaited relaunch re-check `isShuttingDown`. Do NOT remove the unref to
+            // "fix" a perceived missed restart — it would reintroduce that shutdown hang.
+            respawnTimer.unref?.();
+        });
+        return child;
+    };
+    /**
+     * Gracefully terminate the frontend tree and wait (bounded) for the port to
+     * actually free before this process exits, so a `tsx watch` relaunch can
+     * rebind `:3100` cleanly. SIGTERM the group, escalate to SIGKILL if it lingers
+     * (via the shared {@link terminateProcessTree}), then poll until `:3100` is
+     * released. tsx-watch gives us ~5s before it force-kills us, so this budget is
+     * safe. Crucially the port-free wait runs on *both* paths — including when the
+     * shell has already exited — so the post-exit branch no longer drops the
+     * "wait for the port to free" guarantee.
+     */
+    const terminateFrontend = async (child) => {
+        if (!child)
+            return;
+        // SIGTERM→SIGKILL the whole tree, reaping the detached Vite grandchild even
+        // when the shell has already exited (post-exit group kill — see policy).
+        await terminateProcessTree(child, 1500);
+        // Then wait (bounded) for `:3100` to be released. The old post-exit branch
+        // returned right after SIGKILL with no port poll, so a relaunch could race
+        // the kernel's socket teardown and hit `--strictPort` `EADDRINUSE`.
+        await waitForPortFree(frontendPort);
+    };
     // ── API Gateway proxy (sandbox mode) ───────────────────────────────────
     // `changeOrigin: true` rewrites the outgoing `Host` to the execute-api target
     // (required for API Gateway's TLS SNI / host-based routing). That would make
@@ -266,35 +506,13 @@ export async function startDevServer(options) {
         await writeClientCode(resolvedPath, clientPath);
     }
     // ── Start listening ────────────────────────────────────────────────────
-    server.listen(port, '127.0.0.1', async () => {
+    server.listen(port, async () => {
         console.log(`AWS Blocks local server running on http://localhost:${port}`);
         buildAndSendEvent({ command: 'dev', state: 'SUCCESS', duration: Date.now() - devStartTime });
         // Spawn frontend dev server after Blocks server is ready
         if (frontendCommand) {
-            frontendProcess = spawn(frontendCommand, {
-                shell: true,
-                stdio: ['ignore', 'pipe', 'pipe'],
-                env: { ...process.env, NODE_OPTIONS: '' },
-            });
-            // Suppress frontend output — only show errors
-            frontendProcess.stderr?.on('data', (d) => {
-                const msg = d.toString();
-                if (!msg.includes('DeprecationWarning'))
-                    process.stderr.write(msg);
-            });
-            frontendProcess.on('exit', (code) => {
-                if (code !== 0 && code !== null) {
-                    console.error(`⚠️  Frontend process exited with code ${code}`);
-                }
-            });
-            try {
-                await waitForPort(frontendPort);
-                console.log(`\n  ➜  http://localhost:${port}/\n`);
-            }
-            catch (e) {
-                console.error(`⚠️  Frontend did not start: ${e.message}`);
-                console.log(`\n  ➜  http://localhost:${port}/  (API only — frontend unavailable)\n`);
-            }
+            const child = spawnFrontend(frontendCommand);
+            await announceFrontendReady(child);
         }
         else {
             console.log(`\n  ➜  http://localhost:${port}/\n`);
@@ -305,10 +523,26 @@ export async function startDevServer(options) {
         buildAndSendEvent({ command: 'dev', state: 'FAIL', duration: Date.now() - devStartTime, error: { code: errorCode, phase: 'startup' } });
     });
     // ── Cleanup ────────────────────────────────────────────────────────────
+    const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+    let cleaningUp = false;
     const cleanup = async () => {
+        if (cleaningUp)
+            return; // idempotent — a second signal must not re-enter
+        cleaningUp = true;
+        isShuttingDown = true; // stop the supervisor from respawning the frontend
         console.log('\nShutting down...');
-        if (frontendProcess)
-            frontendProcess.kill('SIGTERM');
+        if (respawnTimer) {
+            clearTimeout(respawnTimer);
+            respawnTimer = null;
+        }
+        // Detach our own listeners so repeated signals can't pile up handlers.
+        for (const sig of signals)
+            process.removeListener(sig, cleanup);
+        // Kill the frontend process *group* and wait for the port to free before
+        // we exit, so a tsx-watch restart can rebind `:3100` cleanly.
+        const child = frontendProcess;
+        frontendProcess = null;
+        await terminateFrontend(child);
         if (typeof backend.__cleanup === 'function') {
             try {
                 await backend.__cleanup();
@@ -320,8 +554,24 @@ export async function startDevServer(options) {
         server.close(() => process.exit(0));
         setTimeout(() => process.exit(0), 2000).unref();
     };
-    process.on('SIGINT', cleanup);
-    process.on('SIGTERM', cleanup);
+    for (const sig of signals)
+        process.on(sig, cleanup);
+    // Last-resort safety net for paths that bypass `cleanup` (e.g. an uncaught
+    // exception terminating the process): synchronously reap the frontend tree so
+    // a `detached` Vite is never left orphaned on `:3100`. Reuses
+    // `killFrontendTree`, so unlike the old hand-rolled `process.kill(-pid)` it
+    // also reaps on Windows (via `taskkill`) instead of early-returning and
+    // leaking the Vite tree, and stays in lockstep with the other kill sites. Both
+    // the POSIX group kill and the Windows `taskkill` are synchronous, so this is
+    // legal in an `exit` handler; it reaps even when the shell has already exited
+    // (a surviving grandchild keeps the group alive) — see POST-EXIT GROUP-KILL
+    // POLICY above.
+    process.once('exit', () => {
+        const child = frontendProcess;
+        if (!child)
+            return;
+        killFrontendTree(child, 'SIGKILL');
+    });
 }
 // ── Local API handler ────────────────────────────────────────────────────────
 function handleApiRequest(req, res, url, method, apis) {

package/dist/scripts/ensure-secrets.d.ts

@@ -8,9 +8,12 @@ export declare function findConnectionString(): {
     value: string;
 } | null;
 /**
- * Ensure the connection string is stored in SSM for the current stage.
+ * Ensure the connection string is stored in SSM under this app's stack-scoped
+ * parameter name. `projectRoot` locates the committed `.blocks/config.json`
+ * that defines the stack name; it must match the root used at synth (the deploy
+ * commands pass it explicitly) so the written name equals the name the app reads.
  */
-export declare function ensureSecrets(stage?: 'sandbox' | 'production'): Promise<EnsureSecretsResult>;
+export declare function ensureSecrets(stage?: string, projectRoot?: string): Promise<EnsureSecretsResult>;
 /**
  * Load environment for production deployment.
  *

package/dist/scripts/ensure-secrets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ensure-secrets.d.ts","sourceRoot":"","sources":["../../src/scripts/ensure-secrets.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,wBAAgB,oBAAoB,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAO7E;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,YAAY,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAsClG;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAIxC;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAelD"}
+{"version":3,"file":"ensure-secrets.d.ts","sourceRoot":"","sources":["../../src/scripts/ensure-secrets.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,wBAAgB,oBAAoB,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAO7E;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,KAAK,CAAC,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,mBAAmB,CAAC,CAsC9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAIxC;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAelD"}

package/dist/scripts/ensure-secrets.js

@@ -3,15 +3,20 @@
 /**
  * Pre-deploy secret provisioning.
  *
- * Writes the connection string to an SSM SecureString parameter.
- * Parameter name includes the stage to prevent sandbox/prod collision:
- *   /blocks/{stage}/db-connection-string
+ * Writes the connection string to an SSM SecureString parameter. The parameter
+ * name is stack-scoped (`/<stackName>-db-url` via `dbConnectionParameterName`),
+ * so two Blocks apps in the same account/region/stage never collide. The synth
+ * step names the parameter with the same function and the same inputs
+ * (`projectRoot` + stage), so the value written here is read back under the
+ * identical name — which is why this must be given the same `projectRoot` the
+ * deploy command passes to synth.
  *
  * On first deploy: creates the parameter.
  * On subsequent deploys: updates if value changed, no-op otherwise.
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { dbConnectionParameterName } from '../db-naming.js';
+import { getStackName } from './stack-id.js';
 const CONNECTION_STRING_PATTERN = /_(DB_URL|CONNECTION_STRING)$/;
 export function findConnectionString() {
     for (const [name, value] of Object.entries(process.env)) {
@@ -22,9 +27,12 @@ export function findConnectionString() {
     return null;
 }
 /**
- * Ensure the connection string is stored in SSM for the current stage.
+ * Ensure the connection string is stored in SSM under this app's stack-scoped
+ * parameter name. `projectRoot` locates the committed `.blocks/config.json`
+ * that defines the stack name; it must match the root used at synth (the deploy
+ * commands pass it explicitly) so the written name equals the name the app reads.
  */
-export async function ensureSecrets(stage) {
+export async function ensureSecrets(stage, projectRoot) {
     const result = { created: [], updated: [], unchanged: [] };
     const conn = findConnectionString();
     if (!conn)
@@ -32,7 +40,7 @@ export async function ensureSecrets(stage) {
     const resolvedStage = stage ?? process.env.BLOCKS_STAGE ?? 'sandbox';
     const { SSMClient, GetParameterCommand, PutParameterCommand } = await import('@aws-sdk/client-ssm');
     const client = new SSMClient();
-    const parameterName = dbConnectionParameterName(resolvedStage);
+    const parameterName = dbConnectionParameterName(getStackName({ sandbox: resolvedStage !== 'production', projectRoot }));
     let isNew = false;
     try {
         const current = await client.send(new GetParameterCommand({

package/dist/scripts/external-migrations-step.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"external-migrations-step.d.ts","sourceRoot":"","sources":["../../src/scripts/external-migrations-step.ts"],"names":[],"mappings":"AAmCA;;;;;GAKG;AACH;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAI5G;AAcD,MAAM,WAAW,8BAA8B;IAC7C,KAAK,EAAE,SAAS,GAAG,YAAY,CAAC;IAChC,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,SAAS,GAAG,YAAY,GAAG,OAAO,CAErF;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,8BAA8B,GAAG,OAAO,CAAC,OAAO,CAAC,CAkBpG;AAoBD,qFAAqF;AACrF,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAe3E;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO,CAExF;AAuED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CA8BnH"}
+{"version":3,"file":"external-migrations-step.d.ts","sourceRoot":"","sources":["../../src/scripts/external-migrations-step.ts"],"names":[],"mappings":"AAoCA;;;;;GAKG;AACH;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAI5G;AAcD,MAAM,WAAW,8BAA8B;IAC7C,KAAK,EAAE,SAAS,GAAG,YAAY,CAAC;IAChC,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,SAAS,GAAG,YAAY,GAAG,OAAO,CAErF;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,8BAA8B,GAAG,OAAO,CAAC,OAAO,CAAC,CAkBpG;AAoBD,qFAAqF;AACrF,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAe3E;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO,CAExF;AA0ED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CA8BnH"}

package/dist/scripts/external-migrations-step.js

@@ -25,6 +25,7 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { findConnectionString } from './ensure-secrets.js';
 import { extractDbRef, dbConnectionParameterName } from '../db-naming.js';
+import { getStackName } from './stack-id.js';
 import { runSync } from './run-command.js';
 const DEFAULT_MIGRATIONS_DIR = './migrations';
 /** Default output dir for db-pull generated files (database.types.ts / database.meta.ts). */
@@ -150,7 +151,10 @@ async function productionRefs(devRef) {
     }
     try {
         const { SSMClient, GetParameterCommand } = await import('@aws-sdk/client-ssm');
-        const res = await new SSMClient().send(new GetParameterCommand({ Name: dbConnectionParameterName('production'), WithDecryption: true }));
+        const res = await new SSMClient().send(new GetParameterCommand({
+            Name: dbConnectionParameterName(getStackName({ sandbox: false })),
+            WithDecryption: true,
+        }));
         const v = res.Parameter?.Value;
         const r = v ? safeRef(v) : null;
         if (r)

package/dist/scripts/index.d.ts

@@ -9,4 +9,5 @@ export { openConsole, type ConsoleOptions } from './console.js';
 export { ensureSecrets, loadProductionEnv, loadEnvFile } from './ensure-secrets.js';
 export { trackCommand, buildAndSendEvent, classifyError, type CommandName, type CommandState, type BuildAndSendEventOptions, } from '../telemetry/index.js';
 export { telemetry, type TelemetryOptions } from './telemetry.js';
+export { getStackId, getSandboxId, getStackName } from './stack-id.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/scripts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scripts/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,wBAAwB,GAC9B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scripts/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,wBAAwB,GAC9B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/scripts/index.js

@@ -11,3 +11,4 @@ export { openConsole } from './console.js';
 export { ensureSecrets, loadProductionEnv, loadEnvFile } from './ensure-secrets.js';
 export { trackCommand, buildAndSendEvent, classifyError, } from '../telemetry/index.js';
 export { telemetry } from './telemetry.js';
+export { getStackId, getSandboxId, getStackName } from './stack-id.js';