@aws-blocks/core 0.1.3 → 0.1.7

package/src/scripts/process-tree.ts

@@ -0,0 +1,245 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { spawnSync } from 'node:child_process';
+
+// Shared process-tree teardown primitives used by every dev-tooling entrypoint
+// (the dev server and the sandbox). Both spawn a long-running command with
+// `shell: true`, so the real process (Vite, or the `tsx watch` dev server) is a
+// grandchild of the shell. Reaping it requires killing the whole tree, not just
+// the shell parent — see the per-function docs. Keeping this in one module means
+// the dev server, the sandbox, and the `process.on('exit')` safety net all reap
+// identically instead of hand-rolling divergent copies.
+
+/** 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 function windowsTreeKill(
+  pid: number,
+  runner: (command: string, args: readonly string[]) => TreeKillResult = (command, args) =>
+    spawnSync(command, args as string[], { stdio: 'ignore', windowsHide: true }),
+): boolean {
+  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: KillableProcess,
+  signal: NodeJS.Signals = 'SIGTERM',
+  platform: NodeJS.Platform = process.platform,
+  killFn: (pid: number, signal: NodeJS.Signals) => void = (p, s) => process.kill(p, s),
+  winTreeKill: (pid: number) => boolean = windowsTreeKill,
+): void {
+  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.
+  }
+}
+
+/** 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;
+}
+
+const defaultSleep = (ms: number): Promise<void> =>
+  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: number,
+  platform: NodeJS.Platform = process.platform,
+  kill: (pid: number, signal: number) => void = (p, s) => process.kill(p, s),
+): boolean {
+  if (platform === 'win32') return true;
+  try {
+    kill(-pid, 0);
+    return true;
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).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: AwaitableChild,
+  graceMs = 2000,
+  killTree: (c: KillableProcess, signal: NodeJS.Signals) => void = killFrontendTree,
+  sleep: (ms: number) => Promise<void> = defaultSleep,
+  isGroupAlive: (pid: number) => boolean = isProcessGroupAlive,
+): Promise<boolean> {
+  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<void>((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/src/scripts/sandbox.ts

@@ -11,6 +11,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.
@@ -147,6 +148,12 @@ export async function startSandbox(options: SandboxOptions) {
     `--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') },
   });
 
@@ -166,6 +173,12 @@ export async function startSandbox(options: SandboxOptions) {
   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: '',
@@ -173,12 +186,36 @@ export async function startSandbox(options: SandboxOptions) {
     },
   });
 
-  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);
   };
 

package/src/scripts/stack-id.test.ts

@@ -0,0 +1,63 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, it, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { mkdirSync, writeFileSync, rmSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { getStackId, getSandboxId } from './stack-id.js';
+
+describe('getStackId', () => {
+  let tmpDir: string;
+
+  afterEach(() => {
+    if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('reads stackId from .blocks/config.json', () => {
+    tmpDir = join(tmpdir(), `stack-id-test-${Date.now()}`);
+    mkdirSync(join(tmpDir, '.blocks'), { recursive: true });
+    writeFileSync(join(tmpDir, '.blocks', 'config.json'), JSON.stringify({ stackId: 'test-abc123' }));
+    assert.strictEqual(getStackId(tmpDir), 'test-abc123');
+  });
+
+  it('throws actionable error when config is missing', () => {
+    tmpDir = join(tmpdir(), `stack-id-test-missing-${Date.now()}`);
+    mkdirSync(tmpDir, { recursive: true });
+    assert.throws(() => getStackId(tmpDir), /\.blocks\/config\.json not found/);
+  });
+
+  it('throws actionable error when stackId key is missing', () => {
+    tmpDir = join(tmpdir(), `stack-id-test-nokey-${Date.now()}`);
+    mkdirSync(join(tmpDir, '.blocks'), { recursive: true });
+    writeFileSync(join(tmpDir, '.blocks', 'config.json'), JSON.stringify({ other: 'value' }));
+    assert.throws(() => getStackId(tmpDir), /\.blocks\/config\.json not found/);
+  });
+});
+
+describe('getSandboxId', () => {
+  let tmpDir: string;
+
+  afterEach(() => {
+    if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('generates and persists a sandbox id', () => {
+    tmpDir = join(tmpdir(), `sandbox-id-test-${Date.now()}`);
+    mkdirSync(tmpDir, { recursive: true });
+    const id = getSandboxId(tmpDir);
+    assert.match(id, /^[a-z0-9]+-[a-f0-9]{6}$/);
+    // Verify persisted
+    const stored = readFileSync(join(tmpDir, '.blocks-sandbox', 'sandbox-id.txt'), 'utf-8').trim();
+    assert.strictEqual(stored, id);
+  });
+
+  it('returns existing id on subsequent calls', () => {
+    tmpDir = join(tmpdir(), `sandbox-id-test-idem-${Date.now()}`);
+    mkdirSync(join(tmpDir, '.blocks-sandbox'), { recursive: true });
+    writeFileSync(join(tmpDir, '.blocks-sandbox', 'sandbox-id.txt'), 'alice-abc123');
+    assert.strictEqual(getSandboxId(tmpDir), 'alice-abc123');
+  });
+});

package/src/scripts/stack-id.ts

@@ -0,0 +1,61 @@
+// 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';
+
+interface BlocksConfig {
+  stackId?: string;
+  [key: string]: unknown;
+}
+
+function randomSuffix(length: number): string {
+  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?: string): string {
+  const root = projectRoot || process.cwd();
+  const configPath = join(root, '.blocks', 'config.json');
+  try {
+    const config: BlocksConfig = 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.
+ */
+export function getSandboxId(projectRoot?: string): string {
+  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;
+}
+
+function getUsername(): string {
+  try {
+    return execSync('git config user.name', { encoding: 'utf-8' }).trim();
+  } catch {
+    return process.env.USER || process.env.USERNAME || 'user';
+  }
+}

package/src/version.ts

@@ -1,2 +1,2 @@
 // Auto-generated by scripts/generate-version.mjs — do not edit manually
-export const CORE_VERSION = '0.1.3';
+export const CORE_VERSION = '0.1.7';