@aws-blocks/core 0.1.7 → 0.1.11

package/dist/scripts/dev-server.js

@@ -3,20 +3,21 @@
 import { createServer } from 'node:http';
 import { pathToFileURL, URL } from 'node:url';
 import { resolve, dirname, join } from 'node:path';
-import { writeFileSync, mkdirSync } from 'node:fs';
+import { writeFileSync, mkdirSync, readFileSync, unlinkSync, renameSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { createConnection } from 'node:net';
 import httpProxy from 'http-proxy';
 import { writeClientCode } from './generate-client.js';
 import { ApiError } from '../errors.js';
 import { BLOCKS_RPC_PREFIX, BLOCKS_SANDBOX_PREFIX } from '../constants.js';
+import { BLOCKS_SANDBOX_DIR } from '../common/constants.js';
 import { matchRoute, lockRouteRegistry } from '../raw-route.js';
 import { registerBuiltinRoutes } from '../builtin-routes.js';
 import { parseRpcRequest, successResponse, errorResponseFromCatch, methodNotFoundResponse, } from '../rpc.js';
 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';
+import { killFrontendTree, terminateProcessTree, findListenerPids, killListenerTree } from './process-tree.js';
 function toBodyStream(text) {
     if (!text)
         return null;
@@ -70,19 +71,44 @@ async function deployLocal(backend) {
     }
     await Promise.all(initPromises);
 }
+/**
+ * Single-shot TCP probe: resolves `true` iff a connection to `port` succeeds
+ * within `timeoutMs`, else `false` (connection error or timeout). Never rejects.
+ *
+ * When `host` is omitted the port is probed on BOTH loopback families —
+ * `127.0.0.1` (IPv4) and `::1` (IPv6) — and reported open if EITHER answers.
+ * This matters because `server.listen(port, …)` (below) passes no host, so Node
+ * binds dual-stack on `::` (all interfaces, both families). A single `localhost`
+ * probe resolves to only one of `::1`/`127.0.0.1` on a given host, so an orphan
+ * holding the port on the *other* family would be invisible — leaving the
+ * startup/EADDRINUSE reclaim path blind to a port that `listen` will still
+ * reject. Probing both families keeps every "is the port bound" check in
+ * agreement with what `listen` actually contends for. Pass an explicit `host`
+ * to probe only that address.
+ *
+ * Shared by {@link waitForPort} (wait until open), {@link waitForPortFree} (wait
+ * until closed) and the startup/EADDRINUSE reclaim path so all three agree on
+ * exactly what "the port is bound" means.
+ */
+export async function isPortOpen(port, host, timeoutMs = 200) {
+    const probeOne = (h) => new Promise((resolve) => {
+        const socket = createConnection({ port, host: h }, () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.on('error', () => { socket.destroy(); resolve(false); });
+        socket.setTimeout(timeoutMs, () => { socket.destroy(); resolve(false); });
+    });
+    if (host !== undefined)
+        return probeOne(host);
+    const [v4, v6] = await Promise.all([probeOne('127.0.0.1'), probeOne('::1')]);
+    return v4 || v6;
+}
 /** Wait for a port to accept TCP connections. */
 async function waitForPort(port, maxAttempts = 60) {
     const { setTimeout: sleep } = await import('node:timers/promises');
     for (let i = 0; i < maxAttempts; i++) {
-        const connected = await new Promise((resolve) => {
-            const socket = createConnection({ port, host: 'localhost' }, () => {
-                socket.destroy();
-                resolve(true);
-            });
-            socket.on('error', () => { socket.destroy(); resolve(false); });
-            socket.setTimeout(300, () => { socket.destroy(); resolve(false); });
-        });
-        if (connected)
+        if (await isPortOpen(port, undefined, 300))
             return;
         await sleep(500);
     }
@@ -135,15 +161,7 @@ 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)
+        if (!(await isPortOpen(port, undefined, 200)))
             return;
         await sleep(100);
     }
@@ -168,9 +186,261 @@ export function shouldCreditFrontendReady(child, current) {
         child.exitCode === null &&
         child.signalCode === null);
 }
