@aws-blocks/core 0.1.4 → 0.1.10

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

@@ -0,0 +1,104 @@
+// 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, getStackName } 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');
+    });
+});
+describe('getStackName', () => {
+    let tmpDir;
+    afterEach(() => {
+        if (tmpDir)
+            rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('production is <stackId>-prod', () => {
+        tmpDir = join(tmpdir(), `stack-name-prod-${Date.now()}`);
+        mkdirSync(join(tmpDir, '.blocks'), { recursive: true });
+        writeFileSync(join(tmpDir, '.blocks', 'config.json'), JSON.stringify({ stackId: 'my-app-k7x2mf' }));
+        assert.strictEqual(getStackName({ sandbox: false, projectRoot: tmpDir }), 'my-app-k7x2mf-prod');
+    });
+    it('sandbox is <stackId>-<sandboxId>', () => {
+        tmpDir = join(tmpdir(), `stack-name-sbx-${Date.now()}`);
+        mkdirSync(join(tmpDir, '.blocks'), { recursive: true });
+        writeFileSync(join(tmpDir, '.blocks', 'config.json'), JSON.stringify({ stackId: 'my-app-k7x2mf' }));
+        mkdirSync(join(tmpDir, '.blocks-sandbox'), { recursive: true });
+        writeFileSync(join(tmpDir, '.blocks-sandbox', 'sandbox-id.txt'), 'alice-0d7e1c');
+        assert.strictEqual(getStackName({ sandbox: true, projectRoot: tmpDir }), 'my-app-k7x2mf-alice-0d7e1c');
+    });
+    it('throws actionable error when config is missing (fail fast, no silent fallback)', () => {
+        tmpDir = join(tmpdir(), `stack-name-missing-${Date.now()}`);
+        mkdirSync(tmpDir, { recursive: true });
+        assert.throws(() => getStackName({ sandbox: false, projectRoot: tmpDir }), /\.blocks\/config\.json not found/);
+    });
+});
+describe('getStackName sandbox id (get-or-create)', () => {
+    let tmpDir;
+    afterEach(() => {
+        if (tmpDir)
+            rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('creates and persists sandbox-id.txt on first call when missing', () => {
+        tmpDir = join(tmpdir(), `stack-name-getorcreate-${Date.now()}`);
+        mkdirSync(join(tmpDir, '.blocks'), { recursive: true });
+        writeFileSync(join(tmpDir, '.blocks', 'config.json'), JSON.stringify({ stackId: 'test-app' }));
+        // No .blocks-sandbox dir yet — getStackName creates the id rather than throwing.
+        const name = getStackName({ sandbox: true, projectRoot: tmpDir });
+        assert.match(name, /^test-app-[a-z0-9]+-[a-f0-9]{6}$/);
+        // Persisted so later callers/processes resolve the identical name.
+        const stored = readFileSync(join(tmpDir, '.blocks-sandbox', 'sandbox-id.txt'), 'utf-8').trim();
+        assert.strictEqual(name, `test-app-${stored}`);
+    });
+    it('reuses the same id across calls', () => {
+        tmpDir = join(tmpdir(), `stack-name-getorcreate-idem-${Date.now()}`);
+        mkdirSync(join(tmpDir, '.blocks'), { recursive: true });
+        writeFileSync(join(tmpDir, '.blocks', 'config.json'), JSON.stringify({ stackId: 'test-app' }));
+        assert.strictEqual(getStackName({ sandbox: true, projectRoot: tmpDir }), getStackName({ sandbox: true, projectRoot: tmpDir }));
+    });
+});

package/dist/telemetry/client.d.ts

@@ -52,7 +52,9 @@ export declare function buildAndSendEvent(opts: BuildAndSendEventOptions): void;
 /**
  * Send a pre-built telemetry event to the collection endpoint.
  *
- * Fire-and-forget: no retry, 500ms timeout, all errors silently swallowed.
+ * Spawns a detached subprocess that performs the HTTPS POST independently of
+ * the parent CLI process. This ensures the request completes even when the
+ * parent exits on failure paths before an in-process request would flush.
  * Debug output available via `NODE_DEBUG=blocks-telemetry`.
  */
 export declare function sendEvent(event: BlocksTelemetryEvent): void;

package/dist/telemetry/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/telemetry/client.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAajF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,GAAG,SAAS,CAWzD;AAwBD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,wBAAwB,GAAG,oBAAoB,CAwD/E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,IAAI,CAatE;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,oBAAoB,GAAG,IAAI,CAyC3D"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/telemetry/client.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAYjF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,GAAG,SAAS,CAWzD;AAwBD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,wBAAwB,GAAG,oBAAoB,CAwD/E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,IAAI,CAatE;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,oBAAoB,GAAG,IAAI,CAgC3D"}

package/dist/telemetry/client.js

@@ -1,7 +1,7 @@
-import { request as httpsRequest } from 'node:https';
-import { request as httpRequest } from 'node:http';
 import { existsSync, readFileSync, mkdirSync, openSync, writeSync, closeSync, writeFileSync, constants } from 'node:fs';
+import { spawn } from 'node:child_process';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { debuglog } from 'node:util';
 import { CORE_VERSION } from '../version.js';
 import { Scope } from '../common/index.js';
@@ -11,7 +11,6 @@ import { getInstallationId, getProjectId, generateEventId } from './identifiers.
 // Debug log: writes to stderr via NODE_DEBUG=blocks-telemetry (developer-facing, for troubleshooting)
 const debug = debuglog('blocks-telemetry');
 const DEFAULT_ENDPOINT = 'https://blocks-telemetry.us-east-1.api.aws/metrics';
-const TIMEOUT_MS = 500;
 const TELEMETRY_VERSION = '1.0.0';
 function getEndpoint() {
     return process.env.BLOCKS_TELEMETRY_ENDPOINT || DEFAULT_ENDPOINT;
@@ -172,7 +171,9 @@ export function buildAndSendEvent(opts) {
 /**
  * Send a pre-built telemetry event to the collection endpoint.
  *
- * Fire-and-forget: no retry, 500ms timeout, all errors silently swallowed.
+ * Spawns a detached subprocess that performs the HTTPS POST independently of
+ * the parent CLI process. This ensures the request completes even when the
+ * parent exits on failure paths before an in-process request would flush.
  * Debug output available via `NODE_DEBUG=blocks-telemetry`.
  */
 export function sendEvent(event) {
@@ -187,27 +188,22 @@ export function sendEvent(event) {
             catch { }
         }
         debug('sending event to %s (%d bytes)', endpoint, Buffer.byteLength(payload));
-        const url = new URL(endpoint);
-        const isHttps = url.protocol === 'https:';
-        const requestFn = isHttps ? httpsRequest : httpRequest;
-        const req = requestFn({
-            hostname: url.hostname,
-            port: url.port || (isHttps ? '443' : '80'),
-            path: url.pathname + url.search,
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'Content-Length': Buffer.byteLength(payload),
-            },
-            timeout: TIMEOUT_MS,
-        }, (res) => {
-            debug('event sent (status=%d)', res.statusCode);
-            res.resume();
+        const dir = path.dirname(fileURLToPath(import.meta.url));
+        const workerPath = path.join(dir, 'telemetry-send-worker.js');
+        const child = spawn(process.execPath, [workerPath, endpoint], {
+            detached: true,
+            stdio: ['pipe', 'ignore', 'ignore'],
+            // Clear NODE_OPTIONS so inherited flags (e.g. --conditions=cdk) don't interfere
+            env: { ...process.env, NODE_OPTIONS: '' },
         });
-        req.on('error', (err) => { debug('send failed: %s', err.message); });
-        req.on('timeout', () => { debug('send timed out'); req.destroy(); });
-        req.write(payload);
-        req.end();
+        child.stdin.on('error', (err) => { debug('stdin write failed: %s', err.message); });
+        // Payload is small (<1KB JSON) so it fits in the kernel pipe buffer (~64KB)
+        // and survives the parent closing its fd on exit.
+        child.stdin.write(payload);
+        child.stdin.end();
+        child.on('error', (err) => { debug('spawn failed: %s', err.message); });
+        child.unref();
+        debug('spawned telemetry subprocess (pid=%d)', child.pid);
     }
     catch {
         // Telemetry must never throw or affect the user's command

package/dist/telemetry/telemetry-send-worker.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=telemetry-send-worker.d.ts.map

package/dist/telemetry/telemetry-send-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-send-worker.d.ts","sourceRoot":"","sources":["../../src/telemetry/telemetry-send-worker.ts"],"names":[],"mappings":""}

package/dist/telemetry/telemetry-send-worker.js

@@ -0,0 +1,58 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Telemetry send worker — spawned as a detached subprocess.
+ * Reads JSON payload from stdin, POSTs it to the endpoint (argv[2]).
+ *
+ * Uses only Node built-ins — no project imports — so the compiled .js
+ * runs with bare `node` (no tsx needed).
+ */
+import { request as httpsRequest } from 'node:https';
+import { request as httpRequest } from 'node:http';
+const TIMEOUT_MS = 500;
+const debug = (process.env.NODE_DEBUG || '').includes('blocks-telemetry');
+const endpoint = process.argv[2];
+if (!endpoint)
+    process.exit(1);
+let payload = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', (chunk) => { payload += chunk; });
+process.stdin.on('end', () => {
+    try {
+        const url = new URL(endpoint);
+        const isHttps = url.protocol === 'https:';
+        const requestFn = isHttps ? httpsRequest : httpRequest;
+        const req = requestFn({
+            hostname: url.hostname,
+            port: url.port || (isHttps ? '443' : '80'),
+            path: url.pathname + url.search,
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Content-Length': Buffer.byteLength(payload),
+            },
+            timeout: TIMEOUT_MS,
+        }, (res) => {
+            res.resume();
+            if (debug)
+                process.stderr.write(`BLOCKS-TELEMETRY: sent (status=${res.statusCode})\n`);
+            process.exit(0);
+        });
+        req.on('error', (e) => {
+            if (debug)
+                process.stderr.write(`BLOCKS-TELEMETRY: error: ${e.message}\n`);
+            process.exit(1);
+        });
+        req.on('timeout', () => {
+            if (debug)
+                process.stderr.write(`BLOCKS-TELEMETRY: timed out\n`);
+            req.destroy();
+            process.exit(1);
+        });
+        req.write(payload);
+        req.end();
+    }
+    catch {
+        process.exit(1);
+    }
+});

package/dist/telemetry/telemetry.test.js

@@ -10,7 +10,7 @@ import { isCI, detectOS, detectNodeVersion, detectPackageManager, detectAgent, c
 import { trackCommand, classifyError } from './trackCommand.js';
 import { buildAndSendEvent, buildEvent, sendEvent, getTelemetryFilePath } from './client.js';
 import { getInstallationId, getProjectId, generateEventId } from './identifiers.js';
-import { spawnSync } from 'node:child_process';
+import { spawnSync, spawn as spawnChild } from 'node:child_process';
 import { Scope } from '../common/index.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 describe('telemetry/consent', () => {
@@ -453,6 +453,82 @@ describe('telemetry/client', () => {
         process.env = { ...originalEnv };
     });
 });
+describe('telemetry/send-worker', () => {
+    it('worker POSTs payload from stdin to endpoint', async () => {
+        const received = [];
+        const server = await new Promise((resolve) => {
+            const s = createServer((req, res) => {
+                let body = '';
+                req.on('data', (chunk) => { body += chunk; });
+                req.on('end', () => {
+                    received.push(body);
+                    res.writeHead(200);
+                    res.end();
+                });
+            });
+            s.listen(0, '127.0.0.1', () => resolve(s));
+        });
+        const addr = server.address();
+        const endpoint = `http://127.0.0.1:${addr.port}/collect`;
+        const payload = JSON.stringify({ test: true, command: 'dev' });
+        const workerPath = join(__dirname, 'telemetry-send-worker.js');
+        const exitCode = await new Promise((resolve) => {
+            const proc = spawnChild(process.execPath, [workerPath, endpoint], {
+                stdio: ['pipe', 'ignore', 'ignore'],
+                env: { ...process.env, NODE_OPTIONS: '' },
+            });
+            proc.stdin.write(payload);
+            proc.stdin.end();
+            proc.on('close', (code) => resolve(code));
+        });
+        assert.strictEqual(exitCode, 0);
+        assert.strictEqual(received.length, 1);
+        assert.deepStrictEqual(JSON.parse(received[0]), { test: true, command: 'dev' });
+        server.close();
+    });
+    it('worker exits with 1 on unreachable endpoint', async () => {
+        const payload = JSON.stringify({ test: true });
+        const workerPath = join(__dirname, 'telemetry-send-worker.js');
+        const exitCode = await new Promise((resolve) => {
+            const proc = spawnChild(process.execPath, [workerPath, 'http://127.0.0.1:1/unreachable'], {
+                stdio: ['pipe', 'ignore', 'ignore'],
+                env: { ...process.env, NODE_OPTIONS: '' },
+            });
+            proc.stdin.write(payload);
+            proc.stdin.end();
+            proc.on('close', (code) => resolve(code));
+        });
+        assert.strictEqual(exitCode, 1);
+    });
+    it('worker writes debug output to stderr when NODE_DEBUG is set', async () => {
+        const server = await new Promise((resolve) => {
+            const s = createServer((req, res) => {
+                let body = '';
+                req.on('data', (chunk) => { body += chunk; });
+                req.on('end', () => { res.writeHead(200); res.end(); });
+            });
+            s.listen(0, '127.0.0.1', () => resolve(s));
+        });
+        const addr = server.address();
+        const endpoint = `http://127.0.0.1:${addr.port}/collect`;
+        const payload = JSON.stringify({ test: true });
+        const workerPath = join(__dirname, 'telemetry-send-worker.js');
+        const result = await new Promise((resolve) => {
+            const proc = spawnChild(process.execPath, [workerPath, endpoint], {
+                stdio: ['pipe', 'ignore', 'pipe'],
+                env: { ...process.env, NODE_OPTIONS: '', NODE_DEBUG: 'blocks-telemetry' },
+            });
+            let stderr = '';
+            proc.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+            proc.stdin.write(payload);
+            proc.stdin.end();
+            proc.on('close', (code) => resolve({ code, stderr }));
+        });
+        assert.strictEqual(result.code, 0);
+        assert.ok(result.stderr.includes('BLOCKS-TELEMETRY: sent (status=200)'), `Expected debug output, got: ${result.stderr}`);
+        server.close();
+    });
+});
 describe('telemetry/trackCommand integration', () => {
     const originalEnv = { ...process.env };
     afterEach(() => {

package/dist/telemetry/trackCommand.d.ts

@@ -12,7 +12,7 @@ export declare function classifyError(error: unknown): {
  *
  * Measures wall-clock duration, classifies errors, and sends a single telemetry event
  * after the command completes (success or failure). The telemetry send is fire-and-forget
- * and bounded by a 5s timeout — it will never delay the command or affect its exit code.
+ * and bounded by a 500ms timeout — it will never delay the command or affect its exit code.
  *
  * If telemetry is disabled (via env var or config), the function is executed directly
  * with zero overhead.

package/dist/telemetry/trackCommand.js

@@ -20,10 +20,10 @@ export function classifyError(error) {
     if (msg.includes('cdk synth') || msg.includes('synthesis')) {
         return { code: 'CDK_SYNTH_FAILED', phase: 'synth' };
     }
-    if (msg.includes('cdk deploy') || msg.includes('deployment failed')) {
+    if (msg.includes('cdk deploy') || msg.includes('deployment failed') || (msg.includes('cdk') && msg.includes('deploy') && msg.includes('exited with code'))) {
         return { code: 'CDK_DEPLOY_FAILED', phase: 'deploy' };
     }
-    if (msg.includes('cdk destroy') || msg.includes('destroy failed')) {
+    if (msg.includes('cdk destroy') || msg.includes('destroy failed') || (msg.includes('cdk') && msg.includes('destroy') && msg.includes('exited with code'))) {
         return { code: 'CDK_DESTROY_FAILED', phase: 'destroy' };
     }
     if (msg.includes('npm install') || msg.includes('npm err')) {
@@ -48,7 +48,7 @@ export function classifyError(error) {
  *
  * Measures wall-clock duration, classifies errors, and sends a single telemetry event
  * after the command completes (success or failure). The telemetry send is fire-and-forget
- * and bounded by a 5s timeout — it will never delay the command or affect its exit code.
+ * and bounded by a 500ms timeout — it will never delay the command or affect its exit code.
  *
  * If telemetry is disabled (via env var or config), the function is executed directly
  * with zero overhead.

package/dist/version.d.ts

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

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,YAAY,UAAU,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,YAAY,WAAW,CAAC"}

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.10';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-blocks/core",
-  "version": "0.1.4",
+  "version": "0.1.10",
   "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/db-naming.test.ts

@@ -1,9 +1,13 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { test, describe } from 'node:test';
+import { test, describe, afterEach } from 'node:test';
 import assert from 'node:assert';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
 import { extractDbRef, dbConnectionParameterName } from './db-naming.js';
+import { getStackName } from './scripts/stack-id.js';
 
 describe('extractDbRef', () => {
   test('pooler form (postgres.{ref}@) yields ref', () => {
@@ -39,10 +43,51 @@ describe('extractDbRef', () => {
 });
 
 describe('dbConnectionParameterName', () => {
-  test('composes the stage into the SSM name', () => {
-    assert.strictEqual(
-      dbConnectionParameterName('production'),
-      '/blocks/production/db-connection-string',
+  test('formats stack name into parameter path', () => {
+    assert.strictEqual(dbConnectionParameterName('my-app-k7x2mf-prod'), '/my-app-k7x2mf-prod-db-url');
+  });
+
+  test('two distinct stack names produce distinct parameter names', () => {
+    assert.notStrictEqual(
+      dbConnectionParameterName('app-a-111111-prod'),
+      dbConnectionParameterName('app-b-222222-prod'),
     );
   });
 });
+
+describe('cross-site invariant: write name == read name', () => {
+  let tmpDir: string;
+  let originalCwd: string;
+
+  afterEach(() => {
+    if (originalCwd) process.chdir(originalCwd);
+    if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function setupProject(stackId: string, sandboxId: string): string {
+    tmpDir = mkdtempSync(join(tmpdir(), 'cross-site-'));
+    mkdirSync(join(tmpDir, '.blocks'), { recursive: true });
+    writeFileSync(join(tmpDir, '.blocks', 'config.json'), JSON.stringify({ stackId }));
+    mkdirSync(join(tmpDir, '.blocks-sandbox'), { recursive: true });
+    writeFileSync(join(tmpDir, '.blocks-sandbox', 'sandbox-id.txt'), sandboxId);
+    return tmpDir;
+  }
+
+  test('write-side name == read-side name (sandbox)', () => {
+    const root = setupProject('my-app-k7x2mf', 'alice-0d7e1c');
+    const writeName = dbConnectionParameterName(getStackName({ sandbox: true, projectRoot: root }));
+    originalCwd = process.cwd();
+    process.chdir(root);
+    const readName = dbConnectionParameterName(getStackName({ sandbox: true }));
+    assert.strictEqual(writeName, readName);
+  });
+
+  test('write-side name == read-side name (production)', () => {
+    const root = setupProject('my-app-k7x2mf', 'alice-0d7e1c');
+    const writeName = dbConnectionParameterName(getStackName({ sandbox: false, projectRoot: root }));
+    originalCwd = process.cwd();
+    process.chdir(root);
+    const readName = dbConnectionParameterName(getStackName({ sandbox: false }));
+    assert.strictEqual(writeName, readName);
+  });
+});

package/src/db-naming.ts

@@ -6,9 +6,15 @@
  * database connection string, and for the project ref derived from a Postgres
  * connection string.
  *
- * Both the deploy-time provisioner (`ensure-secrets`) and the `db pull`
- * generated code derive this name from the stage alone. Keep this the only
- * place the name is constructed.
+ * The connection-string parameter name is **stack-scoped** (embeds the
+ * deployment's stack name), so two Blocks apps in the same account + region +
+ * stage get distinct names and cannot overwrite each other's credentials.
+ *
+ * Two call sites compute the name: the pre-deploy writer (`ensure-secrets`) and
+ * the `db pull` generated wiring at synth. Both pass the result of
+ * `getStackName({ sandbox, projectRoot })` into this function, so they produce
+ * the same name by construction. The runtime Lambda does not call this function;
+ * it reads the name recorded at synth.
  */
 
 /**
@@ -35,7 +41,13 @@ export function extractDbRef(connectionString: string): string {
   throw new Error('Cannot extract database identifier from connection string.');
 }
 
-/** SSM parameter name storing the connection string for a given stage. */
-export function dbConnectionParameterName(stage: string): string {
-  return `/blocks/${stage}/db-connection-string`;
+/**
+ * SSM SecureString parameter name for a deployment's external database
+ * connection string.
+ *
+ * Pure string transform: `/<stackName>-db-url`. The caller is responsible for
+ * computing the stack name via `getStackName({ sandbox, projectRoot })`.
+ */
+export function dbConnectionParameterName(stackName: string): string {
+  return `/${stackName}-db-url`;
 }

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;
+}