@aws-blocks/core 0.1.18 → 0.3.0

package/dist/scripts/preflight-credentials.test.js

@@ -0,0 +1,77 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert';
+import { describe, it, mock } from 'node:test';
+import { assertAwsCredentials, resolveProbeRegion } from './preflight-credentials.js';
+const REGION_ENV = { AWS_REGION: 'us-east-1' };
+/** Build an Error with a specific `name`, as the AWS SDK throws. */
+function namedError(name, message = 'raw sdk detail') {
+    const err = new Error(message);
+    err.name = name;
+    return err;
+}
+describe('resolveProbeRegion', () => {
+    it('prefers AWS_REGION', () => {
+        assert.strictEqual(resolveProbeRegion({ AWS_REGION: 'eu-west-1', AWS_DEFAULT_REGION: 'us-east-2' }), 'eu-west-1');
+    });
+    it('falls back to AWS_DEFAULT_REGION', () => {
+        assert.strictEqual(resolveProbeRegion({ AWS_DEFAULT_REGION: 'ap-south-1' }), 'ap-south-1');
+    });
+    it('returns null when neither is set (caller then skips the probe)', () => {
+        assert.strictEqual(resolveProbeRegion({}), null);
+    });
+});
+describe('assertAwsCredentials', () => {
+    it('resolves silently when the credential probe succeeds', async () => {
+        let calledRegion;
+        await assert.doesNotReject(() => assertAwsCredentials('sandbox', async (region) => {
+            calledRegion = region;
+        }, REGION_ENV));
+        assert.strictEqual(calledRegion, 'us-east-1');
+    });
+    it('throws actionable guidance on a real credential error, naming the command', async () => {
+        await assert.rejects(() => assertAwsCredentials('sandbox', async () => { throw namedError('CredentialsProviderError'); }, REGION_ENV), (err) => {
+            assert.match(err.message, /npm run sandbox/);
+            assert.match(err.message, /aws configure|AWS_PROFILE|AWS_ACCESS_KEY_ID/);
+            assert.match(err.message, /CredentialsProviderError/); // the name, for debugging
+            return true;
+        });
+    });
+    it('treats an expired token as a credential error', async () => {
+        await assert.rejects(() => assertAwsCredentials('deploy', async () => { throw namedError('ExpiredToken'); }, REGION_ENV), (err) => {
+            assert.match(err.message, /npm run deploy/);
+            assert.match(err.message, /aws sso login|AWS_PROFILE/);
+            return true;
+        });
+    });
+    it('does NOT leak the raw error message (ARN / account id)', async () => {
+        const arnMessage = 'User: arn:aws:iam::123456789012:user/alice is not authorized to perform sts:GetCallerIdentity';
+        await assert.rejects(() => assertAwsCredentials('deploy', async () => { throw namedError('InvalidClientTokenId', arnMessage); }, REGION_ENV), (err) => {
+            assert.doesNotMatch(err.message, /arn:aws:iam/);
+            assert.doesNotMatch(err.message, /123456789012/);
+            return true;
+        });
+    });
+    it('does not throw on a network/service error — warns and continues', async () => {
+        const warn = mock.method(console, 'warn', () => { });
+        try {
+            await assert.doesNotReject(() => assertAwsCredentials('sandbox', async () => { throw namedError('TimeoutError'); }, REGION_ENV));
+            assert.ok(warn.mock.calls.some((c) => String(c.arguments[0]).includes('Could not verify')), 'should warn that credentials could not be verified');
+        }
+        finally {
+            warn.mock.restore();
+        }
+    });
+    it('skips the probe (with a warning) when no region is resolvable', async () => {
+        const warn = mock.method(console, 'warn', () => { });
+        let probed = false;
+        try {
+            await assertAwsCredentials('sandbox', async () => { probed = true; }, {});
+            assert.strictEqual(probed, false, 'probe must not run without a region');
+            assert.ok(warn.mock.calls.some((c) => String(c.arguments[0]).includes('Skipping the AWS credential pre-check')), 'should warn that the pre-check was skipped');
+        }
+        finally {
+            warn.mock.restore();
+        }
+    });
+});

package/dist/scripts/sandbox-args.test.d.ts

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

package/dist/scripts/sandbox-args.test.d.ts.map

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

package/dist/scripts/sandbox-args.test.js

