@aws-blocks/core 0.2.0 → 0.3.0

package/dist/scripts/index.d.ts

@@ -1,13 +1,16 @@
-export { startDevServer, type DevServerOptions } from './dev-server.js';
-export { startSandbox, destroySandbox, type SandboxOptions } from './sandbox.js';
+export { type BuildAndSendEventOptions, buildAndSendEvent, type CommandName, type CommandState, classifyError, trackCommand, } from '../telemetry/index.js';
+export { listConfig, removeConfig, runConfigCli, setConfig } from './config.js';
+export { type ConsoleOptions, openConsole } from './console.js';
+export { type DeployOptions, deploy } from './deploy.js';
+export { type DestroyOptions, destroy } from './destroy.js';
+export { type DevServerOptions, startDevServer } from './dev-server.js';
+export { ensureSecrets, loadEnvFile, loadProductionEnv } from './ensure-secrets.js';
 export { generateClientCode, writeClientCode } from './generate-client.js';
 export { generateSpec, writeSpec } from './generate-spec.js';
-export { validateSpec, type SpecValidationError } from './validate-spec.js';
-export { deploy, type DeployOptions } from './deploy.js';
-export { destroy, type DestroyOptions } from './destroy.js';
-export { openConsole, type ConsoleOptions } from './console.js';
-export { ensureSecrets, loadProductionEnv, loadEnvFile } from './ensure-secrets.js';
-export { trackCommand, buildAndSendEvent, classifyError, type CommandName, type CommandState, type BuildAndSendEventOptions, } from '../telemetry/index.js';
-export { telemetry, type TelemetryOptions } from './telemetry.js';
-export { getStackId, getSandboxId, getStackName } from './stack-id.js';
+export { destroySandbox, type SandboxOptions, startSandbox } from './sandbox.js';
+export { listSecrets, removeSecret, runSecretCli, setSecret } from './secret.js';
+export { getSandboxId, getStackId, getStackName } from './stack-id.js';
+export { type TelemetryOptions, telemetry } from './telemetry.js';
+export { runTypegenCli } from './typegen.js';
+export { type SpecValidationError, validateSpec } from './validate-spec.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scripts/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,wBAAwB,GAC9B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scripts/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACN,KAAK,wBAAwB,EAC7B,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,aAAa,EACb,YAAY,GACZ,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,KAAK,cAAc,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,KAAK,cAAc,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,KAAK,gBAAgB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,KAAK,mBAAmB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/scripts/index.js

@@ -1,14 +1,17 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
+export { buildAndSendEvent, classifyError, trackCommand, } from '../telemetry/index.js';
+export { listConfig, removeConfig, runConfigCli, setConfig } from './config.js';
+export { openConsole } from './console.js';
+export { deploy } from './deploy.js';
+export { destroy } from './destroy.js';
 export { startDevServer } from './dev-server.js';
-export { startSandbox, destroySandbox } from './sandbox.js';
+export { ensureSecrets, loadEnvFile, loadProductionEnv } from './ensure-secrets.js';
 export { generateClientCode, writeClientCode } from './generate-client.js';
 export { generateSpec, writeSpec } from './generate-spec.js';
-export { validateSpec } from './validate-spec.js';
-export { deploy } from './deploy.js';
-export { destroy } from './destroy.js';
-export { openConsole } from './console.js';
-export { ensureSecrets, loadProductionEnv, loadEnvFile } from './ensure-secrets.js';
-export { trackCommand, buildAndSendEvent, classifyError, } from '../telemetry/index.js';
+export { destroySandbox, startSandbox } from './sandbox.js';
+export { listSecrets, removeSecret, runSecretCli, setSecret } from './secret.js';
+export { getSandboxId, getStackId, getStackName } from './stack-id.js';
 export { telemetry } from './telemetry.js';
-export { getStackId, getSandboxId, getStackName } from './stack-id.js';
+export { runTypegenCli } from './typegen.js';
+export { validateSpec } from './validate-spec.js';

package/dist/scripts/preflight-credentials.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Resolve the region for the STS probe from the environment. Returns `null`
+ * when neither `AWS_REGION` nor `AWS_DEFAULT_REGION` is set — the caller then
+ * skips the probe rather than guessing a region, because a hardcoded guess
+ * (e.g. `us-east-1`) belongs to a different **partition** than GovCloud
+ * (`us-gov-*`) or China (`cn-*`) and would fail against a partition the user
+ * isn't even deploying to.
+ */
+export declare function resolveProbeRegion(env?: NodeJS.ProcessEnv): string | null;
+/**
+ * Probe that resolves when valid AWS credentials are available for `region` and
+ * rejects otherwise. Injectable so the guard can be unit-tested without network
+ * or real credentials; production callers use the default {@link stsProbe}.
+ */
+export type CredentialProbe = (region: string) => Promise<void>;
+/**
+ * Verify AWS credentials before a deploy command spends time synthesizing, and
+ * fail fast with actionable guidance when they're missing, expired, or invalid.
+ *
+ * Skips silently (with a warning) when no region can be resolved from the
+ * environment, and treats network/service errors as non-fatal — see the module
+ * doc for the rationale.
+ *
+ * @param command - The npm script name, used in the messages (e.g. `sandbox`, `deploy`).
+ * @param probe - Credential probe; defaults to STS GetCallerIdentity. Override in tests.
+ * @param env - Environment to resolve the region from. Defaults to `process.env`.
+ * @throws {Error} With actionable guidance when the probe reports a credential error.
+ */
+export declare function assertAwsCredentials(command: string, probe?: CredentialProbe, env?: NodeJS.ProcessEnv): Promise<void>;
+//# sourceMappingURL=preflight-credentials.d.ts.map

