@aws-blocks/core 0.2.0 → 0.4.0

package/src/scripts/dev-server.ts

@@ -105,6 +105,39 @@ export interface DevServerOptions {
   frontendCommand?: string;
   /** Port the frontend dev server listens on. Default: 3100. */
   frontendPort?: number;
+  /**
+   * Watch `secret()` / `config()` calls and regenerate the type-safe key
+   * augmentation (so `getSecret`/`getConfig` autocomplete and reject typos) as you
+   * edit — all under this one `npm run dev`, no second command. Auto-detected: a
+   * no-op unless the app actually declares a `secret()`/`config()`, and never fatal
+   * (a failure only logs a warning). Set `false` to disable. Default: enabled.
+   */
+  typegen?: boolean;
+}
+
+/**
+ * Bootstrap the type-safe `getSecret`/`getConfig` key generation for the dev
+ * session. Auto-detected and non-fatal: scans the app for `secret()`/`config()`
+ * calls and, only if it finds any, generates the augmentation `.d.ts` and starts a
+ * watcher that regenerates on save — so a single `npm run dev` gives type-safe keys
+ * with no second command. Returns a `stop()` (or `undefined` when the app declares
+ * no secrets, typegen is unavailable, or it is disabled). The watcher is `unref`'d
+ * so it can never block the dev server's shutdown.
+ */
+async function startTypegenWatch(): Promise<(() => void) | undefined> {
+  try {
+    const { scanValueKeys, watchHostingValues } = await import('@aws-blocks/hosting/scripts');
+    const scan = await scanValueKeys();
+    if (scan.secretKeys.length === 0 && scan.configKeys.length === 0) {
+      return undefined; // app doesn't use secret()/config() → nothing to type, skip silently
+    }
+    console.log('🔑 Type-safe secret()/config() keys — watching for changes...');
+    return await watchHostingValues({ unref: true });
+  } catch (error) {
+    // Never break the dev server over typegen (e.g. `typescript` not installed).
+    console.warn(`⚠️  hosting-typegen skipped: ${error instanceof Error ? error.message : String(error)}`);
+    return undefined;
+  }
 }
 
 /**
@@ -953,6 +986,12 @@ export async function startDevServer(options: DevServerOptions) {
     await writeClientCode(resolvedPath, clientPath);
   }
 
+  // Type-safe getSecret/getConfig: generate + watch the key augmentation so the
+  // getters autocomplete and reject typos, regenerating on save — all under this
+  // one `npm run dev`. Auto-detected (no-op unless the app uses secret()/config())
+  // and non-fatal.
+  const stopTypegen = options.typegen === false ? undefined : await startTypegenWatch();
+
   // ── Startup reclaim ──────────────────────────────────────────────────────
   // Free any port left bound by a crashed / SIGKILL'd predecessor before we bind
   // the front door or spawn the `--strictPort` frontend. tsx-watch only gives the
@@ -1039,6 +1078,7 @@ export async function startDevServer(options: DevServerOptions) {
     console.log('\nShutting down...');
 
     if (respawnTimer) { clearTimeout(respawnTimer); respawnTimer = null; }
+    stopTypegen?.(); // tear down the typegen watcher (unref'd, but close it cleanly)
     // Detach our own listeners so repeated signals can't pile up handlers.
     for (const sig of signals) process.removeListener(sig, cleanup);
 

package/src/scripts/generate-client.test.ts

@@ -1,12 +1,12 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { describe, it, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert';
+import { afterEach, beforeEach, describe, it } from 'node:test';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { generateClientCode } from './generate-client.js';
-import { writeFileSync, mkdirSync, rmSync } from 'fs';
-import { join } from 'path';
-import { tmpdir } from 'os';
 
 /**
  * Regression test: generateClientCode collects middleware from whatever
@@ -35,9 +35,12 @@ describe('generateClientCode — middleware collection', () => {
 	it('includes middleware specifiers registered by the backend', async () => {
 		// Create a minimal backend that registers a middleware specifier
 		const backendPath = join(tmpDir, 'backend.mjs');
-		writeFileSync(backendPath, `
+		writeFileSync(
+			backendPath,
+			`
 			globalThis.__BLOCKS_CLIENT_MIDDLEWARE__?.push('@aws-blocks/bb-realtime/aws-middleware');
-		`);
+		`,
+		);
 
 		const code = await generateClientCode(backendPath);
 		assert.ok(
@@ -52,9 +55,12 @@ describe('generateClientCode — middleware collection', () => {
 
 	it('includes mock-middleware when backend registers it (local dev mode)', async () => {
 		const backendPath = join(tmpDir, 'backend.mjs');
-		writeFileSync(backendPath, `
+		writeFileSync(
+			backendPath,
+			`
 			globalThis.__BLOCKS_CLIENT_MIDDLEWARE__?.push('@aws-blocks/bb-realtime/mock-middleware');
-		`);
+		`,
+		);
 
 		const code = await generateClientCode(backendPath);
 		assert.ok(
@@ -66,4 +72,33 @@ describe('generateClientCode — middleware collection', () => {
 			'Generated client must NOT include aws-middleware in local dev mode',
 		);
 	});
+
+	it('skips secret()/config() markers — they are values, not API namespaces', async () => {
+		// A secret()/config() marker is branded with Symbol.for('@aws-blocks/hosting.ManagedValue');
+		// build one inline so the fixture needs no imports. A real export still gets a proxy.
+		const backendPath = join(tmpDir, 'backend.mjs');
+		writeFileSync(
+			backendPath,
+			`
+				const BRAND = Symbol.for('@aws-blocks/hosting.ManagedValue');
+				export const stripeKey = { [BRAND]: true, key: 'STRIPE_KEY', kind: 'secret' };
+				export const featureFlags = { [BRAND]: true, key: 'FEATURE_FLAGS', kind: 'config' };
+				export function realApi() {}
+			`,
+		);
+
+		const code = await generateClientCode(backendPath);
+		assert.ok(
+			!code.includes("__BLOCKS_ApiNamespaceClient__('stripeKey')"),
+			'a secret() marker must not become an HTTP namespace',
+		);
+		assert.ok(
+			!code.includes("__BLOCKS_ApiNamespaceClient__('featureFlags')"),
+			'a config() marker must not become an HTTP namespace',
+		);
+		assert.ok(
+			code.includes("export const realApi = __BLOCKS_ApiNamespaceClient__('realApi')"),
+			'a real (non-marker) export still becomes a namespace',
+		);
+	});
 });

package/src/scripts/generate-client.ts

@@ -1,9 +1,10 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { readFileSync, writeFileSync, mkdirSync } from 'fs';
-import { dirname } from 'path';
-import { pathToFileURL } from 'url';
+import { isManagedValue } from '@aws-blocks/hosting';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { API_NAMESPACE_MARKER } from '../api.js';
 
 /**
@@ -15,72 +16,76 @@ import { API_NAMESPACE_MARKER } from '../api.js';
  * import statements + ApiNamespace proxy exports.
  */
 export async function generateClientCode(foundationPath: string): Promise<string> {
-  // Set up global collector if not already present (dev server may have already done this)
-  const collectorAlreadyActive = Array.isArray((globalThis as any).__BLOCKS_CLIENT_MIDDLEWARE__);
-  if (!collectorAlreadyActive) {
-    (globalThis as any).__BLOCKS_CLIENT_MIDDLEWARE__ = [];
-  }
-
-  const backend = await import(pathToFileURL(foundationPath).href);
-
-  // Read collected middleware and clean up
-  const middleware: string[] = (globalThis as any).__BLOCKS_CLIENT_MIDDLEWARE__;
-  delete (globalThis as any).__BLOCKS_CLIENT_MIDDLEWARE__;
-
-  const imports = new Set<string>();
-  const lines: string[] = [];
-  const namespaceNames: string[] = [];
-
-  imports.add(`import { ApiNamespaceClient as __BLOCKS_ApiNamespaceClient__ } from '@aws-blocks/blocks/client';`);
-
-  for (const specifier of middleware) {
-    imports.add(`import '${specifier}';`);
-  }
-
-  // Emit ApiNamespace proxy exports
-  for (const [name, value] of Object.entries(backend)) {
-    if (name.startsWith('_')) continue;
-
-    const isApiNamespace = typeof (value as any)?.[API_NAMESPACE_MARKER] === 'string';
-    if (isApiNamespace) {
-      lines.push(`export const ${name} = __BLOCKS_ApiNamespaceClient__('${name}');`);
-      namespaceNames.push(name);
-      continue;
-    }
-
-    // Fallback: any exported function/object that isn't a Scope gets a proxy.
-    const isScope = typeof (value as any)?.id === 'string' && typeof (value as any)?.fullId === 'string';
-    if (isScope) continue;
-
-    // Fallback: any exported function/object gets an ApiNamespace proxy.
-    if ((typeof value === 'function' || typeof value === 'object') && value !== null) {
-      lines.push(`export const ${name} = __BLOCKS_ApiNamespaceClient__('${name}');`);
-      namespaceNames.push(name);
-    }
-  }
-
-  // Emit generateClient — creates new ApiNamespaceClient instances with the given url
-  const nsEntries = namespaceNames.map(n => `    ${n}: __BLOCKS_ApiNamespaceClient__('${n}', config),`).join('\n');
-  lines.push('');
-  lines.push(`export const generateClient = (config) => ({\n${nsEntries}\n});`);
-
-  const header = [
-    '// ============================================================',
-    '// AUTO-GENERATED FILE — DO NOT EDIT',
-    '//',
-    '// This file is generated by the Blocks dev server / build process.',
-    '// Any manual changes will be overwritten on the next build.',
-    '// ============================================================',
-  ];
-
-  return [...header, '', ...imports, '', ...lines].join('\n');
+	// Set up global collector if not already present (dev server may have already done this)
+	const collectorAlreadyActive = Array.isArray((globalThis as any).__BLOCKS_CLIENT_MIDDLEWARE__);
+	if (!collectorAlreadyActive) {
+		(globalThis as any).__BLOCKS_CLIENT_MIDDLEWARE__ = [];
+	}
+
+	const backend = await import(pathToFileURL(foundationPath).href);
+
+	// Read collected middleware and clean up
+	const middleware: string[] = (globalThis as any).__BLOCKS_CLIENT_MIDDLEWARE__;
+	delete (globalThis as any).__BLOCKS_CLIENT_MIDDLEWARE__;
+
+	const imports = new Set<string>();
+	const lines: string[] = [];
+	const namespaceNames: string[] = [];
+
+	imports.add(`import { ApiNamespaceClient as __BLOCKS_ApiNamespaceClient__ } from '@aws-blocks/blocks/client';`);
+
+	for (const specifier of middleware) {
+		imports.add(`import '${specifier}';`);
+	}
+
+	// Emit ApiNamespace proxy exports
+	for (const [name, value] of Object.entries(backend)) {
+		if (name.startsWith('_')) continue;
+
+		const isApiNamespace = typeof (value as any)?.[API_NAMESPACE_MARKER] === 'string';
+		if (isApiNamespace) {
+			lines.push(`export const ${name} = __BLOCKS_ApiNamespaceClient__('${name}');`);
+			namespaceNames.push(name);
+			continue;
+		}
+
+		// Fallback: any exported function/object that isn't a Scope gets a proxy.
+		const isScope = typeof (value as any)?.id === 'string' && typeof (value as any)?.fullId === 'string';
+		if (isScope) continue;
+
+		// A secret()/config() marker is a deferred value, not an API — skip it, or
+		// `export const k = secret('K')` in index.ts would become a bogus HTTP namespace.
+		if (isManagedValue(value)) continue;
+
+		// Fallback: any exported function/object gets an ApiNamespace proxy.
+		if ((typeof value === 'function' || typeof value === 'object') && value !== null) {
+			lines.push(`export const ${name} = __BLOCKS_ApiNamespaceClient__('${name}');`);
+			namespaceNames.push(name);
+		}
+	}
+
+	// Emit generateClient — creates new ApiNamespaceClient instances with the given url
+	const nsEntries = namespaceNames.map((n) => `    ${n}: __BLOCKS_ApiNamespaceClient__('${n}', config),`).join('\n');
+	lines.push('');
+	lines.push(`export const generateClient = (config) => ({\n${nsEntries}\n});`);
+
+	const header = [
+		'// ============================================================',
+		'// AUTO-GENERATED FILE — DO NOT EDIT',
+		'//',
+		'// This file is generated by the Blocks dev server / build process.',
+		'// Any manual changes will be overwritten on the next build.',
+		'// ============================================================',
+	];
+
+	return [...header, '', ...imports, '', ...lines].join('\n');
 }
 
 /**
  * Generate client code and write it to the aws-blocks subpackage.
  */
 export async function writeClientCode(foundationPath: string, outputPath: string): Promise<void> {
-  const code = await generateClientCode(foundationPath);
-  mkdirSync(dirname(outputPath), { recursive: true });
-  writeFileSync(outputPath, code);
+	const code = await generateClientCode(foundationPath);
+	mkdirSync(dirname(outputPath), { recursive: true });
+	writeFileSync(outputPath, code);
 }