+/**
+ * Free a port left bound by a crashed / SIGKILL'd predecessor so a fresh dev
+ * server can bind the `:3000` front door — or spawn its `--strictPort` frontend
+ * on `:3100` — instead of colliding on it and crashing.
+ *
+ * No-op when the port is already free. Otherwise it discovers the listener PID(s)
+ * ({@link findListenerPids}, an `lsof`/`netstat` probe — the same fuser-style
+ * mechanism `cleanup` uses), SIGTERMs each ({@link killListenerTree}, which
+ * reuses the frontend process-group kill), waits (bounded) for release
+ * ({@link waitForPortFree}), then escalates to SIGKILL if the port is still held.
+ * This deliberately mirrors the respawn path (process-group kill + port-free
+ * wait) rather than inventing a new teardown mechanism.
+ *
+ * The caller is responsible for NOT reclaiming a *healthy peer* dev server — the
+ * singleton guard ({@link evaluateSingleton}) runs first and bows out when a live
+ * peer owns the front door, so anything still holding these ports here is an
+ * orphan. Dependencies are injected for tests; returns what it did for
+ * logging/assertions. Best-effort: never throws.
+ *
+ * Probe contract: the default `probe` is {@link isPortOpen} with no host, which
+ * checks BOTH `127.0.0.1` and `::1`. `server.listen` binds dual-stack on `::`,
+ * so an orphan holding the port on either loopback family is detected (and thus
+ * reclaimed) — a single-family `localhost` probe could miss it and no-op.
+ */
+export async function reclaimPort(port, deps = {}) {
+    const probe = deps.probe ?? ((p) => isPortOpen(p));
+    const listPids = deps.listPids ?? ((p) => findListenerPids(p));
+    const killTree = deps.killTree ?? ((pid, sig) => killListenerTree(pid, sig));
+    const waitFree = deps.waitFree ?? ((p, t) => waitForPortFree(p, t));
+    if (!(await probe(port)))
+        return { wasOpen: false, reclaimed: true, pids: [] };
+    const pids = listPids(port);
+    for (const pid of pids)
+        killTree(pid, 'SIGTERM');
+    await waitFree(port, 2000);
+    if (await probe(port)) {
+        // Still held after a graceful SIGTERM — escalate to SIGKILL. ALWAYS re-list
+        // first: the owner set can change during the wait — the original process may
+        // have exited and a NEW one grabbed the port, so SIGKILLing the stale `pids`
+        // would miss the real owner. Fall back to the stale list only if the re-list
+        // comes back empty (e.g. lsof was momentarily unavailable).
+        const killPids = listPids(port);
+        for (const pid of killPids.length ? killPids : pids)
+            killTree(pid, 'SIGKILL');
+        await waitFree(port, 2000);
+    }
+    return { wasOpen: true, reclaimed: !(await probe(port)), pids };
+}
+/**
+ * Build the console message for a startup reclaim of a port that was in use,
+ * distinguishing the three meaningfully different outcomes so the operator knows
+ * what (if anything) to do next:
+ *  - reclaimed → we freed it; startup continues.
+ *  - not reclaimed but owner PID(s) known → tell the operator exactly which
+ *    process(es) to stop and retry.
+ *  - not reclaimed and no owner PID found → nothing to point at (lsof/netstat
+ *    found no listener), so surface the generic "in use" message.
+ * `subject` describes what was reclaimed (e.g. 'a stale/orphaned listener'). Pure.
+ */
+export function reclaimMessage(port, result, subject) {
+    if (result.reclaimed) {
+        return `♻️  Reclaimed port ${port} from ${subject} before startup.`;
+    }
+    if (result.pids.length > 0) {
+        return (`⚠️  Port ${port} held by pid(s) [${result.pids.join(', ')}] and could not be freed — ` +
+            `stop that process and retry.`);
+    }
+    return `⚠️  Port ${port} is in use and could not be reclaimed automatically (no owner PID found).`;
+}
+/** Default front-door bind retry budget: 3 attempts, 250ms→750ms linear backoff. */
+export const DEFAULT_PORT_BIND_RETRY_POLICY = {
+    maxAttempts: 3,
+    backoffMs: 250,
+};
+/**
+ * Decide whether an EADDRINUSE on the `:3000` front door should trigger another
+ * reclaim-and-rebind attempt. `attempt` is the number of failures so far
+ * (1-based). Returns `retry: false` once the budget is exhausted so the caller
+ * exits non-zero with a clear message rather than looping forever. Pure.
+ */
+export function evaluatePortBindRetry(attempt, policy = DEFAULT_PORT_BIND_RETRY_POLICY) {
+    if (attempt >= policy.maxAttempts)
+        return { retry: false, delayMs: 0 };
+    return { retry: true, delayMs: policy.backoffMs * attempt };
+}
+/**
+ * Build the `:3000` front-door EADDRINUSE bind-retry handler. Extracted from the
+ * `server.on('error')` closure so the retry *wiring* — the 1-based attempt
+ * counter, the bounded {@link evaluatePortBindRetry} decision, reclaim-result
+ * routing, and retry scheduling — is unit-testable without a real socket.
+ *
+ * Returns a function to invoke on each EADDRINUSE. Per invocation it:
+ *  - increments the attempt counter and consults {@link evaluatePortBindRetry};
+ *  - on exhaustion: warns with an actionable message and calls `onExhausted`
+ *    (no further retry is scheduled);
+ *  - otherwise: warns it is retrying, then (async) reclaims the port and — when
+ *    reclaim did NOT free it — surfaces the {@link reclaimMessage} naming the
+ *    holding pid(s) so the operator isn't left with only the generic banner,
+ *    then schedules the next `relisten` after the decided backoff.
+ * Never throws.
+ */
+export function createBindRetryController(port, deps, policy = DEFAULT_PORT_BIND_RETRY_POLICY) {
+    let attempts = 0;
+    return () => {
+        attempts += 1;
+        const decision = evaluatePortBindRetry(attempts, policy);
+        if (!decision.retry) {
+            deps.warn(`\n❌ Port ${port} is still in use after ${policy.maxAttempts} ` +
+                `attempts to reclaim it — another process is holding :${port}. Stop it (or run the ` +
+                `cleanup script) and retry \`npm run dev\`.\n`);
+            deps.onExhausted();
+            return;
+        }
+        deps.warn(`⚠️  Port ${port} already in use (EADDRINUSE) — reclaiming the stale owner and retrying ` +
+            `(attempt ${attempts}/${policy.maxAttempts})…`);
+        void (async () => {
+            const result = await deps.reclaim(port);
+            if (!result.reclaimed)
+                deps.warn(reclaimMessage(port, result, 'a stale/orphaned listener'));
+            deps.scheduleRetry(deps.relisten, decision.delayMs);
+        })();
+    };
+}
+/** Parse a pidfile body into a {@link DevServerPidRecord}; `null` if absent/corrupt/incomplete. */
+export function parsePidRecord(text) {
+    try {
+        const o = JSON.parse(text);
+        if (o && Number.isInteger(o.pid) && Number.isInteger(o.ppid) && Number.isInteger(o.port)) {
+            return { pid: o.pid, ppid: o.ppid, port: o.port };
+        }
+    }
+    catch {
+        // Corrupt / empty pidfile — treat as absent.
+    }
+    return null;
+}
+/** True iff a signal can be delivered to `pid` (exists). `EPERM` (exists, not ours) counts as alive. */
+export function isPidAlive(pid, kill = (p, s) => process.kill(p, s)) {
+    if (!Number.isInteger(pid) || pid <= 1)
+        return false;
+    try {
+        kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+/**
+ * Decide whether a *new* dev-server invocation should start, or bow out because
+ * another supervisor already owns `port`. This is the singleton guard that stops
+ * the "two fighting supervisors" restart loop — a second `npm run dev` racing the
+ * first on `:3000`/`:3100` — WITHOUT breaking `tsx watch`'s own restart of the
+ * *same* supervisor on a file change.
+ *
+ * - **No / corrupt pidfile** → proceed (first start; startup reclaim covers any orphan socket).
+ * - **Same pid** → proceed (defensive; the record is our own).
+ * - **Same parent (`ppid`)** → proceed. `tsx watch` is the stable parent across
+ *   reloads, so a matching parent means the watcher is relaunching OUR OWN script
+ *   — not a competitor. A second `npm run dev` runs under a *different* watcher,
+ *   so it never matches here. This carve-out is what preserves hot reload.
+ * - **Different, still-live owner actually holding the port** → exit cleanly with
+ *   a clear message (do not spawn a competing supervisor).
+ * - **Otherwise** (recorded owner is dead → stale pidfile, or the port is free)
+ *   → proceed; startup reclaim frees any orphaned socket.
+ */
+export function evaluateSingleton(existing, self, portInUse, isAlive) {
+    if (!existing)
+        return { action: 'proceed' };
+    if (existing.pid === self.pid)
+        return { action: 'proceed' };
+    if (existing.ppid === self.ppid)
+        return { action: 'proceed' }; // tsx-watch relaunch of our own supervisor
+    const ownerAlive = isAlive(existing.pid) || (existing.ppid > 1 && isAlive(existing.ppid));
+    if (ownerAlive && portInUse) {
+        return { action: 'exit', reason: `dev server already running on :${existing.port} (pid ${existing.pid})` };
+    }
+    return { action: 'proceed' };
+}
 export async function startDevServer(options) {
     const { port = 3000, backendPath, frontendCommand, frontendPort = 3100, } = options;
     const devStartTime = Date.now();
+    // ── Singleton guard ─────────────────────────────────────────────────────
+    // Prevent two fighting supervisors: a second `npm run dev` must not spawn a
+    // competing supervisor that races the first on :3000/:3100 (backend + Vite
+    // EADDRINUSE → mutual Vite kills → restart loop). We record {pid, ppid, port}
+    // in a per-port pidfile and consult it here. The `ppid` (stable `tsx watch`
+    // watcher) lets us tell a hot-reload relaunch of OUR OWN script apart from a
+    // genuine second invocation — see {@link evaluateSingleton}. A stale pidfile
+    // (dead owner) never blocks startup.
+    const pidfilePath = join(BLOCKS_SANDBOX_DIR, `dev-server.${port}.pid`);
+    const removeOwnPidfile = () => {
+        // Close the read-check-then-delete TOCTOU: a naive `read → if mine → unlink`
+        // could delete a tsx-watch SUCCESSOR's pidfile if it wrote between our read
+        // and our unlink. Instead we atomically `rename` the current pidfile to a
+        // pid-private path (rename(2) is atomic — a concurrent writer can't observe a
+        // half-state), THEN inspect the snapshot:
+        //   • it's ours        → unlink the private copy (done; a successor that
+        //                         writes a fresh pidfile afterwards is untouched
+        //                         because we never unlink the canonical path).
+        //   • it's a successor → we grabbed its file (it wrote before our rename);
+        //                         put it back so the live successor keeps its guard.
+        // We only ever unlink the private claim, never the canonical path, so a
+        // successor's fresh pidfile is never destroyed.
+        const claimPath = `${pidfilePath}.${process.pid}.gc`;
+        try {
+            renameSync(pidfilePath, claimPath);
+        }
+        catch {
+            return; // No pidfile to remove (already gone / never written).
+        }
+        let rec = null;
+        try {
+            rec = parsePidRecord(readFileSync(claimPath, 'utf-8'));
+        }
+        catch { /* unreadable snapshot */ }
+        if (rec && rec.pid !== process.pid) {
+            // Snapshot belongs to a successor — restore it and leave its guard intact.
+            // Residual (astronomically narrow) window: between this rename-away and
+            // rename-back the canonical path briefly has no pidfile, so a THIRD
+            // concurrent start could momentarily see "no guard" and proceed — the same
+            // benign "weakened guard, never broken startup" degradation the write path
+            // already tolerates. tsx-watch drains the old supervisor before relaunching,
+            // so overlap here does not occur in practice.
+            try {
+                renameSync(claimPath, pidfilePath);
+                return;
+            }
+            catch { /* fall through to cleanup */ }
+        }
+        try {
+            unlinkSync(claimPath);
+        }
+        catch { /* already gone */ }
+    };
+    {
+        mkdirSync(BLOCKS_SANDBOX_DIR, { recursive: true });
+        let existing = null;
+        try {
+            existing = parsePidRecord(readFileSync(pidfilePath, 'utf-8'));
+        }
+        catch { /* absent */ }
+        const portInUse = await isPortOpen(port);
+        const decision = evaluateSingleton(existing, { pid: process.pid, ppid: process.ppid }, portInUse, isPidAlive);
+        if (decision.action === 'exit') {
+            console.error(`\n⚠️  ${decision.reason}.\n` +
+                `   Not starting a second dev server. Stop the other process (or run the ` +
+                `cleanup script) and retry \`npm run dev\`.\n`);
+            process.exit(0);
+        }
+        try {
+            writeFileSync(pidfilePath, JSON.stringify({ pid: process.pid, ppid: process.ppid, port }));
+        }
+        catch { /* best-effort — a missing pidfile only weakens the guard, never breaks startup */ }
+    }
     // Load .env.local if present (connection strings, project refs, etc.)
     try {
         process.loadEnvFile('.env.local');
@@ -198,8 +468,8 @@ export async function startDevServer(options) {
     // This makes sandbox single-origin, matching `npm run dev` and the prod
     // CloudFront proxy; `crossDomain` stays unnecessary.
     const blocksConfig = buildBlocksConfig(port, isSandbox);
-    mkdirSync('.blocks-sandbox', { recursive: true });
-    writeFileSync('.blocks-sandbox/config.json', JSON.stringify(blocksConfig, null, 2));
+    mkdirSync(BLOCKS_SANDBOX_DIR, { recursive: true });
+    writeFileSync(join(BLOCKS_SANDBOX_DIR, 'config.json'), JSON.stringify(blocksConfig, null, 2));
     // 1. Set up global collectors for plugin discovery
     globalThis.__BLOCKS_CLIENT_MIDDLEWARE__ = [];
     globalThis.__BLOCKS_DEV_ATTACHMENTS__ = [];
@@ -505,8 +775,30 @@ export async function startDevServer(options) {
         console.log('📝 Generating client code...');
         await writeClientCode(resolvedPath, clientPath);
     }
+    // ── Startup reclaim ──────────────────────────────────────────────────────
+    // Free any port left bound by a crashed / SIGKILL'd predecessor before we bind
+    // the front door or spawn the `--strictPort` frontend. tsx-watch only gives the
+    // previous process ~5s to run cleanup(); if it was SIGKILL'd or crashed, its
+    // detached Vite grandchild (or an orphaned backend) can still hold :3100/:3000
+    // and a fresh `--strictPort` start would collide and crash. The singleton guard
+    // above already ruled out a live *peer* supervisor, so anything still holding
+    // these ports is an orphan — reclaim it (see {@link reclaimPort}).
+    // A successful reclaim (♻️) is an informational confirmation → stdout; a
+    // failed reclaim (⚠️) is a warning the operator must act on → stderr. Keeping
+    // healthy-startup output off stderr avoids false alarms in CI pipelines that
+    // treat any stderr line as a failure.
+    const r3000 = await reclaimPort(port);
+    if (r3000.wasOpen) {
+        (r3000.reclaimed ? console.log : console.error)(reclaimMessage(port, r3000, 'a stale/orphaned listener'));
+    }
+    if (frontendCommand) {
+        const rFrontend = await reclaimPort(frontendPort);
+        if (rFrontend.wasOpen) {
+            (rFrontend.reclaimed ? console.log : console.error)(reclaimMessage(frontendPort, rFrontend, 'a stale/orphaned dev server'));
+        }
+    }
     // ── Start listening ────────────────────────────────────────────────────
-    server.listen(port, async () => {
+    const onListening = 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
@@ -517,11 +809,44 @@ export async function startDevServer(options) {
         else {
             console.log(`\n  ➜  http://localhost:${port}/\n`);
         }
+    };
+    // Front-door EADDRINUSE robustness — mirror the treatment :3100 already gets:
+    // emit a REAL console error (not just telemetry), reclaim the stale owner and
+    // retry the bind (bounded), and on unrecoverable failure exit non-zero with a
+    // clear message so a contended :3000 never silently fails to serve. Startup
+    // reclaim above makes this a rare race (someone grabbed :3000 between reclaim
+    // and listen); the retry closes that window. The retry wiring lives in the
+    // testable {@link createBindRetryController}; telemetry stays here.
+    const onEaddrinuse = createBindRetryController(port, {
+        reclaim: (p) => reclaimPort(p),
+        relisten: () => server.listen(port, onListening),
+        scheduleRetry: (fn, delayMs) => { setTimeout(fn, delayMs).unref?.(); },
+        onExhausted: () => process.exit(1),
+        warn: (msg) => console.error(msg),
     });
     server.on('error', (err) => {
-        const errorCode = err.code === 'EADDRINUSE' ? 'PORT_IN_USE' : 'UNKNOWN';
-        buildAndSendEvent({ command: 'dev', state: 'FAIL', duration: Date.now() - devStartTime, error: { code: errorCode, phase: 'startup' } });
+        if (err.code === 'EADDRINUSE') {
+            // Keep the telemetry signal (unchanged) …
+            buildAndSendEvent({
+                command: 'dev',
+                state: 'FAIL',
+                duration: Date.now() - devStartTime,
+                error: { code: 'PORT_IN_USE', phase: 'startup' },
+            });
+            onEaddrinuse();
+            return;
+        }
+        // Non-EADDRINUSE startup error: telemetry + a real error, then exit non-zero.
+        buildAndSendEvent({
+            command: 'dev',
+            state: 'FAIL',
+            duration: Date.now() - devStartTime,
+            error: { code: 'UNKNOWN', phase: 'startup' },
+        });
+        console.error(`\n❌ Dev server failed to start: ${err.message}\n`);
+        process.exit(1);
     });
+    server.listen(port, onListening);
     // ── Cleanup ────────────────────────────────────────────────────────────
     const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
     let cleaningUp = false;
@@ -549,6 +874,10 @@ export async function startDevServer(options) {
             }
             catch { }
         }
+        // Release the singleton pidfile so the next `npm run dev` isn't blocked by
+        // our own stale record (only removed if it still points at us — a hot-reload
+        // successor may already own it).
+        removeOwnPidfile();
         frontendProxy?.close();
         apiProxy?.close();
         server.close(() => process.exit(0));
@@ -567,6 +896,9 @@ export async function startDevServer(options) {
     // (a surviving grandchild keeps the group alive) — see POST-EXIT GROUP-KILL
     // POLICY above.
     process.once('exit', () => {
+        // Release our singleton pidfile on any exit path (crash, uncaught exception)
+        // that bypassed cleanup(), so it never lingers and blocks the next start.
+        removeOwnPidfile();
         const child = frontendProcess;
         if (!child)
             return;

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,5 +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';
+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;AAClE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,eAAe,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,4 +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';
+export { getStackId, getSandboxId, getStackName } from './stack-id.js';

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

@@ -26,8 +26,9 @@ interface TreeKillResult {
  * 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.
+ * strictly correct — we never silently swallow a failed tree-kill.) Runs with a
+ * 3s `timeout` so a wedged `taskkill` can't stall teardown; a timed-out run
+ * surfaces as `{error}` and degrades to the fallback. Never throws.
  */
 export declare function windowsTreeKill(pid: number, runner?: (command: string, args: readonly string[]) => TreeKillResult): boolean;
 /**
@@ -52,6 +53,44 @@ export declare function windowsTreeKill(pid: number, runner?: (command: string,
  * 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;
+/** Subset of a `spawnSync` result that {@link findListenerPids} inspects. */
+interface CommandOutput {
+    stdout?: string | null;
+    status?: number | null;
+    error?: Error;
+}
+/**
+ * Find the PIDs of processes holding a TCP *listener* on `port`, so a fresh dev
+ * server can reclaim a port left bound by a crashed / SIGKILL'd predecessor (its
+ * orphaned backend, or a detached Vite grandchild) instead of colliding on it.
+ * This mirrors the `lsof -ti:<port>` discovery the `cleanup` script already uses
+ * — it does NOT introduce a new port-to-PID mechanism.
+ *
+ * - **POSIX**: `lsof -ti tcp:<port> -sTCP:LISTEN` — `-t` prints bare PIDs and the
+ *   `-sTCP:LISTEN` state filter restricts the match to the *listener*, so a
+ *   transient client socket on the same port is never targeted.
+ * - **Windows**: `netstat -ano -p tcp`, keeping the trailing PID column of
+ *   `LISTENING` rows whose local address ends in `:<port>`.
+ *
+ * Best-effort and never throws: a missing tool, a non-zero exit ("nothing is
+ * listening"), or unparseable output all yield `[]`. The `spawnSync` runs with a
+ * 3s `timeout` so a hung `lsof`/`netstat` (e.g. an unresponsive NFS mount) can't
+ * block the event loop during startup — a timed-out probe returns `{error}`,
+ * which the `catch` degrades to `[]`. PIDs `<= 1` are dropped
+ * defensively (never target init / the whole current group). `runner`/`platform`
+ * are injected for tests.
+ */
+export declare function findListenerPids(port: number, runner?: (command: string, args: readonly string[]) => CommandOutput, platform?: NodeJS.Platform): number[];
+/**
+ * Force-terminate whatever process (and, on POSIX, its process group) currently
+ * holds a port — used by the dev server's startup / EADDRINUSE *reclaim* path on
+ * a PID discovered via {@link findListenerPids}, i.e. a process this dev server
+ * did NOT spawn. Reuses {@link killFrontendTree} (POSIX `-pid` group kill /
+ * Windows `taskkill /T`, with a direct-`kill` fallback) so reclaim reaps exactly
+ * like our own frontend teardown — no bespoke kill mechanism. Best-effort; never
+ * throws (a since-exited PID just yields ESRCH, swallowed by killFrontendTree).
+ */
+export declare function killListenerTree(pid: number, 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;