@aws-blocks/core 0.1.4 → 0.1.10

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"}

package/dist/scripts/process-tree.js

@@ -0,0 +1,198 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { spawnSync } from 'node:child_process';
+/**
+ * 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 function windowsTreeKill(pid, runner = (command, args) => spawnSync(command, args, { stdio: 'ignore', windowsHide: true })) {
+    try {
+        const { status, error } = runner('taskkill', ['/T', '/F', '/PID', String(pid)]);
+        // Couldn't even spawn taskkill (e.g. not on PATH) → not handled; fall back.
+        if (error)
+            return false;
+        // taskkill ran: only exit 0 (reaped the tree) or 128 ("process not found",
+        // already gone) mean the tree is handled. Any other non-null status (e.g.
+        // 1 = access denied) means taskkill ran but did NOT reap the tree, so report
+        // not-handled and let the caller fall back to a direct child.kill.
+        return status === 0 || status === 128;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 function killFrontendTree(child, signal = 'SIGTERM', platform = process.platform, killFn = (p, s) => process.kill(p, s), winTreeKill = windowsTreeKill) {
+    const { pid } = child;
+    // pid > 1 guards against signalling the whole current group (-0) or init (-1).
+    if (pid && pid > 1) {
+        if (platform !== 'win32') {
+            try {
+                killFn(-pid, signal);
+                return;
+            }
+            catch {
+                // Group already gone or signal failed — fall through to a direct kill.
+            }
+        }
+        else if (winTreeKill(pid)) {
+            // taskkill walked the PID tree and reaped the Vite grandchild.
+            return;
+        }
+    }
+    try {
+        child.kill(signal);
+    }
+    catch {
+        // Process already exited; nothing to do.
+    }
+}
+const defaultSleep = (ms) => new Promise((res) => {
+    setTimeout(res, ms).unref?.();
+});
+/**
+ * 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 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 function isProcessGroupAlive(pid, platform = process.platform, kill = (p, s) => process.kill(p, s)) {
+    if (platform === 'win32')
+        return true;
+    try {
+        kill(-pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+/**
+ * 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 async function terminateProcessTree(child, graceMs = 2000, killTree = killFrontendTree, sleep = defaultSleep, isGroupAlive = isProcessGroupAlive) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        // ── POST-EXIT GROUP-KILL (scoped) ──────────────────────────────────────
+        // The direct child has already exited, but a detached *grandchild* (e.g. an
+        // orphaned Vite) may still be alive in its process group, still holding a
+        // port — reap it with one best-effort group SIGKILL.
+        //
+        // SCOPING: only reap when the group still has a live member. killFrontendTree's
+        // `-pid` group signal is PID-reuse-safe ONLY while a member keeps `pid`
+        // reserved as the group id; once the whole group has drained `pid` can be
+        // recycled and a blind `process.kill(-pid)` could hit an unrelated group. So
+        // we probe first (isProcessGroupAlive; POSIX signal 0) and skip when already
+        // drained — there is then nothing of ours to reap. The residual synchronous
+        // probe→kill window is the accepted trade-off documented in dev-server.ts
+        // "POST-EXIT GROUP-KILL POLICY", cross-referenced here so the risk is
+        // discoverable at this shared primitive.
+        const { pid } = child;
+        if (pid && pid > 1 && isGroupAlive(pid)) {
+            killTree(child, 'SIGKILL');
+        }
+        return true;
+    }
+    const exited = new Promise((res) => child.once('exit', () => res()));
+    killTree(child, 'SIGTERM');
+    const exitedCleanly = await Promise.race([
+        exited.then(() => true),
+        sleep(graceMs).then(() => false),
+    ]);
+    if (exitedCleanly)
+        return true;
+    killTree(child, 'SIGKILL');
+    // Shorter, fixed grace after SIGKILL (vs. the injectable SIGTERM graceMs):
+    // SIGKILL is uncatchable, so we only need a brief beat to observe `exit`.
+    await Promise.race([exited, sleep(KILL_GRACE_MS)]);
+    return child.exitCode !== null || child.signalCode !== null;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/scripts/sandbox.ts"],"names":[],"mappings":"AA8BA,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,cAAc,+BAqJzD;AAED,wBAAsB,cAAc,CAAC,WAAW,EAAE,MAAM,iBAwCvD"}
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/scripts/sandbox.ts"],"names":[],"mappings":"AA+BA,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,cAAc,+BAkMzD;AAED,wBAAsB,cAAc,CAAC,WAAW,EAAE,MAAM,iBAwCvD"}

package/dist/scripts/sandbox.js

@@ -10,6 +10,7 @@ import { trackCommand } from '../telemetry/trackCommand.js';
 import { buildAndSendEvent } from '../telemetry/client.js';
 import { getCdkTelemetryEnv } from './cdk-telemetry-env.js';
 import { runSync, spawnCommand } from './run-command.js';
+import { terminateProcessTree } from './process-tree.js';
 /**
  * Import the backend definition to populate the Scope BB registry.
  *
@@ -40,7 +41,9 @@ export async function startSandbox(options) {
     process.env.BLOCKS_STAGE = 'sandbox';
     // Provision connection string to SSM SecureString.
     // On first deploy, creates the parameter. On subsequent deploys, updates if changed.
-    const secrets = await ensureSecrets('sandbox');
+    // projectRoot is process.cwd() — the same value passed to cdk as --context
+    // projectRoot below — so the written name matches the name resolved at synth.
+    const secrets = await ensureSecrets('sandbox', process.cwd());
     if (secrets.created.length > 0) {
         console.log(`🔐 Created secrets: ${secrets.created.join(', ')}`);
     }
@@ -58,6 +61,13 @@ export async function startSandbox(options) {
     try {
         runSync("npm", [
             "exec", "cdk", "--", "deploy",
+            // `--all`: an app that uses Lambda@Edge (e.g. a Next.js route with
+            // `export const runtime = 'edge'`) synthesizes a SECOND stack
+            // (`edge-lambda-stack-*`, region us-east-1) in addition to the main
+            // hosting stack. Without `--all`, CDK refuses with "specify which
+            // stacks to use". Deploying every stack in a sandbox app is the
+            // intended behavior, so select them all.
+            "--all",
             "--require-approval", "never",
             "--outputs-file", `${outDir}/outputs.json`,
             "--context", `projectRoot=${process.cwd()}`,
@@ -121,6 +131,12 @@ export async function startSandbox(options) {
         `--app`, `npm exec tsx -- -C cdk ${backendPath}`
     ], {
         stdio: ["ignore", "pipe", "pipe"],
+        // Own process group on POSIX so cleanup can reap the whole `cdk watch` tree
+        // (npx → cdk → node) via terminateProcessTree, not just the npx shell — a
+        // bare kill() would orphan the real cdk-watch node process, the same
+        // shell-only-kill leak this PR eliminates for the dev server. Windows has no
+        // groups; terminateProcessTree reaps the tree via taskkill.
+        detached: process.platform !== 'win32',
         env: { ...process.env, NODE_OPTIONS: "--conditions=cdk", ...getCdkTelemetryEnv('sandbox') },
     });
     cdkWatch.stdout?.on("data", (data) => {
@@ -137,18 +153,49 @@ export async function startSandbox(options) {
     const devServer = spawnCommand(cmd, args, {
         stdio: "inherit",
         shell: true,
+        // Own process group on POSIX so cleanup can signal the whole dev-server
+        // tree (shell → tsx → node). The node dev server then runs its own SIGTERM
+        // handler — the ~2s terminateFrontend drain that reaps the *detached* Vite
+        // great-grandchild — which a bare `devServer.kill()` (the shell only) never
+        // triggers. Windows has no groups; terminateProcessTree reaps via taskkill.
+        detached: process.platform !== 'win32',
         env: {
             ...process.env,
             NODE_OPTIONS: '',
             BLOCKS_API_URL: apiUrl,
         },
     });
-    const cleanup = () => {
+    let cleaningUp = false;
+    const cleanup = async () => {
+        if (cleaningUp)
+            return; // idempotent — a second signal must not re-enter
+        cleaningUp = true;
         console.log("\n\n🛑 Stopping local processes...");
         console.log("   (AWS resources are still running)");
         console.log("\n   To destroy AWS resources, run: npm run sandbox:destroy\n");
-        cdkWatch.kill();
-        devServer.kill();
+        // Reap BOTH child trees the way the dev server reaps Vite — a process-group
+        // SIGTERM→SIGKILL via the shared terminateProcessTree — instead of a bare
+        // kill() that signals only the npx/shell parent and orphans the real
+        // grandchild (cdk-watch's node, or the dev server's detached Vite). Run them
+        // concurrently so the cdk-watch teardown doesn't serialize on top of the dev
+        // server's longer drain.
+        //
+        // Only the dev-server child owns the `:3100` port-free wait: its own SIGTERM
+        // handler runs terminateFrontend (a ~2s drain that reaps the detached Vite
+        // great-grandchild AND polls until the port frees), so we give it the longer
+        // 6s budget (> that ~2s drain) — a hung dev server still escalates to a tree
+        // SIGKILL and we exit regardless, so shutdown can never wedge. cdk watch
+        // holds no local port, so a bounded tree-kill is all it needs.
+        //
+        // That a group SIGTERM (terminateProcessTree → killFrontendTree's
+        // `process.kill(-pid, 'SIGTERM')`) actually reaches the *nested* node dev
+        // server and runs its own SIGTERM handler — the load-bearing assumption of
+        // the 6s budget above — is verified by the "group SIGTERM reaches a nested
+        // node child" integration test in dev-server-supervisor.test.ts.
+        await Promise.all([
+            terminateProcessTree(cdkWatch, 2000),
+            terminateProcessTree(devServer, 6000),
+        ]);
         process.exit(0);
     };
     process.on("SIGINT", cleanup);

package/dist/scripts/stack-id.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Get the stackId from `.blocks/config.json` in the project root.
+ * This is the stable project identifier used as the base for CloudFormation stack names.
+ */
+export declare function getStackId(projectRoot?: string): string;
+/**
+ * Get or create a per-machine sandbox identifier.
+ * Stored in `.blocks-sandbox/sandbox-id.txt` (gitignored).
+ * Format: `<username(8)>-<random(6)>` — identifies the developer's sandbox.
+ *
+ * Get-or-create (lazy init): returns the existing id, or generates and persists
+ * one on first call. The file is the shared sync point — once written, every
+ * later caller and every process reads the same id, so the secret writer
+ * (`ensureSecrets`) and synth derive identical names.
+ */
+export declare function getSandboxId(projectRoot?: string): string;
+/**
+ * The full CloudFormation stack name for a deployment.
+ *
+ * Single source of truth for the stack-name scheme (D-012): production is
+ * `<stackId>-prod`; a sandbox is `<stackId>-<sandboxId>`. The CDK templates name
+ * the stack with this function, and the external-DB connection-string parameter
+ * name (`dbConnectionParameterName`) is derived from it — so a deployed stack and
+ * the parameter holding its database credentials can never use divergent names.
+ *
+ * This function reads committed config (`.blocks/config.json`, throws if absent
+ * — D-012) and resolves the sandbox id via {@link getSandboxId} (get-or-create):
+ * the first caller materializes `.blocks-sandbox/sandbox-id.txt`, every later
+ * caller reads the same value. Because that file persists and is shared across
+ * processes, the secret writer (`ensureSecrets`) and synth resolve identical
+ * names. Production does not use the sandbox id.
+ */
+export declare function getStackName(opts: {
+    sandbox: boolean;
+    projectRoot?: string;
+}): string;
+//# sourceMappingURL=stack-id.d.ts.map

