@aws-blocks/core 0.1.4 → 0.1.7

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,+BAyLzD;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.
  *
@@ -121,6 +122,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 +144,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,12 @@
+/**
+ * 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.
+ */
+export declare function getSandboxId(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;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAWzD"}

package/dist/scripts/stack-id.js

@@ -0,0 +1,54 @@
+// 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.
+ */
+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;
+}
+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":""}

package/dist/scripts/stack-id.test.js

@@ -0,0 +1,54 @@
+// 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;
+    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;
+    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/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const CORE_VERSION = "0.1.4";
+export declare const CORE_VERSION = "0.1.7";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-blocks/core",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "author": "Amazon Web Services",
   "license": "Apache-2.0",
   "type": "module",

package/src/cdk/index.ts

@@ -22,7 +22,7 @@ export { SandboxDisableDeletionProtection } from './mixins.js';
 export { registerConfig, finalizeConfigRegistry } from './config-registry.js';
 export { synthGuard } from './synth-guard.js';
 export type { ScopeOptions } from '../index.js';
-export { ApiError, isBlocksError } from '../errors.js';
+export { ApiError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
 
 export class BlocksStack extends cdk.Stack implements BaseBlocksStack {
   public readonly id: string;

package/src/client/index.ts

@@ -316,5 +316,5 @@ export function ApiNamespaceClient<T extends Record<string, (...args: any[]) =>
   });
 }
 
