@aws/nx-plugin 0.76.0 → 0.78.0

package/LICENSE-THIRD-PARTY

@@ -3352,12 +3352,12 @@ SOFTWARE.
 
 ---
 
-The following software may be included in this product: @esbuild/linux-x64 (0.27.2)
+The following software may be included in this product: @esbuild/darwin-arm64 (0.27.2)
 This software contains the following license and notice below:
 
 MIT License
 
-Copyright (c) The maintainers of @esbuild/linux-x64 <https://github.com/evanw/esbuild#readme>
+Copyright (c) The maintainers of @esbuild/darwin-arm64 <https://github.com/evanw/esbuild#readme>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and 
 associated documentation files (the "Software"), to deal in the Software without restriction, including 
@@ -3376,12 +3376,12 @@ USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 ---
 
-The following software may be included in this product: @esbuild/linux-x64 (0.27.3)
+The following software may be included in this product: @esbuild/darwin-arm64 (0.27.3)
 This software contains the following license and notice below:
 
 MIT License
 
-Copyright (c) The maintainers of @esbuild/linux-x64 <https://github.com/evanw/esbuild#readme>
+Copyright (c) The maintainers of @esbuild/darwin-arm64 <https://github.com/evanw/esbuild#readme>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and 
 associated documentation files (the "Software"), to deal in the Software without restriction, including 
@@ -3903,7 +3903,7 @@ THE SOFTWARE.
 
 ---
 
-The following software may be included in this product: @modelcontextprotocol/sdk (1.26.0)
+The following software may be included in this product: @modelcontextprotocol/sdk (1.27.0)
 This software contains the following license and notice below:
 
 MIT License
@@ -4631,7 +4631,7 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 ---
 
-The following software may be included in this product: @nx/nx-linux-x64-gnu (22.5.1)
+The following software may be included in this product: @nx/nx-darwin-arm64 (22.5.1)
 This software contains the following license and notice below:
 
 (The MIT License)
@@ -5349,7 +5349,7 @@ THE SOFTWARE.
 
 ---
 
-The following software may be included in this product: @rollup/rollup-linux-x64-gnu (4.50.1)
+The following software may be included in this product: @rollup/rollup-darwin-arm64 (4.50.1)
 This software contains the following license and notice below:
 
 MIT License
@@ -5401,7 +5401,7 @@ SOFTWARE.
 
 ---
 
-The following software may be included in this product: @rspack/binding-linux-x64-gnu (1.6.8)
+The following software may be included in this product: @rspack/binding-darwin-arm64 (1.6.8)
 This software contains the following license and notice below:
 
 MIT License
@@ -8493,6 +8493,35 @@ SOFTWARE.
 
 ---
 
+The following software may be included in this product: balanced-match (4.0.4)
+This software contains the following license and notice below:
+
+(MIT)
+
+Original code Copyright Julian Gruber <julian@juliangruber.com>
+
+Port to TypeScript Copyright Isaac Z. Schlueter <i@izs.me>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
 The following software may be included in this product: base64-js (1.5.1)
 This software contains the following license and notice below:
 
@@ -8737,6 +8766,35 @@ SOFTWARE.
 
 ---
 
+The following software may be included in this product: brace-expansion (5.0.3)
+This software contains the following license and notice below:
+
+MIT License
+
+Copyright Julian Gruber <julian@juliangruber.com>
+
+TypeScript port Copyright Isaac Z. Schlueter <i@izs.me>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
 The following software may be included in this product: braces (3.0.3)
 This software contains the following license and notice below:
 
@@ -13107,6 +13165,34 @@ OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHE
 
 ---
 
+The following software may be included in this product: fsevents (2.3.3)
+This software contains the following license and notice below:
+
+MIT License
+-----------
+
+Copyright (C) 2010-2020 by Philipp Dunkel, Ben Noordhuis, Elan Shankar, Paul Miller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+---
+
 The following software may be included in this product: function-bind (1.1.2)
 This software contains the following license and notice below:
 
@@ -39041,7 +39127,7 @@ software or this license, under any kind of legal claim._**
 
 ---
 
