@aws-blocks/core 0.1.4 → 0.1.7

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/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 } 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,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 } from './stack-id.js';

package/dist/scripts/process-tree.d.ts

@@ -0,0 +1,126 @@
+/** Minimal child-process surface needed to terminate a frontend dev server. */
+export interface KillableProcess {
+    pid?: number;
+    kill(signal?: NodeJS.Signals | number): boolean;
+}
+/** Subset of {@link import('node:child_process').SpawnSyncReturns} that {@link windowsTreeKill} inspects. */
+interface TreeKillResult {
+    status: number | null;
+    error?: Error;
+}
+/**
+ * Force-kill an entire process tree on Windows via `taskkill /T /F /PID <pid>`.
+ *
+ * Windows has no POSIX process groups, so a bare `child.kill()` only signals the
+ * spawned shell and orphans the real dev server (the Vite grandchild), which
+ * keeps holding `:3100` — the very wedge the POSIX process-group kill fixes.
+ * `taskkill /T` walks the live child tree by PID and terminates every
+ * descendant; `/F` is required because Windows cannot deliver a graceful
+ * shutdown to a non-console subtree anyway (Node maps SIGTERM/SIGKILL to
+ * `TerminateProcess`).
+ *
+ * Returns `true` only when `taskkill` ran AND reported the tree handled — exit
+ * `0` (reaped the tree) or `128` (`"process not found"`, i.e. already gone).
+ * Returns `false` when the command could not be spawned at all (e.g. not on
+ * `PATH`) OR when it ran but returned any other status (e.g. `1` = access
+ * denied): such a run did NOT reap the tree, so the caller must fall back to a
+ * direct `child.kill` rather than treat the leak as handled. (`child.kill`
+ * cannot reap the orphaned grandchild either, but the fallback is cheap and
+ * strictly correct — we never silently swallow a failed tree-kill.) Never
+ * throws.
+ */
+export declare function windowsTreeKill(pid: number, runner?: (command: string, args: readonly string[]) => TreeKillResult): boolean;
+/**
+ * Terminate a process spawned with `shell: true`, including its descendants, on
+ * every platform.
+ *
+ * Under a shell the real dev server (e.g. Vite) is a **grandchild**: the direct
+ * child is the shell, so signalling only the shell (`child.kill`) orphans the
+ * grandchild, which keeps holding its port (`:3100`) and wedges the next
+ * restart.
+ *
+ * - **POSIX**: the process is spawned `detached` (its own process group,
+ *   pgid === child.pid), so we signal the whole group with
+ *   `process.kill(-pid, signal)` and every descendant dies, freeing the port.
+ * - **Windows**: there are no process groups, so we reap the tree with
+ *   `taskkill /T /F /PID <pid>` (see {@link windowsTreeKill}), which walks the
+ *   child tree by PID. A bare `child.kill` would leave the Vite grandchild
+ *   bound to `:3100`, reproducing the POSIX wedge.
+ *
+ * Best-effort and never throws: a missing/invalid pid, an already-dead group
+ * (ESRCH), a failed group signal, or an unavailable `taskkill` all degrade to a
+ * direct `child.kill`.
+ */
+export declare function killFrontendTree(child: KillableProcess, signal?: NodeJS.Signals, platform?: NodeJS.Platform, killFn?: (pid: number, signal: NodeJS.Signals) => void, winTreeKill?: (pid: number) => boolean): void;
+/** Child surface {@link terminateProcessTree} needs: a tree to kill plus exit state to await. */
+export interface AwaitableChild extends KillableProcess {
+    exitCode: number | null;
+    signalCode: NodeJS.Signals | null;
+    once(event: 'exit', listener: () => void): unknown;
+}
+/**
+ * Grace (ms) we wait for the child's `exit` event *after* SIGKILL before giving
+ * up and reporting its last-known exit state. Deliberately shorter than — and
+ * intentionally decoupled from — the injectable SIGTERM `graceMs`: SIGKILL
+ * cannot be caught, blocked, or handled, so the child is already being
+ * force-terminated; we only need a brief beat to observe the `exit` event, not a
+ * full, tunable shutdown window. Fixed (not a parameter) because no caller needs
+ * to tune it — the injected `sleep` is the test seam.
+ */
+export declare const KILL_GRACE_MS = 500;
+/**
+ * Probe whether a detached process *group* still has at least one live member,
+ * **without signalling it**. Used to scope the post-exit group SIGKILL in
+ * {@link terminateProcessTree} to the only window where the `-pid` group signal
+ * is PID-reuse-safe.
+ *
+ * The hazard: {@link killFrontendTree}'s POSIX reap is `process.kill(-pid, …)`,
+ * which targets the process group whose gid is `pid`. That is safe only while a
+ * group member is still alive — a survivor keeps the kernel from recycling
+ * `pid` as a brand-new (unrelated) group leader. Once the whole group has
+ * drained, `pid` is eligible for reuse and a blind `-pid` kill could land on an
+ * unrelated group. So before a *post-exit* reap we probe here and skip when the
+ * group has already drained (there is then nothing of ours left to reap).
+ *
+ * - **POSIX**: `kill(-pid, 0)` sends no signal — it only checks the group
+ *   exists and is signallable. Success or `EPERM` (exists but owned by another
+ *   user) ⇒ alive. `ESRCH` (or anything else) ⇒ treat as drained.
+ * - **Windows**: there are no process groups and the reap path
+ *   (`taskkill /T /F /PID`) walks the live PID tree, so there is no `-pid`
+ *   recycle hazard — always allow the reap (`true`).
+ *
+ * Never throws. `platform`/`kill` are injected for tests.
+ */
+export declare function isProcessGroupAlive(pid: number, platform?: NodeJS.Platform, kill?: (pid: number, signal: number) => void): boolean;
+/**
+ * Terminate a child process *tree* and wait — bounded — for the child to exit,
+ * escalating SIGTERM → SIGKILL. Reuses {@link killFrontendTree} so every
+ * entrypoint reaps the same way (POSIX process-group kill / Windows `taskkill`)
+ * instead of hand-rolling its own group kill.
+ *
+ * Post-exit policy: if the child has *already* exited, a detached grandchild may
+ * still be orphaned (still holding a port), so we issue one best-effort group
+ * SIGKILL to reap it — but ONLY when the group still has a live member
+ * ({@link isProcessGroupAlive}). When the whole group has already drained (the
+ * common healthy shutdown — Vite was already gone), `pid` is eligible for
+ * recycling and a blind `-pid` signal could hit an unrelated, newly created
+ * group; since there is also nothing of ours left to reap, we skip the kill.
+ * See the dev server's "POST-EXIT GROUP-KILL POLICY" for the full rationale and
+ * the accepted residual (the synchronous probe→kill window). Otherwise we
+ * SIGTERM the tree, wait up to `graceMs` for a clean exit, then SIGKILL the tree
+ * and wait a short grace.
+ *
+ * Return value — IMPORTANT: the boolean reflects only the **direct child's**
+ * exit state (its `exitCode`/`signalCode`), NOT whole-group teardown or port
+ * release. On POSIX the SIGKILL is delivered to the whole group (`-pid`), but a
+ * surviving *detached grandchild* can outlive the awaited child and keep holding
+ * a port even after this resolves `true`. So `true` means only "the child we
+ * awaited has exited (or was already gone)" and `false` means "it was still
+ * alive when the budget elapsed" — neither guarantees the port is free. Callers
+ * that need a freed port MUST follow this with a bounded port-free wait (see
+ * `waitForPortFree` in dev-server.ts, which the dev-server child's own SIGTERM
+ * handler runs). Dependencies are injected for tests.
+ */
+export declare function terminateProcessTree(child: AwaitableChild, graceMs?: number, killTree?: (c: KillableProcess, signal: NodeJS.Signals) => void, sleep?: (ms: number) => Promise<void>, isGroupAlive?: (pid: number) => boolean): Promise<boolean>;
+export {};
+//# sourceMappingURL=process-tree.d.ts.map

package/dist/scripts/process-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-tree.d.ts","sourceRoot":"","sources":["../../src/scripts/process-tree.ts"],"names":[],"mappings":"AAaA,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;CACjD;AAED,6GAA6G;AAC7G,UAAU,cAAc;IACtB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,cACwB,GAC7E,OAAO,CAaT;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,eAAe,EACtB,MAAM,GAAE,MAAM,CAAC,OAAmB,EAClC,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAC5C,MAAM,GAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,KAAK,IAAmC,EACpF,WAAW,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAyB,GACtD,IAAI,CAqBN;AAED,iGAAiG;AACjG,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IAClC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;CACpD;AAOD;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAC5C,IAAI,GAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAmC,GACzE,OAAO,CAQT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,cAAc,EACrB,OAAO,SAAO,EACd,QAAQ,GAAE,CAAC,CAAC,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,KAAK,IAAuB,EACjF,KAAK,GAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAgB,EACnD,YAAY,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAA6B,GAC3D,OAAO,CAAC,OAAO,CAAC,CAkClB"}