package/src/scripts/index.ts

@@ -1,22 +1,25 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-export { startDevServer, type DevServerOptions } from './dev-server.js';
-export { startSandbox, destroySandbox, type SandboxOptions } from './sandbox.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,
+	type BuildAndSendEventOptions,
+	buildAndSendEvent,
+	type CommandName,
+	type CommandState,
+	classifyError,
+	trackCommand,
 } from '../telemetry/index.js';
-export { telemetry, type TelemetryOptions } from './telemetry.js';
-export { getStackId, getSandboxId, getStackName } from './stack-id.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 { 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';

package/src/scripts/preflight-credentials.test.ts

@@ -0,0 +1,110 @@
+// 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' } as NodeJS.ProcessEnv;
+
+/** Build an Error with a specific `name`, as the AWS SDK throws. */
+function namedError(name: string, message = 'raw sdk detail'): Error {
+	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: string | undefined;
+		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: Error) => {
+				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: Error) => {
+				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: Error) => {
+				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/src/scripts/preflight-credentials.ts

@@ -0,0 +1,131 @@
+// 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: NodeJS.ProcessEnv = process.env): string | null {
+	return env.AWS_REGION || env.AWS_DEFAULT_REGION || 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>;
+
+/**
+ * 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: CredentialProbe = 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: string,
+	probe: CredentialProbe = stsProbe,
+	env: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+	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.',
+		);
+	}
+}