@aws-blocks/create-block 0.2.0

package/templates/primitive/src/index.cdk.test.ts

@@ -0,0 +1,47 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { test } from 'node:test';
+import assert from 'node:assert';
+import * as cdk from 'aws-cdk-lib';
+import type { Construct } from 'constructs';
+import { Template } from 'aws-cdk-lib/assertions';
+import { Scope } from '@aws-blocks/core/cdk';
+import { __BB_CLASS__ } from './index.cdk.js';
+
+// Minimal BlocksStack-shaped parent so __BB_CLASS__ can grant IAM on this.handler
+// and synth into a real stack. Mirrors the shape a real BlocksStack exposes.
+class StubBlocksStack extends cdk.Stack {
+	public readonly handler: cdk.aws_lambda.Function;
+	public readonly id: string;
+	constructor(scope: Construct, id: string) {
+		super(scope, id);
+		this.id = id;
+		(globalThis as { CURRENT_BLOCKS_STACK?: unknown }).CURRENT_BLOCKS_STACK = this;
+		this.handler = new cdk.aws_lambda.Function(this, 'StubHandler', {
+			runtime: cdk.aws_lambda.Runtime.NODEJS_22_X,
+			handler: 'index.handler',
+			code: cdk.aws_lambda.Code.fromInline('exports.handler = async () => {};'),
+		});
+	}
+}
+
+function setup(): { stack: StubBlocksStack; parent: Scope } {
+	const app = new cdk.App();
+	const stack = new StubBlocksStack(app, 'TestStack');
+	return { stack, parent: new Scope('app') };
+}
+
+test('CDK: the construct synthesizes within a stack', () => {
+	const { stack, parent } = setup();
+	new __BB_CLASS__(parent, 'thing');
+	// TODO: once you provision infra, assert it here, e.g.:
+	//   Template.fromStack(stack).resourceCountIs('AWS::DynamoDB::Table', 1);
+	assert.doesNotThrow(() => Template.fromStack(stack));
+});
+
+test('CDK: runtime methods throw during synth (synthGuard)', () => {
+	const { parent } = setup();
+	const bb = new __BB_CLASS__(parent, 'thing');
+	assert.throws(() => (bb as unknown as { echo: (s: string) => never }).echo('x'), /synth/i);
+});

package/templates/primitive/src/index.cdk.ts

@@ -0,0 +1,34 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Scope, synthGuard } from '@aws-blocks/core/cdk';
+import type { ScopeParent } from '@aws-blocks/core';
+import type { __BB_CLASS__Options } from './types.js';
+
+// ── Public types + errors ────────────────────────────────────────────────────
+export { __BB_CLASS__Errors } from './errors.js';
+export type { __BB_CLASS__Options } from './types.js';
+
+/**
+ * The `cdk` export: runs during `cdk synth` and provisions this block's
+ * infrastructure. It extends `Scope` (never wraps it) so infra discovery and
+ * IAM propagation work.
+ */
+export class __BB_CLASS__ extends Scope {
+	constructor(scope: ScopeParent, id: string, _options?: __BB_CLASS__Options) {
+		super(id, { parent: scope });
+		// TODO: provision your infrastructure and grant the shared Lambda access.
+		// Name resources off `this.fullId` so the runtime can derive the same name.
+		// Example:
+		//   const table = new Table(this, 'table', { tableName: this.fullId.substring(0, 255), ... });
+		//   table.grantReadWriteData(this.handler);
+		//   registerConfig(this, 'BLOCKS_THING_FLAG', '...'); // extra (non-name) config only
+	}
+
+	// Runtime methods are not available during CDK synth (AGENTS.md rule 4). Stub
+	// every method your runtime exposes so a top-level call fails with an
+	// actionable message instead of a cryptic "X is not a function".
+	echo(..._args: unknown[]): never {
+		return synthGuard('__BB_CLASS__', 'echo');
+	}
+}

package/templates/primitive/src/index.mock.ts

