@aws-blocks/core 0.1.0

package/dist/scripts/extract-ts-types.test.js

@@ -0,0 +1,497 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Tests for extract-ts-types.ts — verifies that `new ApiNamespace(...)`
+ * calls and indirect calls (e.g., auth.createApi()) produce proper type info.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { extractMethodTypes, extractSkipCodegenMethods } from './extract-ts-types.js';
+import { writeFileSync, mkdirSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+function createTempProject(files) {
+    const dir = join(tmpdir(), `blocks-ts-test-${Date.now()}`);
+    mkdirSync(dir, { recursive: true });
+    for (const [name, content] of Object.entries(files)) {
+        const filePath = join(dir, name);
+        mkdirSync(join(filePath, '..'), { recursive: true });
+        writeFileSync(filePath, content);
+    }
+    return dir;
+}
+/** Minimal mock so `new ApiNamespace(scope, name, handler)` parses as a NewExpression and types correctly. */
+const API_NS_MOCK = `
+	interface ApiNamespaceConstructor { new <T>(scope: any, name: string, handler: (ctx: any) => T): T; }
+	const ApiNamespace: ApiNamespaceConstructor = class {} as any;
+`;
+describe('extractMethodTypes — direct ApiNamespace calls', () => {
+    it('extracts param and return types from inline ApiNamespace', () => {
+        const dir = createTempProject({
+            'tsconfig.json': JSON.stringify({
+                compilerOptions: {
+                    target: 'ESNext',
+                    module: 'ESNext',
+                    moduleResolution: 'bundler',
+                    strict: true,
+                },
+            }),
+            'index.ts': `
+				${API_NS_MOCK}
+
+				interface User { id: string; name: string; }
+
+				export const api = new ApiNamespace(null, 'api', (context) => ({
+					async getUser(id: string): Promise<User | null> {
+						return null;
+					},
+					async createUser(name: string, age: number) {
+						return { success: true };
+					},
+				}));
+			`,
+        });
+        try {
+            const types = extractMethodTypes(join(dir, 'index.ts'));
+            assert.ok(types.has('getUser'), 'should find getUser');
+            assert.ok(types.has('createUser'), 'should find createUser');
+            const getUser = types.get('getUser');
+            assert.strictEqual(getUser.params.length, 1);
+            assert.strictEqual(getUser.params[0].name, 'id');
+            assert.strictEqual(getUser.params[0].schema.type, 'string');
+            const createUser = types.get('createUser');
+            assert.strictEqual(createUser.params.length, 2);
+            assert.strictEqual(createUser.params[0].schema.type, 'string');
+            assert.strictEqual(createUser.params[1].schema.type, 'number');
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});
+describe('extractSkipCodegenMethods — pure-AST scan', () => {
+    it('returns names of methods tagged with @blocksSkipCodegen, ignoring untagged ones', () => {
+        const dir = createTempProject({
+            // No tsconfig deliberately — this entry must work without one,
+            // since `extractMethodTypes` may crash on a half-resolvable
+            // program but the JSDoc scan should still succeed.
+            'index.ts': `
+				class ApiNamespace { constructor(scope: any, name: any, handler: any) {} }
+
+				export const api = new ApiNamespace(null, 'api', (context) => ({
+					async normalMethod() { return { ok: true }; },
+
+					/**
+					 * @blocksSkipCodegen
+					 */
+					async devOnly() { return null; },
+
+					/** Plain JSDoc, not tagged. */
+					async alsoNormal() { return 1; },
+				}));
+			`,
+        });
+        try {
+            const skips = extractSkipCodegenMethods(join(dir, 'index.ts'));
+            assert.strictEqual(skips.size, 1);
+            assert.ok(skips.has('devOnly'));
+            assert.ok(!skips.has('normalMethod'));
+            assert.ok(!skips.has('alsoNormal'));
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('returns an empty set when the file has no ApiNamespace calls', () => {
+        const dir = createTempProject({
+            'index.ts': `export const x = 1;`,
+        });
+        try {
+            const skips = extractSkipCodegenMethods(join(dir, 'index.ts'));
+            assert.strictEqual(skips.size, 0);
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});
+describe('extractMethodTypes — @blocksSkipCodegen JSDoc tag', () => {
+    it('flags methods with @blocksSkipCodegen so the spec emitter can drop them', () => {
+        const dir = createTempProject({
+            'tsconfig.json': JSON.stringify({
+                compilerOptions: {
+                    target: 'ESNext',
+                    module: 'ESNext',
+                    moduleResolution: 'bundler',
+                    strict: true,
+                },
+            }),
+            'index.ts': `
+				${API_NS_MOCK}
+
+				export const api = new ApiNamespace(null, 'api', (context) => ({
+					async normalMethod() {
+						return { ok: true };
+					},
+
+					/**
+					 * Mock-only helper. Should not show up in native codegen.
+					 * @blocksSkipCodegen
+					 */
+					async getLastCode() {
+						return null as { code: string } | null;
+					},
+				}));
+			`,
+        });
+        try {
+            const types = extractMethodTypes(join(dir, 'index.ts'));
+            assert.strictEqual(types.get('normalMethod')?.skipCodegen, undefined);
+            assert.strictEqual(types.get('getLastCode')?.skipCodegen, true);
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});
+describe('extractMethodTypes — indirect ApiNamespace calls (e.g., auth.createApi())', () => {
+    it('extracts types from methods returned by a helper method', () => {
+        const dir = createTempProject({
+            'tsconfig.json': JSON.stringify({
+                compilerOptions: {
+                    target: 'ESNext',
+                    module: 'ESNext',
+                    moduleResolution: 'bundler',
+                    strict: true,
+                },
+            }),
+            'auth.ts': `
+				${API_NS_MOCK}
+
+				interface AuthState {
+					isSignedIn: boolean;
+					username: string | null;
+					error?: string;
+				}
+
+				export class AuthBasic {
+					createApi() {
+						return new ApiNamespace(null, 'auth', (context) => ({
+							async getAuthState(): Promise<AuthState> {
+								return { isSignedIn: false, username: null };
+							},
+							async setAuthState(action: string, fields: Record<string, string>): Promise<AuthState> {
+								return { isSignedIn: false, username: null };
+							},
+						}));
+					}
+				}
+			`,
+            'index.ts': `
+				import { AuthBasic } from './auth.js';
+
+				${API_NS_MOCK}
+
+				const auth = new AuthBasic();
+
+				export const api = new ApiNamespace(null, 'api', (context) => ({
+					async greet(name: string) {
+						return { message: 'hello ' + name };
+					},
+				}));
+
+				export const authApi = auth.createApi();
+			`,
+        });
+        try {
+            const types = extractMethodTypes(join(dir, 'index.ts'));
+            // Direct ApiNamespace methods should still work
+            assert.ok(types.has('greet'), 'should find greet from direct ApiNamespace');
+            const greet = types.get('greet');
+            assert.strictEqual(greet.params[0].name, 'name');
+            assert.strictEqual(greet.params[0].schema.type, 'string');
+            // Indirect methods from auth.createApi() should now be resolved
+            assert.ok(types.has('getAuthState'), 'should find getAuthState from auth.createApi()');
+            assert.ok(types.has('setAuthState'), 'should find setAuthState from auth.createApi()');
+            const getAuthState = types.get('getAuthState');
+            assert.strictEqual(getAuthState.params.length, 0, 'getAuthState has no params');
+            assert.strictEqual(getAuthState.returnType.type, 'object', 'return type should be object');
+            assert.ok(getAuthState.returnType.properties, 'return type should have properties');
+            assert.ok('isSignedIn' in getAuthState.returnType.properties, 'should have isSignedIn');
+            assert.ok('username' in getAuthState.returnType.properties, 'should have username');
+            const setAuthState = types.get('setAuthState');
+            assert.strictEqual(setAuthState.params.length, 2, 'setAuthState has 2 params');
+            assert.strictEqual(setAuthState.params[0].name, 'action');
+            assert.strictEqual(setAuthState.params[0].schema.type, 'string');
+            assert.strictEqual(setAuthState.params[1].name, 'fields');
+            assert.strictEqual(setAuthState.params[1].schema.type, 'object');
+            // Record<string, string> should emit additionalProperties: { type: 'string' }
+            assert.deepStrictEqual(setAuthState.params[1].schema.additionalProperties, { type: 'string' }, 'Record<string, string> should have additionalProperties: { type: "string" }');
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('does not overwrite methods already found by AST walk', () => {
+        const dir = createTempProject({
+            'tsconfig.json': JSON.stringify({
+                compilerOptions: {
+                    target: 'ESNext',
+                    module: 'ESNext',
+                    moduleResolution: 'bundler',
+                    strict: true,
+                },
+            }),
+            'index.ts': `
+				${API_NS_MOCK}
+
+				// new ApiNamespace — AST walk finds this
+				export const api = new ApiNamespace(null, 'api', (context) => ({
+					async greet(name: string) {
+						return { message: 'hello ' + name };
+					},
+				}));
+			`,
+        });
+        try {
+            const types = extractMethodTypes(join(dir, 'index.ts'));
+            assert.ok(types.has('greet'), 'should find greet');
+            // The AST-walk version should be preserved (it has richer info from the declaration)
+            assert.strictEqual(types.get('greet').params[0].name, 'name');
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});
+// ── Transferable detection ──────────────────────────────────────────────────
+// A "transferable" is a return type carrying a live handle (e.g.
+// `RealtimeChannel`, `FileDownloadHandle`). It implements `toJSON()` returning
+// a descriptor with a `__blocks: '<tag>'` literal. The spec emitter lowers that
+// into `x-blocks-transferable: '<tag>'` so native client codegen can reconstruct
+// a live handle on the receiving side. These tests target detection — the
+// emission step is straight-line glue and is exercised end-to-end every time
+// a customer's BB returns a transferable.
+const TRANSFERABLE_TSCONFIG = JSON.stringify({
+    compilerOptions: {
+        target: 'ESNext',
+        module: 'ESNext',
+        moduleResolution: 'bundler',
+        strict: true,
+        esModuleInterop: true,
+        skipLibCheck: true,
+    },
+});
+/**
+ * Inline definitions of the transferable protocol + a couple of common
+ * handles. Reusing one source-of-truth string keeps the per-test fixtures
+ * small and focused on the variation under test.
+ */
+const TRANSFERABLE_PRELUDE = `
+	${API_NS_MOCK}
+
+	interface RealtimeChannelDescriptor { __blocks: 'realtime/channel'; channel: string; }
+	interface RealtimeChannel<T = unknown> {
+		subscribe(handler: (message: T) => void): void;
+		toJSON(): RealtimeChannelDescriptor;
+	}
+
+	interface FileDownloadDescriptor { __blocks: 'file-bucket/download'; url: string; }
+	interface FileDownloadHandle {
+		download(): Promise<Blob>;
+		toJSON(): FileDownloadDescriptor;
+	}
+`;
+describe('extractMethodTypes — transferable detection', () => {
+    it('identifies a generic transferable and resolves its written type arg', () => {
+        const dir = createTempProject({
+            'tsconfig.json': TRANSFERABLE_TSCONFIG,
+            'index.ts': `
+				${TRANSFERABLE_PRELUDE}
+				interface CursorPosition { userId: string; x: number; y: number; }
+				export const api = new ApiNamespace(null, 'api', () => ({
+					async getCursorChannel(): Promise<RealtimeChannel<CursorPosition>> { return null as any; },
+				}));
+			`,
+        });
+        try {
+            const info = extractMethodTypes(join(dir, 'index.ts')).get('getCursorChannel');
+            assert.ok(info, 'method should be discovered');
+            assert.ok(info.transferable, 'should be detected as transferable');
+            assert.strictEqual(info.transferable.blocksTag, 'realtime/channel');
+            assert.strictEqual(info.transferable.typeArgs.length, 1);
+            const arg = info.transferable.typeArgs[0];
+            assert.strictEqual(arg.title, 'CursorPosition');
+            assert.strictEqual(arg.properties?.userId?.type, 'string');
+            assert.strictEqual(arg.properties?.x?.type, 'number');
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('identifies a non-generic transferable with no type args', () => {
+        const dir = createTempProject({
+            'tsconfig.json': TRANSFERABLE_TSCONFIG,
+            'index.ts': `
+				${TRANSFERABLE_PRELUDE}
+				export const api = new ApiNamespace(null, 'api', () => ({
+					async getDownload(): Promise<FileDownloadHandle> { return null as any; },
+				}));
+			`,
+        });
+        try {
+            const info = extractMethodTypes(join(dir, 'index.ts')).get('getDownload');
+            assert.ok(info?.transferable);
+            assert.strictEqual(info.transferable.blocksTag, 'file-bucket/download');
+            assert.deepStrictEqual(info.transferable.typeArgs, []);
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('distinguishes default-unknown from explicit-unknown type args', () => {
+        const dir = createTempProject({
+            'tsconfig.json': TRANSFERABLE_TSCONFIG,
+            'index.ts': `
+				${TRANSFERABLE_PRELUDE}
+				export const api = new ApiNamespace(null, 'api', () => ({
+					async defaulted(): Promise<RealtimeChannel> { return null as any; },
+					async explicit(): Promise<RealtimeChannel<unknown>> { return null as any; },
+				}));
+			`,
+        });
+        try {
+            const types = extractMethodTypes(join(dir, 'index.ts'));
+            assert.deepStrictEqual(types.get('defaulted')?.transferable?.typeArgs, []);
+            assert.deepStrictEqual(types.get('explicit')?.transferable?.typeArgs, [{}]);
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('returns no transferable info when toJSON is missing or __blocks is not a literal', () => {
+        const dir = createTempProject({
+            'tsconfig.json': TRANSFERABLE_TSCONFIG,
+            'index.ts': `
+				${API_NS_MOCK}
+				interface Plain { value: number; }
+				interface NotLiteral { toJSON(): { __blocks: string; channel: string }; }
+				export const api = new ApiNamespace(null, 'api', () => ({
+					async plain(): Promise<Plain> { return null as any; },
+					async loose(): Promise<NotLiteral> { return null as any; },
+				}));
+			`,
+        });
+        try {
+            const types = extractMethodTypes(join(dir, 'index.ts'));
+            assert.strictEqual(types.get('plain')?.transferable, undefined);
+            assert.strictEqual(types.get('loose')?.transferable, undefined);
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('detects transferables imported from another module', () => {
+        const dir = createTempProject({
+            'tsconfig.json': TRANSFERABLE_TSCONFIG,
+            'handles.ts': `
+				export interface MessageDescriptor { __blocks: 'realtime/channel'; channel: string; }
+				export interface MessageChannel<T = unknown> {
+					subscribe(h: (m: T) => void): void;
+					toJSON(): MessageDescriptor;
+				}
+			`,
+            'index.ts': `
+				import type { MessageChannel } from './handles.js';
+				${API_NS_MOCK}
+				interface Notification { id: string; message: string; }
+				export const api = new ApiNamespace(null, 'api', () => ({
+					async getNotifications(): Promise<MessageChannel<Notification>> { return null as any; },
+				}));
+			`,
+        });
+        try {
+            const info = extractMethodTypes(join(dir, 'index.ts')).get('getNotifications');
+            assert.ok(info?.transferable);
+            assert.strictEqual(info.transferable.blocksTag, 'realtime/channel');
+            assert.strictEqual(info.transferable.typeArgs[0]?.title, 'Notification');
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});
+describe('extractMethodTypes — open-shape intersections', () => {
+    it('preserves additionalProperties from `T & Record<string, V>` intersections', () => {
+        const dir = createTempProject({
+            'tsconfig.json': JSON.stringify({
+                compilerOptions: {
+                    target: 'ESNext',
+                    module: 'ESNext',
+                    moduleResolution: 'bundler',
+                    strict: true,
+                },
+            }),
+            'index.ts': `
+				${API_NS_MOCK}
+
+				// Mirrors AuthCognito's signUp payload: fixed fields plus an open
+				// string-keyed bag for custom attributes.
+				type SignUpInput = { username: string; password: string } & Record<string, string>;
+
+				export const api = new ApiNamespace(null, 'api', () => ({
+					async signUp(input: SignUpInput) { return { success: true }; },
+				}));
+			`,
+        });
+        try {
+            const info = extractMethodTypes(join(dir, 'index.ts')).get('signUp');
+            assert.ok(info, 'should find signUp');
+            const inputSchema = info.params[0].schema;
+            assert.strictEqual(inputSchema.type, 'object');
+            assert.ok(inputSchema.properties?.username, 'fixed username property survives');
+            assert.ok(inputSchema.properties?.password, 'fixed password property survives');
+            assert.ok(inputSchema.additionalProperties, 'open shape preserved as additionalProperties');
+            assert.strictEqual(inputSchema.additionalProperties.type, 'string');
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('emits additionalProperties for object types with index signatures alongside fixed properties', () => {
+        const dir = createTempProject({
+            'tsconfig.json': JSON.stringify({
+                compilerOptions: {
+                    target: 'ESNext',
+                    module: 'ESNext',
+                    moduleResolution: 'bundler',
+                    strict: true,
+                },
+            }),
+            'index.ts': `
+				${API_NS_MOCK}
+
+				interface OpenShape {
+					id: string;
+					[key: string]: string;
+				}
+
+				export const api = new ApiNamespace(null, 'api', () => ({
+					async tag(input: OpenShape) { return { success: true }; },
+				}));
+			`,
+        });
+        try {
+            const info = extractMethodTypes(join(dir, 'index.ts')).get('tag');
+            assert.ok(info, 'should find tag');
+            const inputSchema = info.params[0].schema;
+            assert.strictEqual(inputSchema.type, 'object');
+            assert.ok(inputSchema.properties?.id, 'fixed id property survives');
+            assert.ok(inputSchema.additionalProperties, 'index signature surfaces as additionalProperties');
+            assert.strictEqual(inputSchema.additionalProperties.type, 'string');
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});

package/dist/scripts/generate-client-worker.d.ts

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

package/dist/scripts/generate-client-worker.d.ts.map

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

package/dist/scripts/generate-client-worker.js

@@ -0,0 +1,13 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Worker script for generating client code.
+ * Usage: node [--conditions=aws-runtime] --import tsx generate-client-worker.js <foundationPath> <outputPath>
+ */
+import { generateClientCode } from './generate-client.js';
+import { writeFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+const [foundationPath, outputPath] = process.argv.slice(2);
+const code = await generateClientCode(foundationPath);
+mkdirSync(dirname(outputPath), { recursive: true });
+writeFileSync(outputPath, code);

package/dist/scripts/generate-client.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Generate browser-safe client code from backend exports.
+ *
+ * Sets up global collectors (__BLOCKS_CLIENT_MIDDLEWARE__) before importing
+ * the backend so that Building Block constructors can register their
+ * middleware. After import, reads the collected specifiers and emits
+ * import statements + ApiNamespace proxy exports.
+ */
+export declare function generateClientCode(foundationPath: string): Promise<string>;
+/**
+ * Generate client code and write it to the aws-blocks subpackage.
+ */
+export declare function writeClientCode(foundationPath: string, outputPath: string): Promise<void>;
+//# sourceMappingURL=generate-client.d.ts.map

package/dist/scripts/generate-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-client.d.ts","sourceRoot":"","sources":["../../src/scripts/generate-client.ts"],"names":[],"mappings":"AAQA;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4DhF;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAI/F"}

package/dist/scripts/generate-client.js

@@ -0,0 +1,73 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { writeFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+import { pathToFileURL } from 'url';
+import { API_NAMESPACE_MARKER } from '../api.js';
+/**
+ * Generate browser-safe client code from backend exports.
+ *
+ * Sets up global collectors (__BLOCKS_CLIENT_MIDDLEWARE__) before importing
+ * the backend so that Building Block constructors can register their
+ * middleware. After import, reads the collected specifiers and emits
+ * import statements + ApiNamespace proxy exports.
+ */
+export async function generateClientCode(foundationPath) {
+    // Set up global collector if not already present (dev server may have already done this)
+    const collectorAlreadyActive = Array.isArray(globalThis.__BLOCKS_CLIENT_MIDDLEWARE__);
+    if (!collectorAlreadyActive) {
+        globalThis.__BLOCKS_CLIENT_MIDDLEWARE__ = [];
+    }
+    const backend = await import(pathToFileURL(foundationPath).href);
+    // Read collected middleware and clean up
+    const middleware = globalThis.__BLOCKS_CLIENT_MIDDLEWARE__;
+    delete globalThis.__BLOCKS_CLIENT_MIDDLEWARE__;
+    const imports = new Set();
+    const lines = [];
+    const namespaceNames = [];
+    imports.add(`import { ApiNamespaceClient as __BLOCKS_ApiNamespaceClient__ } from '@aws-blocks/blocks/client';`);
+    for (const specifier of middleware) {
+        imports.add(`import '${specifier}';`);
+    }
+    // Emit ApiNamespace proxy exports
+    for (const [name, value] of Object.entries(backend)) {
+        if (name.startsWith('_'))
+            continue;
+        const isApiNamespace = typeof value?.[API_NAMESPACE_MARKER] === 'string';
+        if (isApiNamespace) {
+            lines.push(`export const ${name} = __BLOCKS_ApiNamespaceClient__('${name}');`);
+            namespaceNames.push(name);
+            continue;
+        }
+        // Fallback: any exported function/object that isn't a Scope gets a proxy.
+        const isScope = typeof value?.id === 'string' && typeof value?.fullId === 'string';
+        if (isScope)
+            continue;
+        // Fallback: any exported function/object gets an ApiNamespace proxy.
+        if ((typeof value === 'function' || typeof value === 'object') && value !== null) {
+            lines.push(`export const ${name} = __BLOCKS_ApiNamespaceClient__('${name}');`);
+            namespaceNames.push(name);
+        }
+    }
+    // Emit generateClient — creates new ApiNamespaceClient instances with the given url
+    const nsEntries = namespaceNames.map(n => `    ${n}: __BLOCKS_ApiNamespaceClient__('${n}', config),`).join('\n');
+    lines.push('');
+    lines.push(`export const generateClient = (config) => ({\n${nsEntries}\n});`);
+    const header = [
+        '// ============================================================',
+        '// AUTO-GENERATED FILE — DO NOT EDIT',
+        '//',
+        '// This file is generated by the Blocks dev server / build process.',
+        '// Any manual changes will be overwritten on the next build.',
+        '// ============================================================',
+    ];
+    return [...header, '', ...imports, '', ...lines].join('\n');
+}
+/**
+ * Generate client code and write it to the aws-blocks subpackage.
+ */
+export async function writeClientCode(foundationPath, outputPath) {
+    const code = await generateClientCode(foundationPath);
+    mkdirSync(dirname(outputPath), { recursive: true });
+    writeFileSync(outputPath, code);
+}

package/dist/scripts/generate-client.test.d.ts

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

package/dist/scripts/generate-client.test.d.ts.map

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

package/dist/scripts/generate-client.test.js

@@ -0,0 +1,48 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { generateClientCode } from './generate-client.js';
+import { writeFileSync, mkdirSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+/**
+ * Regression test: generateClientCode collects middleware from whatever
+ * the backend registers via registerClientMiddleware(). In sandbox mode,
+ * the backend is imported WITHOUT --conditions=aws-runtime, so it registers
+ * mock-middleware instead of aws-middleware. The dev server must NOT call
+ * generateClientCode in sandbox mode (sandbox.ts already generated the
+ * correct client with the aws-runtime condition).
+ *
+ * This test verifies the mechanism: middleware specifiers registered during
+ * backend import appear as imports in the generated client code.
+ */
+describe('generateClientCode — middleware collection', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = join(tmpdir(), `blocks-gen-client-test-${Date.now()}`);
+        mkdirSync(tmpDir, { recursive: true });
+    });
+    afterEach(() => {
+        rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('includes middleware specifiers registered by the backend', async () => {
+        // Create a minimal backend that registers a middleware specifier
+        const backendPath = join(tmpDir, 'backend.mjs');
+        writeFileSync(backendPath, `
+			globalThis.__BLOCKS_CLIENT_MIDDLEWARE__?.push('@aws-blocks/bb-realtime/aws-middleware');
+		`);
+        const code = await generateClientCode(backendPath);
+        assert.ok(code.includes("import '@aws-blocks/bb-realtime/aws-middleware'"), 'Generated client must include aws-middleware when backend registers it');
+        assert.ok(!code.includes('mock-middleware'), 'Generated client must NOT include mock-middleware when backend registers aws-middleware');
+    });
+    it('includes mock-middleware when backend registers it (local dev mode)', async () => {
+        const backendPath = join(tmpDir, 'backend.mjs');
+        writeFileSync(backendPath, `
+			globalThis.__BLOCKS_CLIENT_MIDDLEWARE__?.push('@aws-blocks/bb-realtime/mock-middleware');
+		`);
+        const code = await generateClientCode(backendPath);
+        assert.ok(code.includes("import '@aws-blocks/bb-realtime/mock-middleware'"), 'Generated client must include mock-middleware in local dev mode');
+        assert.ok(!code.includes('aws-middleware'), 'Generated client must NOT include aws-middleware in local dev mode');
+    });
+});

package/dist/scripts/generate-spec-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=generate-spec-cli.d.ts.map

package/dist/scripts/generate-spec-cli.d.ts.map

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