@aws-blocks/core 0.1.0

package/src/scripts/generate-client-worker.ts

@@ -0,0 +1,15 @@
+// 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/src/scripts/generate-client.test.ts

@@ -0,0 +1,69 @@
+// 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: string;
+
+	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/src/scripts/generate-client.ts

@@ -0,0 +1,86 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { readFileSync, 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: string): Promise<string> {
+  // Set up global collector if not already present (dev server may have already done this)
+  const collectorAlreadyActive = Array.isArray((globalThis as any).__BLOCKS_CLIENT_MIDDLEWARE__);
+  if (!collectorAlreadyActive) {
+    (globalThis as any).__BLOCKS_CLIENT_MIDDLEWARE__ = [];
+  }
+
+  const backend = await import(pathToFileURL(foundationPath).href);
+
+  // Read collected middleware and clean up
+  const middleware: string[] = (globalThis as any).__BLOCKS_CLIENT_MIDDLEWARE__;
+  delete (globalThis as any).__BLOCKS_CLIENT_MIDDLEWARE__;
+
+  const imports = new Set<string>();
+  const lines: string[] = [];
+  const namespaceNames: string[] = [];
+
+  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 as any)?.[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 as any)?.id === 'string' && typeof (value as any)?.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: string, outputPath: string): Promise<void> {
+  const code = await generateClientCode(foundationPath);
+  mkdirSync(dirname(outputPath), { recursive: true });
+  writeFileSync(outputPath, code);
+}