@@ -0,0 +1,46 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Scope, registerSdkIdentifiers } from '@aws-blocks/core';
+import type { ScopeParent } from '@aws-blocks/core';
+import { BB_NAME, BB_VERSION } from './version.js';
+
+// ── Public types + errors ────────────────────────────────────────────────────
+export { __BB_CLASS__Errors } from './errors.js';
+export type { __BB_CLASS__Options } from './types.js';
+
+import type { __BB_CLASS__Options } from './types.js';
+
+/**
+ * TODO: one-line summary of what __BB_CLASS__ does.
+ *
+ * This is the **local-dev / test** implementation (the `default` + `types`
+ * export). It runs during `npm run dev` and unit tests, so implement it with
+ * in-memory or on-disk state — never a real AWS call. Keep its public surface
+ * identical to `index.aws.ts` (the deployed runtime). See `bb-kv-store` for a
+ * worked example; this skeleton is intentionally storage-agnostic.
+ *
+ * **When to use:** TODO.
+ *
+ * **When NOT to use:** TODO.
+ */
+export class __BB_CLASS__ extends Scope {
+	constructor(scope: ScopeParent, id: string, _options?: __BB_CLASS__Options) {
+		super(id, { parent: scope, bbName: BB_NAME, bbVersion: BB_VERSION });
+		// The CDK layer provisions your resource under this same `fullId`. Register
+		// its identifier(s) here (e.g. `{ tableName: \`mock-${this.fullId}\` }`) so
+		// methods can resolve them with `getSdkIdentifiers(this)` at call time.
+		registerSdkIdentifiers(this.fullId, {});
+	}
+
+	/**
+	 * TODO: replace with your block's real API. This example method exists only
+	 * so the generated package builds and tests green out of the box.
+	 *
+	 * @param input - TODO describe.
+	 * @returns TODO describe.
+	 */
+	async echo(input: string): Promise<string> {
+		return input;
+	}
+}

package/templates/primitive/src/index.test.ts

@@ -0,0 +1,29 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { test, beforeEach } from 'node:test';
+import assert from 'node:assert';
+import { rmSync } from 'node:fs';
+import { Scope } from '@aws-blocks/core';
+import { __BB_CLASS__, __BB_CLASS__Errors } from './index.mock.js';
+
+// A real, typed parent Scope — no casts (this test represents customer usage).
+const parent = new Scope('test-app');
+let n = 0;
+const make = () => new __BB_CLASS__(parent, `thing-${n++}`);
+
+// Reset mock data between tests (blocks that persist to disk write under .bb-data).
+beforeEach(() => {
+	try {
+		rmSync('.bb-data', { recursive: true, force: true });
+	} catch {}
+});
+
+test('echo returns its input (TODO: replace with real coverage)', async () => {
+	const bb = make();
+	assert.strictEqual(await bb.echo('hello'), 'hello');
+});
+
+test('error constants are defined', () => {
+	assert.ok(__BB_CLASS__Errors.InvalidInput);
+});

package/templates/primitive/src/parity.test.ts

@@ -0,0 +1,16 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/** Ensures the four entry points expose a consistent public error surface. */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { __BB_CLASS__Errors as MockErrors } from './index.mock.js';
+import { __BB_CLASS__Errors as AwsErrors } from './index.aws.js';
+import { __BB_CLASS__Errors as CdkErrors } from './index.cdk.js';
+import { __BB_CLASS__Errors as BrowserErrors } from './index.browser.js';
+
+test('error constants are identical across mock / aws / cdk / browser', () => {
+	assert.deepEqual(MockErrors, AwsErrors);
+	assert.deepEqual(MockErrors, CdkErrors);
+	assert.deepEqual(MockErrors, BrowserErrors);
+});

package/templates/primitive/src/types.ts

@@ -0,0 +1,13 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Shared types for __BB_CLASS__. Imported by the mock, aws, cdk, and browser
+ * entry points. Types only — this file has zero runtime dependencies.
+ */
+
+/** Options for constructing a {@link __BB_CLASS__}. */
+export interface __BB_CLASS__Options {
+	/** TODO: add this block's configuration options (all optional — see AGENTS.md). */
+	label?: string;
+}

package/templates/primitive/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "references": [
+    { "path": "../core" }
+  ]
+}