@aws-blocks/core 0.2.0 → 0.4.0

package/src/scripts/secret.test.ts

@@ -0,0 +1,35 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+import { runConfigCli } from './config.js';
+import { runSecretCli } from './secret.js';
+
+// argv parsing + validation only (no live SSM/Secrets Manager). The set/list/
+// remove SDK calls are exercised end-to-end during deploy verification.
+
+void describe('blocks secret / config CLI argv parsing', () => {
+	void it('rejects an unknown subcommand', async () => {
+		await assert.rejects(runSecretCli(['frobnicate']), /Unknown subcommand/);
+		await assert.rejects(runConfigCli(['frobnicate']), /Unknown subcommand/);
+	});
+
+	void it('requires a key for set (label reflects the kind)', async () => {
+		await assert.rejects(runSecretCli(['set']), /Usage: blocks secret set/);
+		await assert.rejects(runConfigCli(['set']), /Usage: blocks config set/);
+	});
+
+	void it('key-only set falls through to the hidden prompt (TTY error, not usage)', async () => {
+		await assert.rejects(runSecretCli(['set', 'ONLY_KEY']), /stdin is not a TTY/);
+	});
+
+	void it('requires a key for remove', async () => {
+		await assert.rejects(runSecretCli(['remove']), /Usage: blocks secret remove/);
+		await assert.rejects(runConfigCli(['remove']), /Usage: blocks config remove/);
+	});
+
+	void it('validates the key before any store call', async () => {
+		await assert.rejects(runSecretCli(['set', '1bad', 'value']), /Invalid key/);
+	});
+});

package/src/scripts/secret.ts

@@ -0,0 +1,35 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * `blocks secret` — manage a Blocks app's **secrets** (AWS Secrets Manager),
+ * pinned to the Blocks `/blocks/<stackId>/secrets` namespace (scoped to the app's
+ * stable `stackId` from `.blocks/config.json`, so two apps in one account never
+ * collide). Thin wrapper over the shared `@aws-blocks/hosting` CLI with the kind
+ * fixed to `secret`. The `config` counterpart is `./config.ts`.
+ *
+ * @module
+ */
+
+import { listValues, removeValue, runValueCli, setValue } from '@aws-blocks/hosting/scripts';
+import { blocksSecretPrefix } from '../secret-naming.js';
+
+/** Set (create or overwrite) a Blocks secret. */
+export function setSecret(key: string, value: string, opts: { stage?: string } = {}): Promise<void> {
+	return setValue('secret', key, value, { prefix: blocksSecretPrefix(), ...opts });
+}
+
+/** List Blocks secret keys (names only). */
+export function listSecrets(opts: { stage?: string } = {}): Promise<string[]> {
+	return listValues('secret', { prefix: blocksSecretPrefix(), ...opts });
+}
+
+/** Remove a Blocks secret. */
+export function removeSecret(key: string, opts: { stage?: string } = {}): Promise<boolean> {
+	return removeValue('secret', key, { prefix: blocksSecretPrefix(), ...opts });
+}
+
+/** CLI dispatcher for `blocks secret <set|list|remove> …`. */
+export function runSecretCli(argv: string[]): Promise<void> {
+	return runValueCli(argv, { kind: 'secret', prefix: blocksSecretPrefix(), label: 'blocks secret' });
+}

package/src/scripts/typegen.ts

@@ -0,0 +1,18 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * `blocks typegen` — generate the type-safe key augmentation for `getSecret` /
+ * `getConfig` in a Blocks app. Statically scans the app's `secret('...')` /
+ * `config('...')` calls (no execution, no AWS credentials) and writes a `.d.ts`
+ * that narrows the runtime getters to your declared keys (autocomplete + typo
+ * errors) with no call-site change.
+ *
+ * Thin pass-through to the `@aws-blocks/hosting` engine — the getters live on
+ * `@aws-blocks/hosting`, so the generated file augments that module by default;
+ * a Blocks app needs no extra configuration.
+ *
+ * @module
+ */
+
+export { runTypegenCli } from '@aws-blocks/hosting/scripts';

package/src/secret-naming.test.ts