@@ -0,0 +1,77 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { buildSandboxDeployArgs, sandboxFailureRecoveryHint } from './sandbox.js';
+import { buildCdkDeployArgs } from './deploy-stream.js';
+/**
+ * Return the value that follows `flag` in `args`, failing with a clear message
+ * if the flag is absent. Reading `args[indexOf(flag) + 1]` directly silently
+ * reads `args[0]` when the flag is missing (indexOf returns -1), which turns a
+ * dropped flag into a confusing value mismatch instead of a "flag missing".
+ *
+ * NOTE: resolves only the FIRST occurrence of `flag`. `--context` legitimately
+ * appears twice in this argv (projectRoot, then sandboxMode=true), so do not
+ * use `valueAfter(args, '--context')` expecting the second value — it silently
+ * returns the first. Assert repeated flags with `args.includes(...)` instead.
+ */
+function valueAfter(args, flag) {
+    const i = args.indexOf(flag);
+    assert.ok(i !== -1, `expected ${flag} in: ${args.join(' ')}`);
+    return args[i + 1];
+}
+describe('buildSandboxDeployArgs — express mode (sandbox only)', () => {
+    const args = buildSandboxDeployArgs({
+        outDir: '.blocks-sandbox',
+        projectRoot: '/app',
+        backendPath: 'aws-blocks/index.ts',
+    });
+    it('enables CloudFormation Express Mode via --express', () => {
+        assert.ok(args.includes('--express'), `expected --express in: ${args.join(' ')}`);
+    });
+    it('pairs express mode with the direct deployment method', () => {
+        assert.strictEqual(valueAfter(args, '--method'), 'direct');
+    });
+    it('leaves express-mode rollback at its default (off) — no --rollback', () => {
+        // Express Mode disables automatic rollback by default; we keep that default
+        // for the throwaway sandbox loop. Passing --rollback here would silently
+        // give up the speedup.
+        assert.ok(!args.includes('--rollback'), `sandbox must not force --rollback: ${args.join(' ')}`);
+    });
+    it('deploys every stack so Lambda@Edge apps synth cleanly', () => {
+        assert.ok(args.includes('--all'), `expected --all in: ${args.join(' ')}`);
+    });
+    it('keeps the non-interactive deploy contract and sandbox context', () => {
+        assert.deepStrictEqual(args.slice(0, 4), ['exec', 'cdk', '--', 'deploy']);
+        assert.strictEqual(valueAfter(args, '--require-approval'), 'never');
+        assert.strictEqual(valueAfter(args, '--outputs-file'), '.blocks-sandbox/outputs.json');
+        assert.ok(args.includes('sandboxMode=true'), `expected sandboxMode=true in: ${args.join(' ')}`);
+        assert.strictEqual(valueAfter(args, '--app'), 'npm exec tsx -- -C cdk aws-blocks/index.ts');
+    });
+    it('interpolates the provided outDir and projectRoot', () => {
+        const custom = buildSandboxDeployArgs({ outDir: 'out', projectRoot: '/other', backendPath: 'b.ts' });
+        assert.strictEqual(valueAfter(custom, '--outputs-file'), 'out/outputs.json');
+        assert.strictEqual(valueAfter(custom, '--context'), 'projectRoot=/other');
+    });
+    it('does NOT leak express mode into the production deploy path', () => {
+        // A production deploy must keep a reviewable change set and full
+        // stabilization with rollback: neither `--express` nor `--method direct`
+        // (both sandbox-only speedups) may appear in buildCdkDeployArgs.
+        const prod = buildCdkDeployArgs({ projectRoot: '/app', outputsFile: '.blocks-sandbox/outputs.json' });
+        assert.ok(!prod.includes('--express'), `production deploy must not use --express: ${prod.join(' ')}`);
+        assert.ok(!prod.includes('--method'), `production deploy must not use --method: ${prod.join(' ')}`);
+    });
+});
+describe('sandboxFailureRecoveryHint — no silent dead-end after a failed express deploy', () => {
+    const hint = sandboxFailureRecoveryHint();
+    it('points to the repo-native destroy + redeploy recovery', () => {
+        assert.match(hint, /npm run sandbox:destroy/);
+        assert.match(hint, /npm run sandbox\b/);
+    });
+    it('covers the manual UPDATE_ROLLBACK_FAILED escape hatch', () => {
+        assert.match(hint, /continue-update-rollback/);
+    });
+    it('explains why (rollback is off under express mode)', () => {
+        assert.match(hint, /rollback is off|automatic rollback/i);
+    });
+});