package/src/scripts/generate-spec-cli.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Integration test for the `blocks-generate-spec` bin.
+ *
+ * Verifies:
+ *   1. The CLI accepts a `.ts` entry point (regression for the
+ *      "Unknown file extension .ts" failure that broke fresh scaffolds).
+ *   2. The CLI still accepts a `.js` entry point and does not require tsx.
+ *
+ * Spawns the bin as a child process, the same way an end user (or `npx`) would.
+ * The "tsx missing" branch is covered by manual review — it's hard to
+ * simulate inside this monorepo where `tsx` is hoisted at the workspace root.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { writeFileSync, mkdirSync, rmSync, readFileSync, existsSync, copyFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cliPath = join(__dirname, 'generate-spec-cli.js');
+
+function makeBackend(dir: string, ext: 'ts' | 'js'): string {
+	// Copy the marker module next to the foundation so a relative import
+	// resolves through both ESM and CJS loaders.
+	const distDir = join(__dirname, '..');
+	copyFileSync(join(distDir, 'api.js'), join(dir, 'api.js'));
+
+	const indexPath = join(dir, `index.${ext}`);
+	writeFileSync(indexPath, `
+		import { ApiNamespace } from './api.js';
+
+		export const api = new ApiNamespace(null, 'api', (context) => ({
+			async ping() { return { ok: true }; },
+			async echo(s) { return s; },
+		}));
+	`);
+	// tsconfig that allows JS so the spec emitter's TypeScript pass succeeds
+	// regardless of which extension the entry point uses.
+	writeFileSync(join(dir, 'tsconfig.json'), JSON.stringify({
+		compilerOptions: {
+			target: 'ESNext',
+			module: 'ESNext',
+			moduleResolution: 'bundler',
+			allowJs: true,
+			esModuleInterop: true,
+			skipLibCheck: true,
+		},
+	}));
+	return indexPath;
+}
+
+function runCli(args: string[], env: NodeJS.ProcessEnv = process.env) {
+	return spawnSync(process.execPath, [cliPath, ...args], {
+		encoding: 'utf-8',
+		env,
+	});
+}
+
+describe('blocks-generate-spec CLI', () => {
+	it('accepts a TypeScript entry point and emits a valid spec', async () => {
+		const dir = join(tmpdir(), `blocks-spec-cli-test-${Date.now()}-ts`);
+		mkdirSync(dir, { recursive: true });
+		const indexPath = makeBackend(dir, 'ts');
+		const outputPath = join(dir, 'blocks.spec.json');
+
+		try {
+			const result = runCli([indexPath, outputPath]);
+			assert.strictEqual(
+				result.status,
+				0,
+				`CLI exited ${result.status}.\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+			);
+			assert.ok(existsSync(outputPath), 'spec file should exist');
+			const spec = JSON.parse(readFileSync(outputPath, 'utf-8'));
+			const methodNames = (spec.methods as { name: string }[]).map((m) => m.name).sort();
+			assert.deepStrictEqual(methodNames, ['api.echo', 'api.ping']);
+		} finally {
+			rmSync(dir, { recursive: true, force: true });
+		}
+	});
+
+	it('accepts a JavaScript entry point (no tsx needed)', async () => {
+		const dir = join(tmpdir(), `blocks-spec-cli-test-${Date.now()}-js`);
+		mkdirSync(dir, { recursive: true });
+		const indexPath = makeBackend(dir, 'js');
+		const outputPath = join(dir, 'blocks.spec.json');
+
+		try {
+			const result = runCli([indexPath, outputPath]);
+			assert.strictEqual(
+				result.status,
+				0,
+				`CLI exited ${result.status}.\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+			);
+			const spec = JSON.parse(readFileSync(outputPath, 'utf-8'));
+			const methodNames = (spec.methods as { name: string }[]).map((m) => m.name).sort();
+			assert.deepStrictEqual(methodNames, ['api.echo', 'api.ping']);
+		} finally {
+			rmSync(dir, { recursive: true, force: true });
+		}
+	});
+
+});

package/src/scripts/generate-spec-cli.ts

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * CLI wrapper for `writeSpec()`. Generates `aws-blocks/blocks.spec.json` from a
+ * backend entry point. Exposed as the `blocks-generate-spec` bin entry on
+ * `@aws-blocks/core`, so any Blocks app can invoke it via
+ * `npx blocks-generate-spec`.
+ *
+ * Usage:
+ *   node dist/scripts/generate-spec-cli.js [backendPath] [outputPath]
+ *
+ * Defaults:
+ *   backendPath = ./aws-blocks/index.ts
+ *   outputPath  = ./aws-blocks/blocks.spec.json
+ *
+ * For a TypeScript backend entry, this CLI lazily loads `tsx` and uses
+ * its programmatic `tsImport` so no extra build step is needed. JS entries
+ * use plain `import()` and don't pull tsx in.
+ *
+ * The spec emitter loads the TypeScript compiler (~1.5s of cold-start), which
+ * is why this lives in its own CLI rather than being wired into `npm run dev`.
+ * See docs/native-clients/codegen-design.md § Build pipeline.
+ */
+
+import { resolve, dirname, join } from 'node:path';
+import { writeSpec, type FoundationLoader } from './generate-spec.js';
+
+/** Pick a loader based on the file extension. `.ts` / `.tsx` use tsx; everything else uses Node's native `import()`. */
+async function selectLoader(foundationPath: string): Promise<FoundationLoader | undefined> {
+	if (!/\.(ts|tsx|mts|cts)$/i.test(foundationPath)) {
+		// JS entry point — let the default `import()` handle it.
+		return undefined;
+	}
+
+	let tsImport: ((specifier: string, parentURL: string) => Promise<unknown>) | undefined;
+	try {
+		// `tsx/esm/api` is a peer-style helper. We require the consuming app to
+		// have it installed (via the template's devDependencies) rather than
+		// bundling it into @aws-blocks/core, so the runtime Lambda path stays
+		// JS-only. If it's missing, fall through to the helpful error below.
+		const mod = await import('tsx/esm/api');
+		tsImport = (mod as { tsImport?: typeof tsImport }).tsImport;
+	} catch {
+		throw new Error(
+			[
+				`Cannot load TypeScript entry "${foundationPath}" — \`tsx\` is not installed.`,
+				`Install it as a devDependency:`,
+				`    npm install -D tsx`,
+				`Or pass a pre-built JavaScript entry instead.`,
+			].join('\n'),
+		);
+	}
+
+	if (!tsImport) {
+		throw new Error(
+			`The installed version of tsx does not export \`tsImport\` from \`tsx/esm/api\`. Upgrade to tsx ≥ 4.7.`,
+		);
+	}
+
+	// `tsImport` needs a `parentURL` so it can resolve relative imports inside
+	// the TS file. `import.meta.url` of *this* CLI works because the entry
+	// path we pass is absolute — the parentURL only seeds the registry.
+	const parentURL = import.meta.url;
+	return (fileUrl) => tsImport!(fileUrl, parentURL) as Promise<Record<string, unknown>>;
+}
+
+async function main() {
+	const [, , backendArg, outputArg] = process.argv;
+
+	const backendPath = resolve(backendArg ?? './aws-blocks/index.ts');
+	const outputPath = resolve(
+		outputArg ?? join(dirname(backendPath), 'blocks.spec.json')
+	);
+
+	console.log('📝 Generating OpenRPC spec...');
+	console.log('   backend:', backendPath);
+	console.log('   output: ', outputPath);
+
+	try {
+		const loader = await selectLoader(backendPath);
+		await writeSpec(backendPath, outputPath, loader);
+		console.log('✅ OpenRPC spec written to', outputPath);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		console.error('❌ Spec generation failed:', message);
+		process.exit(1);
+	}
+}
+
+main();

package/src/scripts/generate-spec.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Integration test for `generateSpec`. Builds a tiny backend file with one
+ * normal method and one `@blocksSkipCodegen`-tagged method, runs the spec
+ * emitter, and asserts the tagged method is dropped from the OpenRPC
+ * document.
+ *
+ * Uses a `.js` foundation file so plain `node --test dist/...` can run the
+ * test without a TypeScript loader. The TS compiler still parses JSDoc on
+ * the `.js` file when `allowJs` is enabled in the synthetic tsconfig.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { writeFileSync, mkdirSync, rmSync } from 'fs';
+import { join, dirname } from 'path';
+import { tmpdir } from 'os';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { generateSpec } from './generate-spec.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// `import.meta.url` lives in dist/scripts/, so `..` is dist/ and the built
+// `api.js` is next to it. Re-using the real ApiNamespace ensures the marker
+// symbol matches what `generateSpec` discovers.
+const builtApiUrl = pathToFileURL(join(__dirname, '..', 'api.js')).href;
+
+function writeTsconfig(dir: string): void {
+	writeFileSync(join(dir, 'tsconfig.json'), JSON.stringify({
+		compilerOptions: {
+			target: 'ESNext',
+			module: 'ESNext',
+			moduleResolution: 'bundler',
+			allowJs: true,
+			esModuleInterop: true,
+			skipLibCheck: true,
+		},
+	}));
+}
+
+describe('generateSpec — @blocksSkipCodegen', () => {
+	it('drops methods carrying @blocksSkipCodegen from the OpenRPC document', async () => {
+		const dir = join(tmpdir(), `blocks-spec-test-${Date.now()}-skip`);
+		mkdirSync(dir, { recursive: true });
+		writeTsconfig(dir);
+
+		writeFileSync(join(dir, 'index.js'), `
+			import { ApiNamespace } from ${JSON.stringify(builtApiUrl)};
+
+			export const api = new ApiNamespace(null, 'api', (context) => ({
+				async normalMethod(name) {
+					return { greeting: 'hi ' + name };
+				},
+
+				/**
+				 * Mock-only helper.
+				 * @blocksSkipCodegen
+				 */
+				async getLastCode() {
+					return null;
+				},
+			}));
+		`);
+
+		try {
+			const doc = await generateSpec(join(dir, 'index.js'));
+			const methodNames = doc.methods.map((m) => m.name).sort();
+			assert.deepStrictEqual(
+				methodNames,
+				['api.normalMethod'],
+				'getLastCode should be omitted; only normalMethod should remain',
+			);
+		} finally {
+			rmSync(dir, { recursive: true, force: true });
+		}
+	});
+
+	it('keeps methods that do not carry the tag', async () => {
+		const dir = join(tmpdir(), `blocks-spec-test-${Date.now()}-keep`);
+		mkdirSync(dir, { recursive: true });
+		writeTsconfig(dir);
+
+		writeFileSync(join(dir, 'index.js'), `
+			import { ApiNamespace } from ${JSON.stringify(builtApiUrl)};
+
+			export const api = new ApiNamespace(null, 'api', (context) => ({
+				/** Plain JSDoc with no special tag. */
+				async ping() { return { ok: true }; },
+				async echo(s) { return s; },
+			}));
+		`);
+
+		try {
+			const doc = await generateSpec(join(dir, 'index.js'));
+			const methodNames = doc.methods.map((m) => m.name).sort();
+			assert.deepStrictEqual(methodNames, ['api.echo', 'api.ping']);
+		} finally {
+			rmSync(dir, { recursive: true, force: true });
+		}
+	});
+});