@aws-blocks/core 0.1.0

package/dist/scripts/generate-spec-cli.js

@@ -0,0 +1,77 @@
+#!/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 } 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) {
+    if (!/\.(ts|tsx|mts|cts)$/i.test(foundationPath)) {
+        // JS entry point — let the default `import()` handle it.
+        return undefined;
+    }
+    let tsImport;
+    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.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);
+}
+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/dist/scripts/generate-spec-cli.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=generate-spec-cli.test.d.ts.map

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

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

package/dist/scripts/generate-spec-cli.test.js

@@ -0,0 +1,90 @@
+/**
+ * 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, ext) {
+    // 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, env = 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.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.map((m) => m.name).sort();
+            assert.deepStrictEqual(methodNames, ['api.echo', 'api.ping']);
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});

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

@@ -0,0 +1,61 @@
+interface OpenRpcDocument {
+    openrpc: string;
+    info: {
+        title: string;
+        version: string;
+    };
+    servers?: {
+        name: string;
+        url: string;
+    }[];
+    methods: OpenRpcMethod[];
+    components?: {
+        schemas?: Record<string, JsonSchema>;
+    };
+}
+interface OpenRpcMethod {
+    name: string;
+    params: OpenRpcParam[];
+    result: OpenRpcResult;
+}
+interface OpenRpcParam {
+    name: string;
+    required: boolean;
+    schema: JsonSchema;
+}
+interface OpenRpcResult {
+    name: string;
+    schema: JsonSchema;
+}
+interface JsonSchema {
+    type?: string;
+    $ref?: string;
+    [key: string]: unknown;
+}
+/**
+ * Discover all `ApiNamespace` exports from the backend module and build
+ * an OpenRPC document describing every method.
+ *
+ * For methods that reference Zod schemas (detected via `.parse()` calls in
+ * the function body), emits precise JSON Schema types. For plain TS methods,
+ * falls back to `{ "type": "unknown" }`.
+ *
+ * Named schemas (via `.meta({ id: 'Post' })`) are placed in
+ * `components.schemas` with `$ref` pointers. Unnamed schemas are inlined
+ * or given synthetic names like `KvGetInput`.
+ */
+/**
+ * Loader for the foundation module. Defaults to plain dynamic `import()` so JS
+ * entry points work with no extra deps. The CLI overrides this with a tsx-based
+ * loader when the entry point ends in `.ts` / `.tsx`, so customers can point the
+ * spec emitter at their TypeScript source without an extra build step.
+ */
+export type FoundationLoader = (fileUrl: string) => Promise<Record<string, unknown>>;
+export declare function generateSpec(foundationPath: string, loader?: FoundationLoader): Promise<OpenRpcDocument>;
+/**
+ * Generate the OpenRPC spec, validate it, and write it to disk as `blocks.spec.json`.
+ * Logs validation warnings but does not fail — the spec is still written.
+ */
+export declare function writeSpec(foundationPath: string, outputPath: string, loader?: FoundationLoader): Promise<void>;
+export {};
+//# sourceMappingURL=generate-spec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"generate-spec.d.ts","sourceRoot":"","sources":["../../src/scripts/generate-spec.ts"],"names":[],"mappings":"AA2BA,UAAU,eAAe;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC1C,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;KAAE,CAAC;CACtD;AAED,UAAU,aAAa;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,MAAM,EAAE,aAAa,CAAC;CACtB;AAED,UAAU,YAAY;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;CACnB;AAED,UAAU,aAAa;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,CAAC;CACnB;AAED,UAAU,UAAU;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAsKD;;;;;;;;;;;GAWG;AACH;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAIrF,wBAAsB,YAAY,CACjC,cAAc,EAAE,MAAM,EACtB,MAAM,GAAE,gBAAgC,GACtC,OAAO,CAAC,eAAe,CAAC,CAsQ1B;AAyQD;;;GAGG;AACH,wBAAsB,SAAS,CAC9B,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,gBAAgB,GACvB,OAAO,CAAC,IAAI,CAAC,CA0Bf"}