package/dist/scripts/sandbox.d.ts

@@ -6,6 +6,58 @@ export interface SandboxOptions {
     /** Custom dev server command. Defaults to 'npx vite'. For Next.js use 'npx next dev'. */
     devCommand?: string;
 }
+export interface SandboxDeployArgsOptions {
+    /** Directory CDK writes stack outputs to (relative to the project root). */
+    outDir: string;
+    /** Project root passed to synth as `--context projectRoot=…` (usually `process.cwd()`). */
+    projectRoot: string;
+    /** Backend entry passed to `--app` so CDK synthesizes from the app definition. */
+    backendPath: string;
+}
+/**
+ * Build the `npm exec cdk -- deploy …` argv used by the sandbox deploy.
+ *
+ * Kept pure (no I/O) so the argv contract — in particular the flags below — can
+ * be asserted directly, the same way {@link buildCdkDeployArgs} is for the
+ * production path.
+ *
+ * - `--all`: an app that uses Lambda@Edge (e.g. a Next.js route with
+ *   `export const runtime = 'edge'`) synthesizes a SECOND stack
+ *   (`edge-lambda-stack-*`, region us-east-1) in addition to the main hosting
+ *   stack. Without `--all`, CDK refuses with "specify which stacks to use".
+ *   Deploying every stack in a sandbox app is the intended behavior.
+ * - `--method direct`: skip CloudFormation change-set creation and call
+ *   UpdateStack directly. This is the baseline sandbox deployment method that
+ *   `--express` builds on.
+ * - `--express` (**CloudFormation Express Mode — sandbox only**): the real
+ *   speedup. CloudFormation reports each stack operation complete as soon as
+ *   the resource's configuration is applied, WITHOUT waiting for full
+ *   stabilization. Because it skips stabilization it also disables automatic
+ *   rollback by default, so a failed deploy can leave the stack in a failed
+ *   state — acceptable for the throwaway sandbox iteration loop, never for
+ *   production. We leave rollback at Express Mode's default (off) and do NOT
+ *   pass `--rollback`. The production deploy path (`deploy.ts`) deliberately
+ *   uses neither `--express` nor `--method direct`: it keeps a reviewable
+ *   change set and full stabilization with rollback, which are exactly the
+ *   safety signals a production deploy should keep. Requires an aws-cdk CLI
+ *   new enough to expose `--express`; our pinned `^2.1138.0` has it.
+ */
+export declare function buildSandboxDeployArgs({ outDir, projectRoot, backendPath }: SandboxDeployArgsOptions): string[];
+/**
+ * Operator-facing recovery guidance printed when a sandbox deploy fails.
+ *
+ * Express Mode (see {@link buildSandboxDeployArgs}) disables CloudFormation's
+ * automatic rollback, so a failed deploy does NOT clean up after itself: a
+ * failed *first* deploy leaves the stack in `CREATE_FAILED`/`ROLLBACK_COMPLETE`
+ * and a failed update can land in `UPDATE_ROLLBACK_FAILED`. In those states
+ * CloudFormation refuses the next `UpdateStack`, so a plain re-run of
+ * `npm run sandbox` would hit the same wall — a silent dead-end for the fast
+ * loop. This spells out the exact way out instead of leaving the operator to
+ * discover it via a cryptic CloudFormation error.
+ *
+ * Kept pure so it can be asserted in a unit test.
+ */
+export declare function sandboxFailureRecoveryHint(): string;
 export declare function startSandbox(options: SandboxOptions): Promise<string | undefined>;
 export declare function destroySandbox(backendPath: string): Promise<void>;
 //# sourceMappingURL=sandbox.d.ts.map

package/dist/scripts/sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/scripts/sandbox.ts"],"names":[],"mappings":"AA+BA,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,cAAc,+BAkMzD;AAED,wBAAsB,cAAc,CAAC,WAAW,EAAE,MAAM,iBAwCvD"}
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/scripts/sandbox.ts"],"names":[],"mappings":"AAiCA,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,2FAA2F;IAC3F,WAAW,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,EAAE,wBAAwB,GAAG,MAAM,EAAE,CAY/G;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,CAYnD;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,cAAc,+BAwMzD;AAED,wBAAsB,cAAc,CAAC,WAAW,EAAE,MAAM,iBAwCvD"}