package/dist/scripts/preflight-credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight-credentials.d.ts","sourceRoot":"","sources":["../../src/scripts/preflight-credentials.ts"],"names":[],"mappings":"AAmCA;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,IAAI,CAEtF;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAyBhE;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CACzC,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,eAA0B,EACjC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAClC,OAAO,CAAC,IAAI,CAAC,CAoCf"}

package/dist/scripts/preflight-credentials.js

@@ -0,0 +1,108 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Pre-deploy AWS credential check.
+ *
+ * `cdk deploy` spends ~10 seconds synthesizing the app before it makes its
+ * first AWS call, so a missing or expired credential surfaces only *after* that
+ * wasted synth — as an opaque CDK/CloudFormation error that doesn't name the
+ * real cause. Calling STS GetCallerIdentity up front turns that into an
+ * immediate, actionable message the moment a deploy command starts.
+ *
+ * The check is intentionally conservative: it fails fast **only** on a real
+ * credential problem (missing/expired/invalid). A network or service error
+ * (STS unreachable, throttled, disabled in a region) is not treated as a
+ * credential failure — it warns and lets the deploy proceed, since blocking on
+ * an unverifiable probe would reject a deploy that might have worked.
+ */
+/**
+ * Error `name`s that mean the credentials themselves are missing, expired, or
+ * invalid — the cases where the "configure your credentials" remediation is
+ * correct. Anything else (network, throttling, an explicit `AccessDenied` — which
+ * actually proves the identity resolved) is surfaced as itself instead.
+ */
+const CREDENTIAL_ERROR_NAMES = new Set([
+    'CredentialsProviderError',
+    'ExpiredToken',
+    'ExpiredTokenException',
+    'InvalidClientTokenId',
+    'UnrecognizedClientException',
+    'SignatureDoesNotMatch',
+    'TokenRefreshRequired',
+]);
+/**
+ * Resolve the region for the STS probe from the environment. Returns `null`
+ * when neither `AWS_REGION` nor `AWS_DEFAULT_REGION` is set — the caller then
+ * skips the probe rather than guessing a region, because a hardcoded guess
+ * (e.g. `us-east-1`) belongs to a different **partition** than GovCloud
+ * (`us-gov-*`) or China (`cn-*`) and would fail against a partition the user
+ * isn't even deploying to.
+ */
+export function resolveProbeRegion(env = process.env) {
+    return env.AWS_REGION || env.AWS_DEFAULT_REGION || null;
+}
+/**
+ * Default probe: STS GetCallerIdentity via the SDK's standard credential chain
+ * (env vars, shared config/credentials, SSO, container/instance roles).
+ *
+ * Dynamically imported so the STS client is only loaded when a deploy actually
+ * runs — never during dev-server startup or a mock unit test. Bounded with a
+ * short request timeout and a single attempt (matching `common/config.ts`) so a
+ * bad network can't make this hang *longer* than the synth it's replacing.
+ */
+const stsProbe = async (region) => {
+    const { STSClient, GetCallerIdentityCommand } = await import('@aws-sdk/client-sts');
+    const client = new STSClient({
+        region,
+        maxAttempts: 1,
+        requestHandler: { connectionTimeout: 2000, requestTimeout: 3000 },
+    });
+    try {
+        await client.send(new GetCallerIdentityCommand({}));
+    }
+    finally {
+        client.destroy();
+    }
+};
+/**
+ * Verify AWS credentials before a deploy command spends time synthesizing, and
+ * fail fast with actionable guidance when they're missing, expired, or invalid.
+ *
+ * Skips silently (with a warning) when no region can be resolved from the
+ * environment, and treats network/service errors as non-fatal — see the module
+ * doc for the rationale.
+ *
+ * @param command - The npm script name, used in the messages (e.g. `sandbox`, `deploy`).
+ * @param probe - Credential probe; defaults to STS GetCallerIdentity. Override in tests.
+ * @param env - Environment to resolve the region from. Defaults to `process.env`.
+ * @throws {Error} With actionable guidance when the probe reports a credential error.
+ */
+export async function assertAwsCredentials(command, probe = stsProbe, env = process.env) {
+    const region = resolveProbeRegion(env);
+    if (!region) {
+        console.warn(`⚠️  Skipping the AWS credential pre-check for \`npm run ${command}\`: ` +
+            'no region set in AWS_REGION / AWS_DEFAULT_REGION. The deploy will surface any credential error itself.');
+        return;
+    }
+    try {
+        await probe(region);
+    }
+    catch (error) {
+        // Use the error *name* only — never the raw message, which for an STS
+        // authorization failure embeds the caller ARN and account id (and this
+        // Error propagates through telemetry).
+        const name = error instanceof Error && error.name ? error.name : 'UnknownError';
+        if (CREDENTIAL_ERROR_NAMES.has(name)) {
+            throw new Error(`AWS credentials could not be verified for \`npm run ${command}\` (${name}).\n` +
+                'Configure AWS credentials — for example:\n' +
+                '  • run `aws configure` (or `aws sso login`), or\n' +
+                '  • set AWS_PROFILE to a configured profile, or\n' +
+                '  • export AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (and AWS_SESSION_TOKEN for temporary credentials).\n' +
+                `Then re-run \`npm run ${command}\`.`);
+        }
+        // Not a credential problem (network, throttling, STS disabled in-region, …).
+        // Don't block a deploy that might still work — warn and continue.
+        console.warn(`⚠️  Could not verify AWS credentials for \`npm run ${command}\` (${name}); ` +
+            'continuing — the deploy will report any real error.');
+    }
+}

package/dist/scripts/preflight-credentials.test.d.ts

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

package/dist/scripts/preflight-credentials.test.d.ts.map

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

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' });
+}