@@ -0,0 +1,59 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+import { secretStoreLocator } from '@aws-blocks/hosting';
+import {
+	BLOCKS_CONFIG_PARAMETER_PREFIX,
+	BLOCKS_SECRET_PARAMETER_PREFIX,
+	blocksConfigParameterName,
+	blocksConfigPrefix,
+	blocksSecretParameterName,
+	blocksSecretPrefix,
+	blocksStoreConfig,
+} from './secret-naming.js';
+
+// These run with no `.blocks/config.json` in cwd, so they exercise the UNSCOPED
+// fallback. A real Blocks app has the file, so it gets the `stackId`-scoped path
+// (covered by the explicit-stackId cases below).
+void describe('Blocks value namespaces — fallback (no .blocks/config.json)', () => {
+	void it('falls back to the unscoped /blocks/secrets and /blocks/config bases', () => {
+		assert.strictEqual(BLOCKS_SECRET_PARAMETER_PREFIX, '/blocks/secrets');
+		assert.strictEqual(BLOCKS_CONFIG_PARAMETER_PREFIX, '/blocks/config');
+		// Secrets Manager names are slash-free at the root; SSM keeps the leading slash.
+		assert.strictEqual(blocksSecretParameterName('STRIPE_KEY'), 'blocks/secrets/STRIPE_KEY');
+		assert.strictEqual(blocksConfigParameterName('FEATURE_FLAGS'), '/blocks/config/FEATURE_FLAGS');
+		assert.deepStrictEqual(blocksStoreConfig(), {
+			secretStore: { prefix: '/blocks/secrets' },
+			configStore: { prefix: '/blocks/config' },
+		});
+	});
+
+	void it('matches the store locator the CLI/grant/runtime actually use (no divergent name)', () => {
+		assert.strictEqual(
+			blocksSecretParameterName('K'),
+			secretStoreLocator('K', { prefix: BLOCKS_SECRET_PARAMETER_PREFIX, store: 'secrets-manager' }),
+		);
+		assert.strictEqual(
+			blocksConfigParameterName('K'),
+			secretStoreLocator('K', { prefix: BLOCKS_CONFIG_PARAMETER_PREFIX, store: 'ssm' }),
+		);
+	});
+});
+
+void describe('Blocks value namespaces — stackId-scoped (B5)', () => {
+	void it('scopes the prefix by stackId so two apps in one account never collide', () => {
+		assert.strictEqual(blocksSecretPrefix('myapp'), '/blocks/myapp/secrets');
+		assert.strictEqual(blocksConfigPrefix('myapp'), '/blocks/myapp/config');
+		assert.deepStrictEqual(blocksStoreConfig('myapp'), {
+			secretStore: { prefix: '/blocks/myapp/secrets' },
+			configStore: { prefix: '/blocks/myapp/config' },
+		});
+	});
+
+	void it('scoped store names match secretStoreLocator (SM slash-free, SSM leading-slash)', () => {
+		assert.strictEqual(blocksSecretParameterName('STRIPE_KEY', 'myapp'), 'blocks/myapp/secrets/STRIPE_KEY');
+		assert.strictEqual(blocksConfigParameterName('FEATURE_FLAGS', 'myapp'), '/blocks/myapp/config/FEATURE_FLAGS');
+	});
+});

package/src/secret-naming.ts