package/dist/scripts/sandbox.js

@@ -5,9 +5,11 @@ import { writeFileSync, mkdirSync, readFileSync } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { ensureSecrets, loadEnvFile } from './ensure-secrets.js';
+import { assertAwsCredentials } from './preflight-credentials.js';
 import { applyExternalMigrations } from './external-migrations-step.js';
 import { trackCommand } from '../telemetry/trackCommand.js';
 import { buildAndSendEvent } from '../telemetry/client.js';
+import { classifyError } from '../telemetry/trackCommand.js';
 import { getCdkTelemetryEnv } from './cdk-telemetry-env.js';
 import { runSync, spawnCommand } from './run-command.js';
 import { terminateProcessTree } from './process-tree.js';
@@ -27,6 +29,74 @@ async function importBackendForRegistry(backendPath) {
         // best-effort — telemetry never affects the command
     }
 }
+/**
+ * Build the `npm exec cdk -- deploy …` argv used by the sandbox deploy.
+ *
+ * Kept pure (no I/O) so the argv contract — in particular the flags below — can
+ * be asserted directly, the same way {@link buildCdkDeployArgs} is for the
+ * production path.
+ *
+ * - `--all`: an app that uses Lambda@Edge (e.g. a Next.js route with
+ *   `export const runtime = 'edge'`) synthesizes a SECOND stack
+ *   (`edge-lambda-stack-*`, region us-east-1) in addition to the main hosting
+ *   stack. Without `--all`, CDK refuses with "specify which stacks to use".
+ *   Deploying every stack in a sandbox app is the intended behavior.
+ * - `--method direct`: skip CloudFormation change-set creation and call
+ *   UpdateStack directly. This is the baseline sandbox deployment method that
+ *   `--express` builds on.
+ * - `--express` (**CloudFormation Express Mode — sandbox only**): the real
+ *   speedup. CloudFormation reports each stack operation complete as soon as
+ *   the resource's configuration is applied, WITHOUT waiting for full
+ *   stabilization. Because it skips stabilization it also disables automatic
+ *   rollback by default, so a failed deploy can leave the stack in a failed
+ *   state — acceptable for the throwaway sandbox iteration loop, never for
+ *   production. We leave rollback at Express Mode's default (off) and do NOT
+ *   pass `--rollback`. The production deploy path (`deploy.ts`) deliberately
+ *   uses neither `--express` nor `--method direct`: it keeps a reviewable
+ *   change set and full stabilization with rollback, which are exactly the
+ *   safety signals a production deploy should keep. Requires an aws-cdk CLI
+ *   new enough to expose `--express`; our pinned `^2.1138.0` has it.
+ */
+export function buildSandboxDeployArgs({ outDir, projectRoot, backendPath }) {
+    return [
+        "exec", "cdk", "--", "deploy",
+        "--all",
+        "--method", "direct",
+        "--express",
+        "--require-approval", "never",
+        "--outputs-file", `${outDir}/outputs.json`,
+        "--context", `projectRoot=${projectRoot}`,
+        "--context", "sandboxMode=true",
+        "--app", `npm exec tsx -- -C cdk ${backendPath}`,
+    ];
+}
+/**
+ * Operator-facing recovery guidance printed when a sandbox deploy fails.
+ *
+ * Express Mode (see {@link buildSandboxDeployArgs}) disables CloudFormation's
+ * automatic rollback, so a failed deploy does NOT clean up after itself: a
+ * failed *first* deploy leaves the stack in `CREATE_FAILED`/`ROLLBACK_COMPLETE`
+ * and a failed update can land in `UPDATE_ROLLBACK_FAILED`. In those states
+ * CloudFormation refuses the next `UpdateStack`, so a plain re-run of
+ * `npm run sandbox` would hit the same wall — a silent dead-end for the fast
+ * loop. This spells out the exact way out instead of leaving the operator to
+ * discover it via a cryptic CloudFormation error.
+ *
+ * Kept pure so it can be asserted in a unit test.
+ */
+export function sandboxFailureRecoveryHint() {
+    return [
+        "",
+        "ℹ️  Express Mode leaves failed sandbox stacks in place (automatic rollback is off).",
+        "   If the next `npm run sandbox` reports the stack cannot be updated, recover with:",
+        "",
+        "     npm run sandbox:destroy   # tears the failed stack down (handles ROLLBACK_COMPLETE)",
+        "     npm run sandbox           # redeploy from a clean slate",
+        "",
+        "   If destroy reports UPDATE_ROLLBACK_FAILED, first run:",
+        "     aws cloudformation continue-update-rollback --stack-name <your-sandbox-stack>",
+    ].join("\n");
+}
 export async function startSandbox(options) {
     const { backendPath, outDir = ".blocks-sandbox", clientPort = 3000, deployOnly = false, devCommand } = options;
     const sandboxStartTime = Date.now();
@@ -39,6 +109,23 @@ export async function startSandbox(options) {
             throw e;
     }
     process.env.BLOCKS_STAGE = 'sandbox';
+    // Fail fast if AWS credentials are missing/expired, before spending ~10s in
+    // synth only to hit an opaque CDK credential error. Unlike deploy(), startSandbox
+    // isn't wrapped in trackCommand, so emit the FAIL event manually (mirroring the
+    // CDK-deploy failure path below) before rethrowing — otherwise a no-creds abort
+    // sends no telemetry.
+    try {
+        await assertAwsCredentials('sandbox');
+    }
+    catch (error) {
+        buildAndSendEvent({
+            command: 'sandbox',
+            state: 'FAIL',
+            duration: Date.now() - sandboxStartTime,
+            error: classifyError(error),
+        });
+        throw error;
+    }
     // Provision connection string to SSM SecureString.
     // On first deploy, creates the parameter. On subsequent deploys, updates if changed.
     // projectRoot is process.cwd() — the same value passed to cdk as --context
@@ -59,21 +146,10 @@ export async function startSandbox(options) {
     console.log("🚀 Deploying to AWS...");
     console.log("   (This may take a few minutes on first deploy)");
     try {
-        runSync("npm", [
-            "exec", "cdk", "--", "deploy",
-            // `--all`: an app that uses Lambda@Edge (e.g. a Next.js route with
-            // `export const runtime = 'edge'`) synthesizes a SECOND stack
-            // (`edge-lambda-stack-*`, region us-east-1) in addition to the main
-            // hosting stack. Without `--all`, CDK refuses with "specify which
-            // stacks to use". Deploying every stack in a sandbox app is the
-            // intended behavior, so select them all.
-            "--all",
-            "--require-approval", "never",
-            "--outputs-file", `${outDir}/outputs.json`,
-            "--context", `projectRoot=${process.cwd()}`,
-            "--context", "sandboxMode=true",
-            "--app", `npm exec tsx -- -C cdk ${backendPath}`,
-        ], {
+        runSync("npm", 
+        // Argv (including sandbox-only CloudFormation Express Mode, `--express`)
+        // is built by buildSandboxDeployArgs — see its doc for why each flag exists.
+        buildSandboxDeployArgs({ outDir, projectRoot: process.cwd(), backendPath }), {
             stdio: "inherit",
             env: { ...process.env, NODE_OPTIONS: "--conditions=cdk", ...getCdkTelemetryEnv('sandbox') },
         });
@@ -86,6 +162,7 @@ export async function startSandbox(options) {
             error: { code: 'CDK_DEPLOY_FAILED', phase: 'deploy' },
         });
         console.error("\n❌ Deployment failed.");
+        console.error(sandboxFailureRecoveryHint());
         throw error;
     }
     const outputs = JSON.parse(readFileSync(`${outDir}/outputs.json`, "utf-8"));

package/dist/scripts/secret.d.ts

@@ -0,0 +1,15 @@
+/** Set (create or overwrite) a Blocks secret. */
+export declare function setSecret(key: string, value: string, opts?: {
+    stage?: string;
+}): Promise<void>;
+/** List Blocks secret keys (names only). */
+export declare function listSecrets(opts?: {
+    stage?: string;
+}): Promise<string[]>;
+/** Remove a Blocks secret. */
+export declare function removeSecret(key: string, opts?: {
+    stage?: string;
+}): Promise<boolean>;
+/** CLI dispatcher for `blocks secret <set|list|remove> …`. */
+export declare function runSecretCli(argv: string[]): Promise<void>;
+//# sourceMappingURL=secret.d.ts.map

package/dist/scripts/secret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret.d.ts","sourceRoot":"","sources":["../../src/scripts/secret.ts"],"names":[],"mappings":"AAgBA,iDAAiD;AACjD,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAElG;AAED,4CAA4C;AAC5C,wBAAgB,WAAW,CAAC,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAE5E;AAED,8BAA8B;AAC9B,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAEzF;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1D"}

package/dist/scripts/secret.js

@@ -0,0 +1,29 @@
+// 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, value, opts = {}) {
+    return setValue('secret', key, value, { prefix: blocksSecretPrefix(), ...opts });
+}
+/** List Blocks secret keys (names only). */
+export function listSecrets(opts = {}) {
+    return listValues('secret', { prefix: blocksSecretPrefix(), ...opts });
+}
+/** Remove a Blocks secret. */
+export function removeSecret(key, opts = {}) {
+    return removeValue('secret', key, { prefix: blocksSecretPrefix(), ...opts });
+}
+/** CLI dispatcher for `blocks secret <set|list|remove> …`. */
+export function runSecretCli(argv) {
+    return runValueCli(argv, { kind: 'secret', prefix: blocksSecretPrefix(), label: 'blocks secret' });
+}

package/dist/scripts/secret.test.d.ts

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

package/dist/scripts/secret.test.d.ts.map

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

package/dist/scripts/secret.test.js

@@ -0,0 +1,28 @@
+// 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/dist/scripts/telemetry.test.js

@@ -23,6 +23,8 @@ const NO_CI_ENV = {
     TF_BUILD: '',
     BITBUCKET_BUILD_NUMBER: '',
     BUILDKITE: '',
+    RENDER: '',
+    TASKCLUSTER_ROOT_URL: '',
     AWS_BLOCKS_DISABLE_TELEMETRY: '',
 };
 function createTmpDir() {

package/dist/scripts/typegen.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `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';
+//# sourceMappingURL=typegen.d.ts.map

package/dist/scripts/typegen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typegen.d.ts","sourceRoot":"","sources":["../../src/scripts/typegen.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/scripts/typegen.js

@@ -0,0 +1,16 @@
+// 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/dist/secret-naming.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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';
+/** Base Blocks prefix for `secret()` values (Secrets Manager); scoped by `stackId`. */
+export declare const BLOCKS_SECRET_PARAMETER_PREFIX = "/blocks/secrets";
+/** Base Blocks prefix for `config()` values (SSM Parameter Store); scoped by `stackId`. */
+export declare const BLOCKS_CONFIG_PARAMETER_PREFIX = "/blocks/config";
+/** The Blocks `secret()` prefix, scoped to `stackId` when available. */
+export declare function blocksSecretPrefix(stackId?: string): string;
+/** The Blocks `config()` prefix, scoped to `stackId` when available. */
+export declare function blocksConfigPrefix(stackId?: string): string;
+/**
+ * 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 declare function blocksSecretParameterName(key: string, stackId?: string): string;
+/**
+ * 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 declare function blocksConfigParameterName(key: string, stackId?: string): string;
+/**
+ * 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 declare function blocksStoreConfig(stackId?: string): StoreConfig;
+//# sourceMappingURL=secret-naming.d.ts.map

package/dist/secret-naming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-naming.d.ts","sourceRoot":"","sources":["../src/secret-naming.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAIlE,uFAAuF;AACvF,eAAO,MAAM,8BAA8B,oBAAoB,CAAC;AAEhE,2FAA2F;AAC3F,eAAO,MAAM,8BAA8B,mBAAmB,CAAC;AAgB/D,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAG3D;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAG3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,CAK/D"}

package/dist/secret-naming.js

@@ -0,0 +1,67 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+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) {
+    if (explicit)
+        return explicit;
+    try {
+        return getStackId();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The Blocks `secret()` prefix, scoped to `stackId` when available. */
+export function blocksSecretPrefix(stackId) {
+    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) {
+    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, stackId) {
+    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, stackId) {
+    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) {
+    return {
+        secretStore: { prefix: blocksSecretPrefix(stackId) },
+        configStore: { prefix: blocksConfigPrefix(stackId) },
+    };
+}

package/dist/secret-naming.test.d.ts

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