-export { ApiError, isBlocksError } from '../errors.js';
+export { ApiError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
 export { Scope, type ScopeOptions } from '../common/index.js';

package/src/errors.test.ts

@@ -0,0 +1,55 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { ApiError, isBlocksError, hasAuthError } from './errors.js';
+
+describe('isBlocksError', () => {
+  it('matches a thrown ApiError by name', () => {
+    const e = new ApiError('nope', 401, { name: 'InvalidCredentialsException' });
+    assert.ok(isBlocksError(e, 'InvalidCredentialsException'));
+  });
+
+  it('does not match a different name', () => {
+    const e = new ApiError('nope', 401, { name: 'InvalidCredentialsException' });
+    assert.ok(!isBlocksError(e, 'SomeOtherException'));
+  });
+
+  it('does not match a plain object (not an Error)', () => {
+    assert.ok(!isBlocksError({ name: 'InvalidCredentialsException' }, 'InvalidCredentialsException'));
+  });
+});
+
+describe('hasAuthError', () => {
+  it('matches a state carrying the given errorName', () => {
+    const state = { state: 'signedOut', errorName: 'InvalidCredentialsException' } as const;
+    assert.ok(hasAuthError(state, 'InvalidCredentialsException'));
+  });
+
+  it('does not match a different errorName', () => {
+    const state = { errorName: 'InvalidCredentialsException' };
+    assert.ok(!hasAuthError(state, 'UserAlreadyExistsException'));
+  });
+
+  it('does not match a state with no errorName', () => {
+    const state: { errorName?: string } = {};
+    assert.ok(!hasAuthError(state, 'InvalidCredentialsException'));
+  });
+
+  it('is safe on null / undefined', () => {
+    assert.ok(!hasAuthError(null, 'InvalidCredentialsException'));
+    assert.ok(!hasAuthError(undefined, 'InvalidCredentialsException'));
+  });
+
+  it('narrows the errorName to the matched literal', () => {
+    const state: { errorName?: string } = { errorName: 'InvalidCredentialsException' };
+    if (hasAuthError(state, 'InvalidCredentialsException')) {
+      // Type-level: state.errorName is narrowed to the literal.
+      const name: 'InvalidCredentialsException' = state.errorName;
+      assert.strictEqual(name, 'InvalidCredentialsException');
+    } else {
+      assert.fail('expected match');
+    }
+  });
+});

package/src/errors.ts

@@ -1,6 +1,13 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+/**
+ * The `name` an `ApiError` falls back to when no structured error name is
+ * given. A name equal to this carries no BB-level meaning, so consumers
+ * branching on the structured identity should treat it as "no name".
+ */
+export const DEFAULT_API_ERROR_NAME = 'ApiError';
+
 /**
  * Error subclass for errors that cross the wire between server and client.
  *
@@ -46,7 +53,7 @@ export class ApiError extends Error {
 
 	constructor(message: string, status: number, options?: { name?: string; cause?: unknown; retriable?: boolean }) {
 		super(message, options?.cause ? { cause: options.cause } : undefined);
-		this.name = options?.name ?? 'ApiError';
+		this.name = options?.name ?? DEFAULT_API_ERROR_NAME;
 		this.status = status;
 		this.retriable = options?.retriable ?? false;
 	}
@@ -70,3 +77,27 @@ export class ApiError extends Error {
 export function isBlocksError<N extends string>(e: unknown, name: N): e is Error & { name: N } {
 	return e instanceof Error && e.name === name;
 }
+
+/**
+ * Type guard for branching on a failed `AuthState` (the recommended
+ * `setAuthState` client path) by its structured `errorName`.
+ *
+ * The returned state is a plain object, not a thrown `Error`, so
+ * `isBlocksError` does not apply — use this on the value returned by
+ * `setAuthState`/`getAuthState`. Match on the BB error constant, never on
+ * the human-facing `error` string.
+ *
+ * @example
+ * ```typescript
+ * const next = await authApi.setAuthState({ action: 'signIn', username, password });
+ * if (hasAuthError(next, AuthBasicErrors.InvalidCredentials)) {
+ *   // unknown user → fall back to sign-up
+ * }
+ * ```
+ */
+export function hasAuthError<T extends { errorName?: string }, N extends string>(
+	state: T | null | undefined,
+	name: N,
+): state is T & { errorName: N } {
+	return state?.errorName === name;
+}

package/src/hosting.ts

@@ -71,8 +71,29 @@ export type ComputeConfig = {
    * ```
    */
   timeout?: cdk.Duration | number;
-  /** Reserved concurrent executions. Default: undefined (no reservation). */
+  /** Reserved concurrent executions for the SSR Lambda. Default: undefined (no reservation). */
   reservedConcurrency?: number;
+  /**
+   * Overrides for the image-optimization Lambda.
+   *
+   * `reservedConcurrency` defaults to undefined (no reservation). It is left
+   * unreserved so deploys succeed on fresh AWS accounts, whose default
+   * account-level unreserved-concurrency limit is 10 — reserving any
+   * concurrency there can drop the account below its required minimum and
+   * cause Lambda to reject the stack with a 400. Set this only if you have
+   * headroom and want to cap image-opt throughput.
+   *
+   * @example
+   * ```ts
+   * compute: {
+   *   imageOptimization: { reservedConcurrency: 5 },
+   * }
+   * ```
+   */
+  imageOptimization?: {
+    /** Reserved concurrent executions. Default: undefined (no reservation). */
+    reservedConcurrency?: number;
+  };
   /** CloudWatch log retention for the SSR Lambda. Default: TWO_WEEKS. */
   logRetention?: cdk.aws_logs.RetentionDays;
 };

package/src/index.cdk.ts

@@ -3,7 +3,7 @@
 
 export { ApiNamespace, type BlocksContext, type ApiHandler } from './api.js';
 export { BLOCKS_RPC_PREFIX, BLOCKS_AUTH_PREFIX } from './constants.js';
-export { ApiError, isBlocksError } from './errors.js';
+export { ApiError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from './errors.js';
 export { EventSourceMapping } from './lambda-handler.js';
 export { BlocksStackProps } from './common/index.js';
 export { registerSdkIdentifiers, getSdkIdentifiers, getAllSdkIdentifiers, _resetSdkRegistry } from './common/sdk-registry.js';

package/src/index.ts

@@ -3,7 +3,7 @@
 
 export { ApiNamespace, type BlocksContext, type ApiHandler } from './api.js';
 export { BLOCKS_RPC_PREFIX, BLOCKS_AUTH_PREFIX } from './constants.js';
-export { ApiError, isBlocksError } from './errors.js';
+export { ApiError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from './errors.js';
 export { Scope, type ScopeOptions, type ScopeParent, type BuildingBlockMeta } from './common/index.js';
 export { registerSdkIdentifiers, getSdkIdentifiers, getAllSdkIdentifiers, _resetSdkRegistry } from './common/sdk-registry.js';
 export { getConfig, getConfigSync, preloadConfig, loadConfigToProcessEnv, _resetConfigCache } from './common/config.js';