-The following software may be included in this product: minimatch (10.1.2)
+The following software may be included in this product: minimatch (10.2.2)
 This software contains the following license and notice below:
 
 # Blue Oak Model License
@@ -39873,7 +39959,7 @@ defined by the Mozilla Public License, v. 2.0.
 
 ---
 
-The following software may be included in this product: lightningcss-linux-x64-gnu (1.30.2)
+The following software may be included in this product: lightningcss-darwin-arm64 (1.30.2)
 This software contains the following license and notice below:
 
 Mozilla Public License Version 2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/nx-plugin",
-  "version": "0.76.0",
+  "version": "0.78.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/nx-plugin-for-aws.git",
@@ -19,19 +19,19 @@
   },
   "generators": "./generators.json",
   "peerDependencies": {
-    "nx": "~22.5.0",
+    "nx": "~22.5.1",
     "prettier": "^3.8.1"
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^10.1.1",
     "@hey-api/openapi-ts": "0.64.13",
     "@iarna/toml": "^2.2.5",
-    "@modelcontextprotocol/sdk": "~1.26.0",
-    "@nx/devkit": "~22.5.0",
-    "@nx/eslint": "~22.5.0",
-    "@nx/js": "~22.5.0",
-    "@nx/react": "~22.5.0",
-    "@nx/vite": "~22.5.0",
+    "@modelcontextprotocol/sdk": "~1.27.0",
+    "@nx/devkit": "~22.5.1",
+    "@nx/eslint": "~22.5.1",
+    "@nx/js": "~22.5.1",
+    "@nx/react": "~22.5.1",
+    "@nx/vite": "~22.5.1",
     "@nxlv/python": "~22.1.0",
     "@phenomnomnominal/tsquery": "6.1.4",
     "enquirer": "^2.4.1",
@@ -42,7 +42,7 @@
     "lodash.orderby": "^4.6.0",
     "lodash.trim": "^4.5.1",
     "lodash.uniqby": "^4.7.0",
-    "minimatch": "^10.1.2",
+    "minimatch": "^10.2.1",
     "openapi-types": "^12.1.3",
     "pip-requirements-js": "^0.2.1",
     "typescript": "~5.9.3",

package/src/infra/app/__snapshots__/generator.spec.ts.snap

@@ -2,9 +2,9 @@
 
 exports[`infra generator > should add required dependencies to package.json > dependencies 1`] = `
 {
-  "aws-cdk": "2.1105.0",
+  "aws-cdk": "2.1106.0",
   "aws-cdk-lib": "2.238.0",
-  "constructs": "10.4.5",
+  "constructs": "10.5.0",
   "esbuild": "0.27.3",
   "source-map-support": "0.5.21",
 }
@@ -39,9 +39,9 @@ exports[`infra generator > should add required dependencies to package.json > de
 exports[`infra generator > should add required dependencies to package.json > package-json 1`] = `
 {
   "dependencies": {
-    "aws-cdk": "2.1105.0",
+    "aws-cdk": "2.1106.0",
     "aws-cdk-lib": "2.238.0",
-    "constructs": "10.4.5",
+    "constructs": "10.5.0",
     "esbuild": "0.27.3",
     "source-map-support": "0.5.21",
   },
@@ -84,7 +84,7 @@ exports[`infra generator > should configure Checkov target correctly > checkov-t
     "{workspaceRoot}/dist/{projectRoot}/cdk.out",
   ],
   "options": {
-    "command": "uvx checkov==3.2.501 --config-file {projectRoot}/checkov.yml --directory dist/{projectRoot}/cdk.out --framework cloudformation",
+    "command": "uvx checkov==3.2.505 --config-file {projectRoot}/checkov.yml --directory dist/{projectRoot}/cdk.out --framework cloudformation",
   },
   "outputs": [
     "{workspaceRoot}/dist/{projectRoot}/checkov",
@@ -177,7 +177,7 @@ exports[`infra generator > should configure project.json with correct targets >
         "{workspaceRoot}/dist/{projectRoot}/cdk.out",
       ],
       "options": {
-        "command": "uvx checkov==3.2.501 --config-file {projectRoot}/checkov.yml --directory dist/{projectRoot}/cdk.out --framework cloudformation",
+        "command": "uvx checkov==3.2.505 --config-file {projectRoot}/checkov.yml --directory dist/{projectRoot}/cdk.out --framework cloudformation",
       },
       "outputs": [
         "{workspaceRoot}/dist/{projectRoot}/checkov",
@@ -727,7 +727,7 @@ exports[`infra generator > should handle custom project names correctly > custom
         "{workspaceRoot}/dist/{projectRoot}/cdk.out",
       ],
       "options": {
-        "command": "uvx checkov==3.2.501 --config-file {projectRoot}/checkov.yml --directory dist/{projectRoot}/cdk.out --framework cloudformation",
+        "command": "uvx checkov==3.2.505 --config-file {projectRoot}/checkov.yml --directory dist/{projectRoot}/cdk.out --framework cloudformation",
       },
       "outputs": [
         "{workspaceRoot}/dist/{projectRoot}/checkov",
@@ -812,3 +812,374 @@ exports[`infra generator > should handle custom project names correctly > custom
   },
 }
 `;
+
+exports[`infra generator > with enableStageConfig > should snapshot generated infra-config src directory > packages/common/infra-config/src/index.ts 1`] = `
+"export * from './stages.types.js';
+export { default } from './stages.config.js';
+export { resolveStage } from './resolve-stage.js';
+"
+`;
+
+exports[`infra generator > with enableStageConfig > should snapshot generated infra-config src directory > packages/common/infra-config/src/resolve-stage.ts 1`] = `
+"import type { StageConfig, StagesConfig } from './stages.types.js';
+import stagesConfig from './stages.config.js';
+
+// Widen the narrow \`as const\` type to StagesConfig for dynamic key access
+const config: StagesConfig = stagesConfig;
+
+/**
+ * Resolves stage config for a given project and stage name.
+ * Project-specific fields take priority over shared ones.
+ *
+ * @param projectPath - Project path relative to workspace root (e.g., 'packages/infra')
+ * @param stageName - CDK stage name (e.g., 'my-app-dev')
+ * @returns Merged StageConfig or undefined if no config exists for this stage
+ */
+export function resolveStage(
+  projectPath: string,
+  stageName: string,
+): StageConfig | undefined {
+  const shared = config.shared?.stages?.[stageName];
+  const project = config.projects?.[projectPath]?.stages?.[stageName];
+  if (!shared && !project) return undefined;
+  return { ...shared, ...project } as StageConfig;
+}
+"
+`;
+
+exports[`infra generator > with enableStageConfig > should snapshot generated infra-config src directory > packages/common/infra-config/src/stages.config.ts 1`] = `
+"/**
+ * Stage configuration for CDK deployments.
+ *
+ * This file maps CDK stage names to their deployment settings. When you run
+ * \`npx nx run <project>:deploy <stage-name>/*\`, the infra-deploy script
+ * automatically resolves and applies the correct credentials.
+ *
+ * Project keys are the project path relative to the workspace root
+ * (e.g., 'packages/infra').
+ *
+ * Stage names must match the CDK stage identifiers defined in your main.ts —
+ * the first argument to \`new ApplicationStage(app, '<stage-name>', ...)\`.
+ * For example, if main.ts has \`new ApplicationStage(app, 'my-app-dev', ...)\`
+ * then the stage name here is 'my-app-dev'.
+ *
+ * We recommend committing this file so the team shares a single source of truth.
+ * If it contains personal profile names, you can add it to .gitignore instead.
+ */
+import type { StagesConfig } from './stages.types.js';
+
+export default {
+  projects: {
+    // Example: map stages for a specific infra project
+    // 'packages/infra': {
+    //   stages: {
+    //     'my-app-dev': {
+    //       credentials: { type: 'profile', profile: 'dev-account' },
+    //       region: 'us-east-1',
+    //       // account is optional — if omitted, CDK infers from the profile
+    //     },
+    //     'my-app-prod': {
+    //       credentials: { type: 'assumeRole', assumeRole: 'arn:aws:iam::123456789012:role/DeployRole' },
+    //       region: 'us-west-2',
+    //       account: '123456789012',
+    //     },
+    //   },
+    // },
+  },
+  shared: {
+    stages: {
+      // Example: shared sandbox stage available to all projects
+      // 'sandbox': {
+      //   credentials: { type: 'profile', profile: 'sandbox-profile' },
+      //   region: 'us-east-1',
+      // },
+    },
+  },
+} as const satisfies StagesConfig;
+"
+`;
+
+exports[`infra generator > with enableStageConfig > should snapshot generated infra-config src directory > packages/common/infra-config/src/stages.types.ts 1`] = `
+"/**
+ * Type definitions for stage and project configuration.
+ *
+ * These types are used by both stages.config.ts and the infra-deploy/
+ * infra-destroy scripts. They live in a shared package so any
+ * project in the workspace can import them.
+ */
+
+/** Use an AWS CLI profile from ~/.aws/config */
+export type ProfileCredentials = {
+  type: 'profile';
+  /** AWS CLI profile name */
+  profile: string;
+};
+
+/** Assume an IAM role via STS, optionally using a profile as the source credentials */
+export type AssumeRoleCredentials = {
+  type: 'assumeRole';
+  /** IAM Role ARN to assume */
+  assumeRole: string;
+  /** Optional: AWS CLI profile to use as source credentials for the AssumeRole call */
+  profile?: string;
+  /** Optional: External ID required by the role's trust policy */
+  externalId?: string;
+  /** Optional: Session duration in seconds (default: 3600). Increase for long deployments. */
+  sessionDuration?: number;
+};
+
+/**
+ * Credentials for deploying to a specific CDK stage.
+ * The \`type\` field determines which credential strategy is used.
+ */
+export type StageCredentials = ProfileCredentials | AssumeRoleCredentials;
+
+/**
+ * Configuration for a single CDK stage.
+ * Includes credentials, region, and optionally account.
+ */
+export type StageConfig = {
+  /** How to authenticate when deploying this stage */
+  credentials: StageCredentials;
+  /** AWS region for this stage (e.g., 'us-east-1') */
+  region: string;
+  /** AWS account ID. If omitted, CDK infers it from the active credentials. */
+  account?: string;
+};
+
+/**
+ * Configuration for a single infrastructure project.
+ * The key in the parent map is the project path relative to workspace root
+ * (e.g., 'packages/infra').
+ */
+export type ProjectConfig = {
+  /** Map of CDK stage names to their configuration */
+  stages: { [stageName: string]: StageConfig };
+};
+
+/** Top-level configuration mapping projects and stages to their settings. */
+export type StagesConfig = {
+  /** Project-specific config. Key is the project path relative to workspace root. */
+  projects?: { [projectPath: string]: ProjectConfig };
+  /** Shared stage config available to all projects. */
+  shared?: {
+    stages: { [stageName: string]: StageConfig };
+  };
+};
+"
+`;
+
+exports[`infra generator > with enableStageConfig > should snapshot generated scripts src directory > packages/common/scripts/src/index.ts 1`] = `
+"// Scripts (infra-deploy, infra-destroy) are the public interface of this package.
+"
+`;
+
+exports[`infra generator > with enableStageConfig > should snapshot generated scripts src directory > packages/common/scripts/src/infra-deploy.ts 1`] = `
+"import { run } from './stage-credentials/run.js';
+run('deploy');
+"
+`;
+
+exports[`infra generator > with enableStageConfig > should snapshot generated scripts src directory > packages/common/scripts/src/infra-destroy.ts 1`] = `
+"import { run } from './stage-credentials/run.js';
+run('destroy');
+"
+`;
+
+exports[`infra generator > with enableStageConfig > should snapshot generated scripts src directory > packages/common/scripts/src/stage-credentials/cdk-command.ts 1`] = `
+"/**
+ * Builds the CDK command as an array of arguments for spawnSync.
+ *
+ * Defaults to --require-approval=never (standard for local dev deploys).
+ * If the user explicitly passes --require-approval with any value, we
+ * respect their choice and don't add the default.
+ */
+export function buildCdkCommand(
+  action: string,
+  remainingArgs: string[],
+): string[] {
+  const hasRequireApproval = remainingArgs.some(
+    (a) => a === '--require-approval' || a.startsWith('--require-approval='),
+  );
+  return hasRequireApproval
+    ? ['cdk', action, ...remainingArgs]
+    : ['cdk', action, '--require-approval=never', ...remainingArgs];
+}
+"
+`;
+
+exports[`infra generator > with enableStageConfig > should snapshot generated scripts src directory > packages/common/scripts/src/stage-credentials/credentials.ts 1`] = `
+"import type { StageCredentials, StagesConfig } from ':proj/common-infra-config';
+
+/**
+ * Looks up credentials for a given project + stage combination.
+ *
+ * Lookup order:
+ *   1. Project-specific: config.projects[projectPath].stages[stageName].credentials
+ *   2. Shared:           config.shared.stages[stageName].credentials
+ *   3. No match:         returns undefined — caller falls back to env vars
+ */
+export function lookupCredentials(
+  config: StagesConfig | undefined,
+  projectPath: string,
+  stageName: string,
+): { credentials: StageCredentials | undefined; source: string } {
+  const projectCreds =
+    config?.projects?.[projectPath]?.stages?.[stageName]?.credentials;
+  if (projectCreds) {
+    return { credentials: projectCreds, source: 'project-specific' };
+  }
+
+  const sharedCreds = config?.shared?.stages?.[stageName]?.credentials;
+  if (sharedCreds) {
+    return { credentials: sharedCreds, source: 'shared' };
+  }
+
+  return { credentials: undefined, source: 'environment fallback' };
+}
+
+/**
+ * Builds a child process environment with the resolved credentials overlaid.
+ * Never modifies process.env — returns a new object.
+ */
+export async function buildChildEnv(
+  credentials: StageCredentials,
+  projectPath: string,
+): Promise<Record<string, string | undefined>> {
+  const env = { ...process.env };
+
+  switch (credentials.type) {
+    case 'profile': {
+      env.AWS_PROFILE = credentials.profile;
+      break;
+    }
+    case 'assumeRole': {
+      let STSClient: typeof import('@aws-sdk/client-sts').STSClient;
+      let AssumeRoleCommand: typeof import('@aws-sdk/client-sts').AssumeRoleCommand;
+      try {
+        ({ STSClient, AssumeRoleCommand } =
+          await import('@aws-sdk/client-sts'));
+      } catch {
+        console.error(
+          '[infra-deploy] Error: @aws-sdk/client-sts is required for assumeRole credentials but is not installed.',
+        );
+        console.error('[infra-deploy] Please install @aws-sdk/client-sts');
+        process.exit(1);
+      }
+
+      // If a source profile is specified, configure the STS client to use it
+      const stsClientOptions: Record<string, unknown> = {};
+      if (credentials.profile) {
+        const { fromIni } = await import('@aws-sdk/credential-providers');
+        stsClientOptions.credentials = fromIni({
+          profile: credentials.profile,
+        });
+      }
+
+      const response = await new STSClient(stsClientOptions).send(
+        new AssumeRoleCommand({
+          RoleArn: credentials.assumeRole,
+          RoleSessionName: \`infra-deploy-\${projectPath.replace(/\\//g, '-')}\`,
+          ...(credentials.externalId
+            ? { ExternalId: credentials.externalId }
+            : {}),
+          ...(credentials.sessionDuration
+            ? { DurationSeconds: credentials.sessionDuration }
+            : {}),
+        }),
+      );
+
+      env.AWS_ACCESS_KEY_ID = response.Credentials?.AccessKeyId;
+      env.AWS_SECRET_ACCESS_KEY = response.Credentials?.SecretAccessKey;
+      env.AWS_SESSION_TOKEN = response.Credentials?.SessionToken;
+      delete env.AWS_PROFILE;
+      break;
+    }
+  }
+
+  return env;
+}
+
+/** Human-readable description of credentials for logging */
+export function describeCredentials(creds: StageCredentials): string {
+  return creds.type === 'profile'
+    ? \`profile '\${creds.profile}'\`
+    : \`role '\${creds.assumeRole}'\`;
+}
+"
+`;
+
+exports[`infra generator > with enableStageConfig > should snapshot generated scripts src directory > packages/common/scripts/src/stage-credentials/run.ts 1`] = `
+"import { spawnSync } from 'child_process';
+import stagesConfig from ':proj/common-infra-config';
+import { parseStageName } from './stage-parser.js';
+import {
+  lookupCredentials,
+  buildChildEnv,
+  describeCredentials,
+} from './credentials.js';
+import { buildCdkCommand } from './cdk-command.js';
+
+const log = (msg: string) => console.error(\`[infra-deploy] \${msg}\`);
+
+export async function run(action: 'deploy' | 'destroy'): Promise<void> {
+  const [projectPath, ...remainingArgs] = process.argv.slice(2);
+
+  if (!projectPath) {
+    log(\`Usage: infra-\${action} <project-path> [stage/*] [cdk-args...]\`);
+    process.exit(1);
+  }
+
+  const stageName = parseStageName(remainingArgs[0]);
+  let childEnv: Record<string, string | undefined> = { ...process.env };
+
+  if (stageName) {
+    const { credentials, source } = lookupCredentials(
+      stagesConfig,
+      projectPath,
+      stageName,
+    );
+
+    if (credentials) {
+      log(
+        \`Using \${describeCredentials(credentials)} for '\${stageName}' (\${source})\`,
+      );
+      childEnv = await buildChildEnv(credentials, projectPath);
+    } else {
+      log(\`No credentials for '\${stageName}' — using environment\`);
+    }
+  } else {
+    log('No stage specified — using environment credentials');
+  }
+
+  // Run CDK from the project directory so it finds cdk.json
+  const cmd = buildCdkCommand(action, remainingArgs);
+  const { status } = spawnSync(cmd[0], cmd.slice(1), {
+    stdio: 'inherit',
+    env: childEnv,
+    cwd: projectPath,
+  });
+
+  process.exit(status ?? 1);
+}
+"
+`;
+
+exports[`infra generator > with enableStageConfig > should snapshot generated scripts src directory > packages/common/scripts/src/stage-credentials/stage-parser.ts 1`] = `
+"/**
+ * Extracts the CDK stage name from the first positional argument.
+ *
+ * Examples:
+ *   parseStageName('my-app-dev/*')  → 'my-app-dev'
+ *   parseStageName('my-app-dev')    → 'my-app-dev'
+ *   parseStageName('--verbose')     → undefined (flag, not a stage)
+ *   parseStageName(undefined)       → undefined
+ */
+export function parseStageName(
+  firstArg: string | undefined,
+): string | undefined {
+  if (!firstArg || firstArg.startsWith('-')) return undefined;
+  return firstArg.includes('/') ? firstArg.split('/')[0] : firstArg;
+}
+"
+`;

package/src/infra/app/files/app/src/main.ts.template

@@ -1,8 +1,23 @@
 import { ApplicationStage } from './stages/application-stage.js';
 import { App } from '<%= scopeAlias %>common-constructs';
-
+<% if (enableStageConfig) { %>import { resolveStage } from '<%= scopeAlias %>common-infra-config';
+<% } %>
 const app = new App();
+<% if (enableStageConfig) { %>
+// Stage configuration is defined in packages/common/infra-config/src/stages.config.ts
+// The project path '<%= dir %>' is used as the key in the config.
+// Project-specific settings override shared settings for the same stage name.
 
+// Sandbox stage — uses your CLI credentials by default.
+// Add an entry in stages.config.ts to configure specific credentials.
+const sandboxConfig = resolveStage('<%= dir %>', '<%= namespace %>-sandbox');
+new ApplicationStage(app, '<%= namespace %>-sandbox', {
+  env: {
+    account: sandboxConfig?.account ?? process.env.CDK_DEFAULT_ACCOUNT,
+    region: sandboxConfig?.region ?? process.env.CDK_DEFAULT_REGION,
+  },
+});
+<% } else { %>
 // Use this to deploy your own sandbox environment (assumes your CLI credentials)
 new ApplicationStage(app, '<%= namespace %>-sandbox', {
   env: {
@@ -10,5 +25,5 @@ new ApplicationStage(app, '<%= namespace %>-sandbox', {
     region: process.env.CDK_DEFAULT_REGION,
   },
 });
-
+<% } %>
 app.synth();