@@ -0,0 +1,99 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Blocks-owned namespaces for hosting values.
+ *
+ * The mechanism (markers, resolvers, path/env naming) lives in the
+ * framework-neutral `@aws-blocks/hosting` package, which defaults to neutral
+ * `/hosting/secrets` and `/hosting/config` prefixes so a non-Blocks consumer
+ * never inherits Blocks branding.
+ *
+ * This module is the ONE place Blocks pins its own namespaces. The prefixes are
+ * **scoped to the app's stable `stackId`** (from the committed `.blocks/config.json`)
+ * — `/blocks/<stackId>/secrets` (Secrets Manager) and `/blocks/<stackId>/config`
+ * (SSM Parameter Store) — so two Blocks apps in one account/region never collide.
+ *
+ * Both sides derive the scope from the SAME source: the out-of-band CLI
+ * (`npm run secret`/`config`) and the CDK synth both call {@link blocksStoreConfig},
+ * which reads `stackId` via {@link getStackId}. When `.blocks/config.json` is absent
+ * (e.g. a bare unit test) both sides fall back to the unscoped `/blocks/secrets` /
+ * `/blocks/config` identically — so the CLI write and the deploy read can never
+ * diverge, whether the id is present or not. `stackId` is stage-independent
+ * (prod and sandbox share it); use the opt-in `stage` segment for per-stage values.
+ *
+ * @module
+ */
+
+import type { StoreConfig } from '@aws-blocks/hosting/constructs';
+import { secretStoreLocator } from '@aws-blocks/hosting';
+import { getStackId } from './scripts/stack-id.js';
+
+/** Base Blocks prefix for `secret()` values (Secrets Manager); scoped by `stackId`. */
+export const BLOCKS_SECRET_PARAMETER_PREFIX = '/blocks/secrets';
+
+/** Base Blocks prefix for `config()` values (SSM Parameter Store); scoped by `stackId`. */
+export const BLOCKS_CONFIG_PARAMETER_PREFIX = '/blocks/config';
+
+/**
+ * Resolve the app's `stackId` (stable, stage-independent, from `.blocks/config.json`),
+ * or `undefined` when it can't be read. Never throws — a missing id means both the
+ * CLI and synth fall back to the unscoped base prefix, so they still agree.
+ */
+function resolveStackId(explicit?: string): string | undefined {
+	if (explicit) return explicit;
+	try {
+		return getStackId();
+	} catch {
+		return undefined;
+	}
+}
+
+/** The Blocks `secret()` prefix, scoped to `stackId` when available. */
+export function blocksSecretPrefix(stackId?: string): string {
+	const id = resolveStackId(stackId);
+	return id ? `/blocks/${id}/secrets` : BLOCKS_SECRET_PARAMETER_PREFIX;
+}
+
+/** The Blocks `config()` prefix, scoped to `stackId` when available. */
+export function blocksConfigPrefix(stackId?: string): string {
+	const id = resolveStackId(stackId);
+	return id ? `/blocks/${id}/config` : BLOCKS_CONFIG_PARAMETER_PREFIX;
+}
+
+/**
+ * The **actual store name** of a Blocks `secret()` key in AWS Secrets Manager —
+ * routed through {@link secretStoreLocator} so it matches exactly what the CLI
+ * writes, the IAM grant scopes to, and the runtime resolver reads. Secrets Manager
+ * names are slash-free at the root, so this is `blocks/<stackId>/secrets/<KEY>`
+ * (no leading slash), NOT an SSM-style path. Pass `stackId` to compute it without
+ * reading `.blocks/config.json`.
+ *
+ * @example 'blocks/myapp/secrets/STRIPE_KEY'
+ */
+export function blocksSecretParameterName(key: string, stackId?: string): string {
+	return secretStoreLocator(key, { prefix: blocksSecretPrefix(stackId), store: 'secrets-manager' });
+}
+
+/**
+ * The **actual store name** of a Blocks `config()` key in SSM Parameter Store —
+ * routed through {@link secretStoreLocator} for consistency with the CLI/grant/
+ * runtime path. SSM keeps the leading-slash path.
+ *
+ * @example '/blocks/myapp/config/FEATURE_FLAGS'
+ */
+export function blocksConfigParameterName(key: string, stackId?: string): string {
+	return secretStoreLocator(key, { prefix: blocksConfigPrefix(stackId), store: 'ssm' });
+}
+
+/**
+ * The Blocks store config passed to the shared hosting engine — `stackId`-scoped
+ * prefixes (falling back to the unscoped base when `.blocks/config.json` is absent).
+ * Both the CLI and the CDK synth call this, so they resolve identical names.
+ */
+export function blocksStoreConfig(stackId?: string): StoreConfig {
+	return {
+		secretStore: { prefix: blocksSecretPrefix(stackId) },
+		configStore: { prefix: blocksConfigPrefix(stackId) },
+	};
+}

package/src/version.ts

@@ -1,2 +1,2 @@
 // Auto-generated by scripts/generate-version.mjs — do not edit manually
-export const CORE_VERSION = '0.2.0';
+export const CORE_VERSION = '0.4.0';