package/dist/scripts/stack-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-id.d.ts","sourceRoot":"","sources":["../../src/scripts/stack-id.ts"],"names":[],"mappings":"AAiBA;;;GAGG;AACH,wBAAgB,UAAU,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAavD;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAWzD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAGrF"}

package/dist/scripts/stack-id.js

@@ -0,0 +1,79 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { execSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+function randomSuffix(length) {
+    return randomBytes(length).toString('hex').slice(0, length);
+}
+/**
+ * Get the stackId from `.blocks/config.json` in the project root.
+ * This is the stable project identifier used as the base for CloudFormation stack names.
+ */
+export function getStackId(projectRoot) {
+    const root = projectRoot || process.cwd();
+    const configPath = join(root, '.blocks', 'config.json');
+    try {
+        const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+        if (!config.stackId)
+            throw new Error('missing key');
+        return config.stackId;
+    }
+    catch {
+        throw new Error(`.blocks/config.json not found or missing stackId — it is created by create-blocks-app and should be committed. ` +
+            `To fix manually, create ${configPath} with: { "stackId": "<your-app-name>" }`);
+    }
+}
+/**
+ * Get or create a per-machine sandbox identifier.
+ * Stored in `.blocks-sandbox/sandbox-id.txt` (gitignored).
+ * Format: `<username(8)>-<random(6)>` — identifies the developer's sandbox.
+ *
+ * Get-or-create (lazy init): returns the existing id, or generates and persists
+ * one on first call. The file is the shared sync point — once written, every
+ * later caller and every process reads the same id, so the secret writer
+ * (`ensureSecrets`) and synth derive identical names.
+ */
+export function getSandboxId(projectRoot) {
+    const root = projectRoot || process.cwd();
+    const filePath = join(root, '.blocks-sandbox', 'sandbox-id.txt');
+    if (existsSync(filePath))
+        return readFileSync(filePath, 'utf-8').trim();
+    const dir = dirname(filePath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const username = getUsername().toLowerCase().replace(/[^a-z0-9]/g, '').slice(0, 8) || 'dev';
+    const random = randomSuffix(6);
+    const id = `${username}-${random}`;
+    writeFileSync(filePath, id);
+    return id;
+}
+/**
+ * The full CloudFormation stack name for a deployment.
+ *
+ * Single source of truth for the stack-name scheme (D-012): production is
+ * `<stackId>-prod`; a sandbox is `<stackId>-<sandboxId>`. The CDK templates name
+ * the stack with this function, and the external-DB connection-string parameter
+ * name (`dbConnectionParameterName`) is derived from it — so a deployed stack and
+ * the parameter holding its database credentials can never use divergent names.
+ *
+ * This function reads committed config (`.blocks/config.json`, throws if absent
+ * — D-012) and resolves the sandbox id via {@link getSandboxId} (get-or-create):
+ * the first caller materializes `.blocks-sandbox/sandbox-id.txt`, every later
+ * caller reads the same value. Because that file persists and is shared across
+ * processes, the secret writer (`ensureSecrets`) and synth resolve identical
+ * names. Production does not use the sandbox id.
+ */
+export function getStackName(opts) {
+    const base = getStackId(opts.projectRoot);
+    return opts.sandbox ? `${base}-${getSandboxId(opts.projectRoot)}` : `${base}-prod`;
+}
+function getUsername() {
+    try {
+        return execSync('git config user.name', { encoding: 'utf-8' }).trim();
+    }
+    catch {
+        return process.env.USER || process.env.USERNAME || 'user';
+    }
+}

package/dist/scripts/stack-id.test.d.ts

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

package/dist/scripts/stack-id.test.d.ts.map

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