@aws/nx-plugin 1.0.0-rc.95 → 1.0.0-rc.97

package/src/mcp-server/server.js

@@ -7,6 +7,7 @@ import PackageJson from "../../package.json" with {
 };
 import { listGenerators } from "../utils/nx.js";
 import { addToExistingProjectTool } from "./tools/add-to-existing-project.js";
+import { addBestPracticesTool } from "./tools/best-practices.js";
 import { addCreateWorkspaceCommandTool } from "./tools/create-workspace-command.js";
 import { addGeneralGuidanceTool, TOOL_SELECTION_GUIDE } from "./tools/general-guidance.js";
 import { addGeneratorGuideTool } from "./tools/generator-guide.js";
@@ -31,6 +32,7 @@ ${TOOL_SELECTION_GUIDE}
 `
     });
     addGeneralGuidanceTool(server, generators);
+    addBestPracticesTool(server, generators);
     addCreateWorkspaceCommandTool(server);
     addListGeneratorsTool(server, generators);
     addGeneratorGuideTool(server, generators);

package/src/mcp-server/server.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../packages/nx-plugin/src/mcp-server/server.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport PackageJson from '../../package.json' with { type: 'json' };\nimport { listGenerators } from '../utils/nx.js';\nimport { addToExistingProjectTool } from './tools/add-to-existing-project.js';\nimport { addCreateWorkspaceCommandTool } from './tools/create-workspace-command.js';\nimport {\n  addGeneralGuidanceTool,\n  TOOL_SELECTION_GUIDE,\n} from './tools/general-guidance.js';\nimport { addGeneratorGuideTool } from './tools/generator-guide.js';\nimport { addListGeneratorsTool } from './tools/list-generators.js';\nimport { addUpgradeWorkspaceTool } from './tools/upgrade-workspace.js';\n\n/**\n * Create the MCP Server\n */\nexport const createServer = () => {\n  const generators = listGenerators();\n\n  const server = new McpServer(\n    {\n      name: 'nx-plugin-for-aws',\n      version: PackageJson.version,\n    },\n    {\n      instructions: `# Nx Plugin for AWS MCP Server\n\nThis server provides resources and tools for quickly scaffolding AWS projects within an Nx workspace (monorepo), using the Nx Plugin for AWS (@aws/nx-plugin).\n\nThe Nx Plugin for AWS provides \"generators\" to add projects or functionality to your workspace. Use this to build the foundations of any project you are building\non AWS, if the generators apply to your use case.\n\n${TOOL_SELECTION_GUIDE}\n`,\n    },\n  );\n\n  addGeneralGuidanceTool(server, generators);\n  addCreateWorkspaceCommandTool(server);\n  addListGeneratorsTool(server, generators);\n  addGeneratorGuideTool(server, generators);\n  addToExistingProjectTool(server, generators);\n  addUpgradeWorkspaceTool(server, generators);\n\n  return server;\n};\n"],"names":["McpServer","PackageJson","type","listGenerators","addToExistingProjectTool","addCreateWorkspaceCommandTool","addGeneralGuidanceTool","TOOL_SELECTION_GUIDE","addGeneratorGuideTool","addListGeneratorsTool","addUpgradeWorkspaceTool","createServer","generators","server","name","version","instructions"],"mappings":"AAAA;;;CAGC,GACD,SAASA,SAAS,QAAQ,0CAA0C;AACpE,OAAOC,iBAAiB,0BAA0B;IAAEC,MAAM;AAAO,EAAE;AACnE,SAASC,cAAc,QAAQ,iBAAiB;AAChD,SAASC,wBAAwB,QAAQ,qCAAqC;AAC9E,SAASC,6BAA6B,QAAQ,sCAAsC;AACpF,SACEC,sBAAsB,EACtBC,oBAAoB,QACf,8BAA8B;AACrC,SAASC,qBAAqB,QAAQ,6BAA6B;AACnE,SAASC,qBAAqB,QAAQ,6BAA6B;AACnE,SAASC,uBAAuB,QAAQ,+BAA+B;AAEvE;;CAEC,GACD,OAAO,MAAMC,eAAe;IAC1B,MAAMC,aAAaT;IAEnB,MAAMU,SAAS,IAAIb,UACjB;QACEc,MAAM;QACNC,SAASd,YAAYc,OAAO;IAC9B,GACA;QACEC,cAAc,CAAC;;;;;;;AAOrB,EAAET,qBAAqB;AACvB,CAAC;IACG;IAGFD,uBAAuBO,QAAQD;IAC/BP,8BAA8BQ;IAC9BJ,sBAAsBI,QAAQD;IAC9BJ,sBAAsBK,QAAQD;IAC9BR,yBAAyBS,QAAQD;IACjCF,wBAAwBG,QAAQD;IAEhC,OAAOC;AACT,EAAE"}
+{"version":3,"sources":["../../../../../packages/nx-plugin/src/mcp-server/server.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport PackageJson from '../../package.json' with { type: 'json' };\nimport { listGenerators } from '../utils/nx.js';\nimport { addToExistingProjectTool } from './tools/add-to-existing-project.js';\nimport { addBestPracticesTool } from './tools/best-practices.js';\nimport { addCreateWorkspaceCommandTool } from './tools/create-workspace-command.js';\nimport {\n  addGeneralGuidanceTool,\n  TOOL_SELECTION_GUIDE,\n} from './tools/general-guidance.js';\nimport { addGeneratorGuideTool } from './tools/generator-guide.js';\nimport { addListGeneratorsTool } from './tools/list-generators.js';\nimport { addUpgradeWorkspaceTool } from './tools/upgrade-workspace.js';\n\n/**\n * Create the MCP Server\n */\nexport const createServer = () => {\n  const generators = listGenerators();\n\n  const server = new McpServer(\n    {\n      name: 'nx-plugin-for-aws',\n      version: PackageJson.version,\n    },\n    {\n      instructions: `# Nx Plugin for AWS MCP Server\n\nThis server provides resources and tools for quickly scaffolding AWS projects within an Nx workspace (monorepo), using the Nx Plugin for AWS (@aws/nx-plugin).\n\nThe Nx Plugin for AWS provides \"generators\" to add projects or functionality to your workspace. Use this to build the foundations of any project you are building\non AWS, if the generators apply to your use case.\n\n${TOOL_SELECTION_GUIDE}\n`,\n    },\n  );\n\n  addGeneralGuidanceTool(server, generators);\n  addBestPracticesTool(server, generators);\n  addCreateWorkspaceCommandTool(server);\n  addListGeneratorsTool(server, generators);\n  addGeneratorGuideTool(server, generators);\n  addToExistingProjectTool(server, generators);\n  addUpgradeWorkspaceTool(server, generators);\n\n  return server;\n};\n"],"names":["McpServer","PackageJson","type","listGenerators","addToExistingProjectTool","addBestPracticesTool","addCreateWorkspaceCommandTool","addGeneralGuidanceTool","TOOL_SELECTION_GUIDE","addGeneratorGuideTool","addListGeneratorsTool","addUpgradeWorkspaceTool","createServer","generators","server","name","version","instructions"],"mappings":"AAAA;;;CAGC,GACD,SAASA,SAAS,QAAQ,0CAA0C;AACpE,OAAOC,iBAAiB,0BAA0B;IAAEC,MAAM;AAAO,EAAE;AACnE,SAASC,cAAc,QAAQ,iBAAiB;AAChD,SAASC,wBAAwB,QAAQ,qCAAqC;AAC9E,SAASC,oBAAoB,QAAQ,4BAA4B;AACjE,SAASC,6BAA6B,QAAQ,sCAAsC;AACpF,SACEC,sBAAsB,EACtBC,oBAAoB,QACf,8BAA8B;AACrC,SAASC,qBAAqB,QAAQ,6BAA6B;AACnE,SAASC,qBAAqB,QAAQ,6BAA6B;AACnE,SAASC,uBAAuB,QAAQ,+BAA+B;AAEvE;;CAEC,GACD,OAAO,MAAMC,eAAe;IAC1B,MAAMC,aAAaV;IAEnB,MAAMW,SAAS,IAAId,UACjB;QACEe,MAAM;QACNC,SAASf,YAAYe,OAAO;IAC9B,GACA;QACEC,cAAc,CAAC;;;;;;;AAOrB,EAAET,qBAAqB;AACvB,CAAC;IACG;IAGFD,uBAAuBO,QAAQD;IAC/BR,qBAAqBS,QAAQD;IAC7BP,8BAA8BQ;IAC9BJ,sBAAsBI,QAAQD;IAC9BJ,sBAAsBK,QAAQD;IAC9BT,yBAAyBU,QAAQD;IACjCF,wBAAwBG,QAAQD;IAEhC,OAAOC;AACT,EAAE"}

package/src/mcp-server/tools/best-practices.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { NxGeneratorInfo } from '../../utils/generators.js';
+/**
+ * Guide pages documenting behaviour that spans generators, so no single
+ * generator owns them and `generator-guide` never returns them. Each is
+ * described for the agent so it can pick the ones relevant to its task.
+ */
+export declare const BEST_PRACTICE_PAGES: {
+    readonly workspace: "Workspace layout, configuration and common commands";
+    readonly 'typescript-project': "Conventions for TypeScript projects";
+    readonly 'python-project': "Conventions for Python projects";
+    readonly security: "Security controls vended infrastructure carries, and the shared responsibility model";
+    readonly 'runtime-config': "How generated projects discover one another through AWS AppConfig";
+    readonly 'docker-bundling': "Building and deploying container images";
+    readonly 'local-development': "Running projects locally with the serve and dev targets";
+};
+export type BestPracticePage = keyof typeof BEST_PRACTICE_PAGES;
+export declare const BEST_PRACTICE_PAGE_NAMES: BestPracticePage[];
+/**
+ * Add a tool which serves the cross-cutting guide pages. Kept separate from
+ * `general-guidance` so an agent fetches only the pages its task needs rather
+ * than every page on every call.
+ */
+export declare const addBestPracticesTool: (server: McpServer, generators: NxGeneratorInfo[]) => void;

package/src/mcp-server/tools/best-practices.js

@@ -0,0 +1,43 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { z } from "zod";
+import { fetchGuidePages } from "../generator-info.js";
+import { PackageManagerSchema } from "../schema.js";
+/**
+ * Guide pages documenting behaviour that spans generators, so no single
+ * generator owns them and `generator-guide` never returns them. Each is
+ * described for the agent so it can pick the ones relevant to its task.
+ */ export const BEST_PRACTICE_PAGES = {
+    workspace: 'Workspace layout, configuration and common commands',
+    'typescript-project': 'Conventions for TypeScript projects',
+    'python-project': 'Conventions for Python projects',
+    security: 'Security controls vended infrastructure carries, and the shared responsibility model',
+    'runtime-config': 'How generated projects discover one another through AWS AppConfig',
+    'docker-bundling': 'Building and deploying container images',
+    'local-development': 'Running projects locally with the serve and dev targets'
+};
+export const BEST_PRACTICE_PAGE_NAMES = Object.keys(BEST_PRACTICE_PAGES);
+/**
+ * Add a tool which serves the cross-cutting guide pages. Kept separate from
+ * `general-guidance` so an agent fetches only the pages its task needs rather
+ * than every page on every call.
+ */ export const addBestPracticesTool = (server, generators)=>{
+    server.registerTool('best-practices', {
+        title: 'Best Practices',
+        description: 'Tool to retrieve guidance which spans generators, rather than applying to one in particular. ' + 'Request the pages relevant to your task:\n' + Object.entries(BEST_PRACTICE_PAGES).map(([page, description])=>`- \`${page}\`: ${description}`).join('\n'),
+        inputSchema: {
+            packageManager: PackageManagerSchema.optional(),
+            pages: z.array(z.enum(BEST_PRACTICE_PAGE_NAMES)).min(1).describe('The guide pages to retrieve.')
+        }
+    }, async ({ packageManager, pages })=>({
+            content: [
+                {
+                    type: 'text',
+                    text: await fetchGuidePages(pages, generators, packageManager)
+                }
+            ]
+        }));
+};
+
+//# sourceMappingURL=best-practices.js.map

package/src/mcp-server/tools/best-practices.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../packages/nx-plugin/src/mcp-server/tools/best-practices.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { z } from 'zod';\nimport type { NxGeneratorInfo } from '../../utils/generators.js';\nimport { fetchGuidePages } from '../generator-info.js';\nimport { PackageManagerSchema } from '../schema.js';\n\n/**\n * Guide pages documenting behaviour that spans generators, so no single\n * generator owns them and `generator-guide` never returns them. Each is\n * described for the agent so it can pick the ones relevant to its task.\n */\nexport const BEST_PRACTICE_PAGES = {\n  workspace: 'Workspace layout, configuration and common commands',\n  'typescript-project': 'Conventions for TypeScript projects',\n  'python-project': 'Conventions for Python projects',\n  security:\n    'Security controls vended infrastructure carries, and the shared responsibility model',\n  'runtime-config':\n    'How generated projects discover one another through AWS AppConfig',\n  'docker-bundling': 'Building and deploying container images',\n  'local-development':\n    'Running projects locally with the serve and dev targets',\n} as const satisfies Record<string, string>;\n\nexport type BestPracticePage = keyof typeof BEST_PRACTICE_PAGES;\n\nexport const BEST_PRACTICE_PAGE_NAMES = Object.keys(\n  BEST_PRACTICE_PAGES,\n) as BestPracticePage[];\n\n/**\n * Add a tool which serves the cross-cutting guide pages. Kept separate from\n * `general-guidance` so an agent fetches only the pages its task needs rather\n * than every page on every call.\n */\nexport const addBestPracticesTool = (\n  server: McpServer,\n  generators: NxGeneratorInfo[],\n) => {\n  server.registerTool(\n    'best-practices',\n    {\n      title: 'Best Practices',\n      description:\n        'Tool to retrieve guidance which spans generators, rather than applying to one in particular. ' +\n        'Request the pages relevant to your task:\\n' +\n        Object.entries(BEST_PRACTICE_PAGES)\n          .map(([page, description]) => `- \\`${page}\\`: ${description}`)\n          .join('\\n'),\n      inputSchema: {\n        packageManager: PackageManagerSchema.optional(),\n        pages: z\n          .array(z.enum(BEST_PRACTICE_PAGE_NAMES))\n          .min(1)\n          .describe('The guide pages to retrieve.'),\n      },\n    },\n    async ({ packageManager, pages }) => ({\n      content: [\n        {\n          type: 'text' as const,\n          text: await fetchGuidePages(pages, generators, packageManager),\n        },\n      ],\n    }),\n  );\n};\n"],"names":["z","fetchGuidePages","PackageManagerSchema","BEST_PRACTICE_PAGES","workspace","security","BEST_PRACTICE_PAGE_NAMES","Object","keys","addBestPracticesTool","server","generators","registerTool","title","description","entries","map","page","join","inputSchema","packageManager","optional","pages","array","enum","min","describe","content","type","text"],"mappings":"AAAA;;;CAGC,GAED,SAASA,CAAC,QAAQ,MAAM;AAExB,SAASC,eAAe,QAAQ,uBAAuB;AACvD,SAASC,oBAAoB,QAAQ,eAAe;AAEpD;;;;CAIC,GACD,OAAO,MAAMC,sBAAsB;IACjCC,WAAW;IACX,sBAAsB;IACtB,kBAAkB;IAClBC,UACE;IACF,kBACE;IACF,mBAAmB;IACnB,qBACE;AACJ,EAA4C;AAI5C,OAAO,MAAMC,2BAA2BC,OAAOC,IAAI,CACjDL,qBACsB;AAExB;;;;CAIC,GACD,OAAO,MAAMM,uBAAuB,CAClCC,QACAC;IAEAD,OAAOE,YAAY,CACjB,kBACA;QACEC,OAAO;QACPC,aACE,kGACA,+CACAP,OAAOQ,OAAO,CAACZ,qBACZa,GAAG,CAAC,CAAC,CAACC,MAAMH,YAAY,GAAK,CAAC,IAAI,EAAEG,KAAK,IAAI,EAAEH,aAAa,EAC5DI,IAAI,CAAC;QACVC,aAAa;YACXC,gBAAgBlB,qBAAqBmB,QAAQ;YAC7CC,OAAOtB,EACJuB,KAAK,CAACvB,EAAEwB,IAAI,CAAClB,2BACbmB,GAAG,CAAC,GACJC,QAAQ,CAAC;QACd;IACF,GACA,OAAO,EAAEN,cAAc,EAAEE,KAAK,EAAE,GAAM,CAAA;YACpCK,SAAS;gBACP;oBACEC,MAAM;oBACNC,MAAM,MAAM5B,gBAAgBqB,OAAOX,YAAYS;gBACjD;aACD;QACH,CAAA;AAEJ,EAAE"}

package/src/mcp-server/tools/general-guidance.d.ts

@@ -4,7 +4,7 @@
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { NxGeneratorInfo } from '../../utils/generators.js';
-export declare const TOOL_SELECTION_GUIDE = "## Tool Selection Guide\n\n- Use the `general-guidance` tool for guidance and best practices for working with Nx and the Nx Plugin for AWS.\n- Use the `create-workspace-command` tool to discover how to create a workspace to start a new project.\n- Use the `add-to-existing-project` tool when adding the plugin to an existing Nx workspace or non-Nx monorepo, or when troubleshooting configuration errors in such a workspace.\n- Use the `upgrade-workspace` tool when upgrading Nx or the Nx Plugin for AWS to a newer version.\n- Use the `list-generators` tool to discover the available generators and how to run them.\n- Use the `generator-guide` tool to retrieve detailed information about a specific generator.";
+export declare const TOOL_SELECTION_GUIDE = "## Tool Selection Guide\n\n- Use the `general-guidance` tool for guidance and best practices for working with Nx and the Nx Plugin for AWS.\n- Use the `best-practices` tool for guidance which spans generators rather than applying to one in particular, such as workspace layout, security, runtime configuration, container builds and local development.\n- Use the `create-workspace-command` tool to discover how to create a workspace to start a new project.\n- Use the `add-to-existing-project` tool when adding the plugin to an existing Nx workspace or non-Nx monorepo, or when troubleshooting configuration errors in such a workspace.\n- Use the `upgrade-workspace` tool when upgrading Nx or the Nx Plugin for AWS to a newer version.\n- Use the `list-generators` tool to discover the available generators and how to run them.\n- Use the `generator-guide` tool to retrieve detailed information about a specific generator.";
 /**
  * Add a tool which provides general guidance for using Nx and the Nx Plugin for AWS
  */

package/src/mcp-server/tools/general-guidance.js

@@ -4,9 +4,20 @@
  */ import { IAC_PROVIDERS } from "../../utils/iac-providers.js";
 import { buildNxCommand, fetchGuidePages } from "../generator-info.js";
 import { PACKAGE_MANAGERS } from "../schema.js";
+import { BEST_PRACTICE_PAGE_NAMES } from "./best-practices.js";
+/**
+ * The cross-cutting pages every agent needs regardless of task, inlined here
+ * so a workspace's conventions land without a second tool call. The rest are
+ * served on demand by `best-practices`.
+ */ const GENERAL_GUIDANCE_PAGES = [
+    'workspace',
+    'typescript-project',
+    'python-project'
+];
 export const TOOL_SELECTION_GUIDE = `## Tool Selection Guide
 
 - Use the \`general-guidance\` tool for guidance and best practices for working with Nx and the Nx Plugin for AWS.
+- Use the \`best-practices\` tool for guidance which spans generators rather than applying to one in particular, such as workspace layout, security, runtime configuration, container builds and local development.
 - Use the \`create-workspace-command\` tool to discover how to create a workspace to start a new project.
 - Use the \`add-to-existing-project\` tool when adding the plugin to an existing Nx workspace or non-Nx monorepo, or when troubleshooting configuration errors in such a workspace.
 - Use the \`upgrade-workspace\` tool when upgrading Nx or the Nx Plugin for AWS to a newer version.
@@ -86,12 +97,10 @@ ${PACKAGE_MANAGERS.map((pm)=>`  \`\`\`bash
 
 ## Detailed Guides
 
-Please refer to the below documentation for important details regarding workspaces and working with TypeScript or Python projects.
+Please refer to the below documentation for important details regarding workspaces and working with TypeScript or Python projects. Use the \`best-practices\` tool for the remaining cross-cutting guides (${BEST_PRACTICE_PAGE_NAMES.filter((p)=>!GENERAL_GUIDANCE_PAGES.includes(p)).map((p)=>`\`${p}\``).join(', ')}).
 
 ${await fetchGuidePages([
-                        'workspace',
-                        'typescript-project',
-                        'python-project'
+                        ...GENERAL_GUIDANCE_PAGES
                     ], generators)}
 
     `

package/src/mcp-server/tools/general-guidance.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../packages/nx-plugin/src/mcp-server/tools/general-guidance.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport type { NxGeneratorInfo } from '../../utils/generators.js';\nimport { IAC_PROVIDERS } from '../../utils/iac-providers.js';\nimport { buildNxCommand, fetchGuidePages } from '../generator-info.js';\nimport { PACKAGE_MANAGERS } from '../schema.js';\n\nexport const TOOL_SELECTION_GUIDE = `## Tool Selection Guide\n\n- Use the \\`general-guidance\\` tool for guidance and best practices for working with Nx and the Nx Plugin for AWS.\n- Use the \\`create-workspace-command\\` tool to discover how to create a workspace to start a new project.\n- Use the \\`add-to-existing-project\\` tool when adding the plugin to an existing Nx workspace or non-Nx monorepo, or when troubleshooting configuration errors in such a workspace.\n- Use the \\`upgrade-workspace\\` tool when upgrading Nx or the Nx Plugin for AWS to a newer version.\n- Use the \\`list-generators\\` tool to discover the available generators and how to run them.\n- Use the \\`generator-guide\\` tool to retrieve detailed information about a specific generator.`;\n\n/**\n * Add a tool which provides general guidance for using Nx and the Nx Plugin for AWS\n */\nexport const addGeneralGuidanceTool = (\n  server: McpServer,\n  generators: NxGeneratorInfo[],\n) => {\n  server.registerTool(\n    'general-guidance',\n    {\n      title: 'General Guidance',\n      description:\n        'Tool for guidance and best practices for working with Nx and the Nx Plugin for AWS',\n    },\n    async () => ({\n      content: [\n        {\n          type: 'text' as const,\n          text: `# Nx Plugin for AWS Guidance\n\n${TOOL_SELECTION_GUIDE}\n\n## Getting Started\n\n- Choose a package manager first. You can choose between ${PACKAGE_MANAGERS.join(', ')}. It's recommended to use \"pnpm\" if the user has no preference\n- Choose an infrastructure as code (IaC) provider next. You can choose between ${IAC_PROVIDERS.join(', ')}. It's recommended to use CDK if the user has no preference\n- Next, you must create an Nx workspace. Use the \\`create-workspace-command\\` tool for more details, and provide it with your chosen package manager\n- After this, you can start scaffolding the main components of your application using generators. Use the \\`list-generators\\` tool to discover available generators, and the \\`generator-guide\\` tool for more detailed information about a specific generator\n\n## Nx Primer\n\n- Prefix nx commands with the appropriate prefix for your package manager, for example:\n${PACKAGE_MANAGERS.map((pm) => buildNxCommand('<options>', pm)).join(' - \\n')}\n- Each project in your workspace has a file named \\`project.json\\` which contains important project information such as its name, and defines the \"targets\" which can be run for that project, for example building or testing the project\n- Use the command \\`nx reset\\` to reset the Nx daemon when unexpected issues arise\n- After adding dependencies between TypeScript projects, use \\`nx sync\\` to ensure project references are set up correctly\n\n## General Instructions\n\n- Each project declares the third-party runtime dependencies its source imports in its own \\`package.json\\`; shared build/test tooling (test runners, bundlers, etc.) is declared in the root \\`package.json\\` \\`devDependencies\\`. Versions follow a single version policy, recorded in the package manager's dependency catalog where supported (referenced as \\`catalog:\\`). Install with the appropriate command for your package manager:\n  - Add a project runtime dependency: \\`pnpm add <package> --filter <project>\\` / \\`yarn workspace <project> add <package>\\` / \\`npm install <package> -w <project>\\` / \\`bun add <package> --cwd <project-directory>\\`\n  - Add a shared dev tool at the root: \\`pnpm add -Dw <package>\\` / \\`yarn add -D <package>\\` / \\`npm install --legacy-peer-deps -D <package>\\` / \\`bun install -D <package>\\`\n- The \\`noUndeclaredDependencies\\` lint rule enforces that a project's source only imports packages declared in its own \\`package.json\\`\n- Projects in the same workspace can import one another directly by package name (eg \\`@workspace-name/project-name\\`) without declaring a dependency in \\`package.json\\` — TypeScript path aliases in \\`tsconfig.base.json\\` resolve these imports\n- When specifying project names as arguments to generators, prefer the _fully qualified_ project name, for example \\`@workspace-name/project-name\\`. Check the \\`project.json\\` file for the specific package to find its fully qualified name\n- When no generator exists for a specific framework required, use the base \\`ts#project\\` and \\`py#project\\` generators and build on top.\n- Leave the \\`--infra\\` option at its default value unless the user has explicitly instructed otherwise. Generators choose a sensible default type of infrastructure to deploy the project with, so only override \\`--infra\\` when the user has specified a particular requirement.\n\n## Useful Commands\n\n- Fix lint issues with \\`nx run-many --target lint --configuration=fix --all --output-style=stream\\`\n- Build all projects with \\`nx run-many --target build --all --output-style=stream\\`\n- Prefer importing the CDK constructs vended by generators in \\`packages/common/constructs\\` over writing your own\n\n## Best Practices\n\n- After running a generator, use the \\`nx show projects\\` command to check which projects have been added (if any)\n- Carefully examine the files that have been generated and always refer back to the generator guide when working in a generated project\n- Generate all projects into the \\`packages/\\` directory\n- After making changes to your projects, fix linting issues, then run a full build\n- When it's time to start testing a project, suggest to the user that infrastructure is deployed to AWS. For websites, if a runtime-config.json is needed, use the load-runtime-config target after a deployment to point a local website at a sandbox stack.\n- For CDK infrastructure projects, deploy the sandbox stage with the \\`deploy-sandbox\\` target (eg \\`nx deploy-sandbox infra\\`) rather than passing a stage pattern to \\`deploy\\` — it already targets the sandbox stage declared in \\`main.ts\\`. Likewise \\`destroy-sandbox\\` tears that stage back down.\n\n## Batching Generators\n\nWhen scaffolding several projects in one go, chain generators to avoid a slow dependency install after every generator:\n\n- **Chain generators** with \\`&&\\` in a single command. Pass \\`--prefer-install-dependencies=false\\` on each generator except the last so dependencies install once at the end, for example:\n\n${PACKAGE_MANAGERS.map(\n  (pm) => `  \\`\\`\\`bash\n  ${buildNxCommand('g @aws/nx-plugin:ts#trpc-api --no-interactive --name=my-app-api --auth=iam --prefer-install-dependencies=false', pm)} && \\\\\n    ${buildNxCommand('g @aws/nx-plugin:ts#react-website --no-interactive --name=my-app-website --prefer-install-dependencies=false', pm)} && \\\\\n    ${buildNxCommand('g @aws/nx-plugin:connection --no-interactive --sourceProject=@my-app/my-app-website --targetProject=@my-app/my-app-api --prefer-install-dependencies=false', pm)} && \\\\\n    ${buildNxCommand('g @aws/nx-plugin:ts#infra --no-interactive --name=infra', pm)} && \\\\\n    ${buildNxCommand('sync', pm)}\n  \\`\\`\\``,\n).join('\\n')}\n\n- **\\`--prefer-install-dependencies=false\\`** asks a generator to defer its dependency install so the batch installs once at the end (the final generator above omits the flag and installs everything).\n- **\\`nx sync\\`** is required before building — generators modify TypeScript project references.\n\n## Detailed Guides\n\nPlease refer to the below documentation for important details regarding workspaces and working with TypeScript or Python projects.\n\n${await fetchGuidePages(['workspace', 'typescript-project', 'python-project'], generators)}\n\n    `,\n        },\n      ],\n    }),\n  );\n};\n"],"names":["IAC_PROVIDERS","buildNxCommand","fetchGuidePages","PACKAGE_MANAGERS","TOOL_SELECTION_GUIDE","addGeneralGuidanceTool","server","generators","registerTool","title","description","content","type","text","join","map","pm"],"mappings":"AAAA;;;CAGC,GAGD,SAASA,aAAa,QAAQ,+BAA+B;AAC7D,SAASC,cAAc,EAAEC,eAAe,QAAQ,uBAAuB;AACvE,SAASC,gBAAgB,QAAQ,eAAe;AAEhD,OAAO,MAAMC,uBAAuB,CAAC;;;;;;;+FAO0D,CAAC,CAAC;AAEjG;;CAEC,GACD,OAAO,MAAMC,yBAAyB,CACpCC,QACAC;IAEAD,OAAOE,YAAY,CACjB,oBACA;QACEC,OAAO;QACPC,aACE;IACJ,GACA,UAAa,CAAA;YACXC,SAAS;gBACP;oBACEC,MAAM;oBACNC,MAAM,CAAC;;AAEjB,EAAET,qBAAqB;;;;yDAIkC,EAAED,iBAAiBW,IAAI,CAAC,MAAM;+EACR,EAAEd,cAAcc,IAAI,CAAC,MAAM;;;;;;;AAO1G,EAAEX,iBAAiBY,GAAG,CAAC,CAACC,KAAOf,eAAe,aAAae,KAAKF,IAAI,CAAC,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqC9E,EAAEX,iBAAiBY,GAAG,CACpB,CAACC,KAAO,CAAC;EACT,EAAEf,eAAe,kHAAkHe,IAAI;IACrI,EAAEf,eAAe,gHAAgHe,IAAI;IACrI,EAAEf,eAAe,8JAA8Je,IAAI;IACnL,EAAEf,eAAe,2DAA2De,IAAI;IAChF,EAAEf,eAAe,QAAQe,IAAI;QACzB,CAAC,EACPF,IAAI,CAAC,MAAM;;;;;;;;;AASb,EAAE,MAAMZ,gBAAgB;wBAAC;wBAAa;wBAAsB;qBAAiB,EAAEK,YAAY;;IAEvF,CAAC;gBACG;aACD;QACH,CAAA;AAEJ,EAAE"}
+{"version":3,"sources":["../../../../../../packages/nx-plugin/src/mcp-server/tools/general-guidance.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport type { NxGeneratorInfo } from '../../utils/generators.js';\nimport { IAC_PROVIDERS } from '../../utils/iac-providers.js';\nimport { buildNxCommand, fetchGuidePages } from '../generator-info.js';\nimport { PACKAGE_MANAGERS } from '../schema.js';\nimport { BEST_PRACTICE_PAGE_NAMES } from './best-practices.js';\n\n/**\n * The cross-cutting pages every agent needs regardless of task, inlined here\n * so a workspace's conventions land without a second tool call. The rest are\n * served on demand by `best-practices`.\n */\nconst GENERAL_GUIDANCE_PAGES = [\n  'workspace',\n  'typescript-project',\n  'python-project',\n] as const;\n\nexport const TOOL_SELECTION_GUIDE = `## Tool Selection Guide\n\n- Use the \\`general-guidance\\` tool for guidance and best practices for working with Nx and the Nx Plugin for AWS.\n- Use the \\`best-practices\\` tool for guidance which spans generators rather than applying to one in particular, such as workspace layout, security, runtime configuration, container builds and local development.\n- Use the \\`create-workspace-command\\` tool to discover how to create a workspace to start a new project.\n- Use the \\`add-to-existing-project\\` tool when adding the plugin to an existing Nx workspace or non-Nx monorepo, or when troubleshooting configuration errors in such a workspace.\n- Use the \\`upgrade-workspace\\` tool when upgrading Nx or the Nx Plugin for AWS to a newer version.\n- Use the \\`list-generators\\` tool to discover the available generators and how to run them.\n- Use the \\`generator-guide\\` tool to retrieve detailed information about a specific generator.`;\n\n/**\n * Add a tool which provides general guidance for using Nx and the Nx Plugin for AWS\n */\nexport const addGeneralGuidanceTool = (\n  server: McpServer,\n  generators: NxGeneratorInfo[],\n) => {\n  server.registerTool(\n    'general-guidance',\n    {\n      title: 'General Guidance',\n      description:\n        'Tool for guidance and best practices for working with Nx and the Nx Plugin for AWS',\n    },\n    async () => ({\n      content: [\n        {\n          type: 'text' as const,\n          text: `# Nx Plugin for AWS Guidance\n\n${TOOL_SELECTION_GUIDE}\n\n## Getting Started\n\n- Choose a package manager first. You can choose between ${PACKAGE_MANAGERS.join(', ')}. It's recommended to use \"pnpm\" if the user has no preference\n- Choose an infrastructure as code (IaC) provider next. You can choose between ${IAC_PROVIDERS.join(', ')}. It's recommended to use CDK if the user has no preference\n- Next, you must create an Nx workspace. Use the \\`create-workspace-command\\` tool for more details, and provide it with your chosen package manager\n- After this, you can start scaffolding the main components of your application using generators. Use the \\`list-generators\\` tool to discover available generators, and the \\`generator-guide\\` tool for more detailed information about a specific generator\n\n## Nx Primer\n\n- Prefix nx commands with the appropriate prefix for your package manager, for example:\n${PACKAGE_MANAGERS.map((pm) => buildNxCommand('<options>', pm)).join(' - \\n')}\n- Each project in your workspace has a file named \\`project.json\\` which contains important project information such as its name, and defines the \"targets\" which can be run for that project, for example building or testing the project\n- Use the command \\`nx reset\\` to reset the Nx daemon when unexpected issues arise\n- After adding dependencies between TypeScript projects, use \\`nx sync\\` to ensure project references are set up correctly\n\n## General Instructions\n\n- Each project declares the third-party runtime dependencies its source imports in its own \\`package.json\\`; shared build/test tooling (test runners, bundlers, etc.) is declared in the root \\`package.json\\` \\`devDependencies\\`. Versions follow a single version policy, recorded in the package manager's dependency catalog where supported (referenced as \\`catalog:\\`). Install with the appropriate command for your package manager:\n  - Add a project runtime dependency: \\`pnpm add <package> --filter <project>\\` / \\`yarn workspace <project> add <package>\\` / \\`npm install <package> -w <project>\\` / \\`bun add <package> --cwd <project-directory>\\`\n  - Add a shared dev tool at the root: \\`pnpm add -Dw <package>\\` / \\`yarn add -D <package>\\` / \\`npm install --legacy-peer-deps -D <package>\\` / \\`bun install -D <package>\\`\n- The \\`noUndeclaredDependencies\\` lint rule enforces that a project's source only imports packages declared in its own \\`package.json\\`\n- Projects in the same workspace can import one another directly by package name (eg \\`@workspace-name/project-name\\`) without declaring a dependency in \\`package.json\\` — TypeScript path aliases in \\`tsconfig.base.json\\` resolve these imports\n- When specifying project names as arguments to generators, prefer the _fully qualified_ project name, for example \\`@workspace-name/project-name\\`. Check the \\`project.json\\` file for the specific package to find its fully qualified name\n- When no generator exists for a specific framework required, use the base \\`ts#project\\` and \\`py#project\\` generators and build on top.\n- Leave the \\`--infra\\` option at its default value unless the user has explicitly instructed otherwise. Generators choose a sensible default type of infrastructure to deploy the project with, so only override \\`--infra\\` when the user has specified a particular requirement.\n\n## Useful Commands\n\n- Fix lint issues with \\`nx run-many --target lint --configuration=fix --all --output-style=stream\\`\n- Build all projects with \\`nx run-many --target build --all --output-style=stream\\`\n- Prefer importing the CDK constructs vended by generators in \\`packages/common/constructs\\` over writing your own\n\n## Best Practices\n\n- After running a generator, use the \\`nx show projects\\` command to check which projects have been added (if any)\n- Carefully examine the files that have been generated and always refer back to the generator guide when working in a generated project\n- Generate all projects into the \\`packages/\\` directory\n- After making changes to your projects, fix linting issues, then run a full build\n- When it's time to start testing a project, suggest to the user that infrastructure is deployed to AWS. For websites, if a runtime-config.json is needed, use the load-runtime-config target after a deployment to point a local website at a sandbox stack.\n- For CDK infrastructure projects, deploy the sandbox stage with the \\`deploy-sandbox\\` target (eg \\`nx deploy-sandbox infra\\`) rather than passing a stage pattern to \\`deploy\\` — it already targets the sandbox stage declared in \\`main.ts\\`. Likewise \\`destroy-sandbox\\` tears that stage back down.\n\n## Batching Generators\n\nWhen scaffolding several projects in one go, chain generators to avoid a slow dependency install after every generator:\n\n- **Chain generators** with \\`&&\\` in a single command. Pass \\`--prefer-install-dependencies=false\\` on each generator except the last so dependencies install once at the end, for example:\n\n${PACKAGE_MANAGERS.map(\n  (pm) => `  \\`\\`\\`bash\n  ${buildNxCommand('g @aws/nx-plugin:ts#trpc-api --no-interactive --name=my-app-api --auth=iam --prefer-install-dependencies=false', pm)} && \\\\\n    ${buildNxCommand('g @aws/nx-plugin:ts#react-website --no-interactive --name=my-app-website --prefer-install-dependencies=false', pm)} && \\\\\n    ${buildNxCommand('g @aws/nx-plugin:connection --no-interactive --sourceProject=@my-app/my-app-website --targetProject=@my-app/my-app-api --prefer-install-dependencies=false', pm)} && \\\\\n    ${buildNxCommand('g @aws/nx-plugin:ts#infra --no-interactive --name=infra', pm)} && \\\\\n    ${buildNxCommand('sync', pm)}\n  \\`\\`\\``,\n).join('\\n')}\n\n- **\\`--prefer-install-dependencies=false\\`** asks a generator to defer its dependency install so the batch installs once at the end (the final generator above omits the flag and installs everything).\n- **\\`nx sync\\`** is required before building — generators modify TypeScript project references.\n\n## Detailed Guides\n\nPlease refer to the below documentation for important details regarding workspaces and working with TypeScript or Python projects. Use the \\`best-practices\\` tool for the remaining cross-cutting guides (${BEST_PRACTICE_PAGE_NAMES.filter(\n            (p) => !GENERAL_GUIDANCE_PAGES.includes(p as never),\n          )\n            .map((p) => `\\`${p}\\``)\n            .join(', ')}).\n\n${await fetchGuidePages([...GENERAL_GUIDANCE_PAGES], generators)}\n\n    `,\n        },\n      ],\n    }),\n  );\n};\n"],"names":["IAC_PROVIDERS","buildNxCommand","fetchGuidePages","PACKAGE_MANAGERS","BEST_PRACTICE_PAGE_NAMES","GENERAL_GUIDANCE_PAGES","TOOL_SELECTION_GUIDE","addGeneralGuidanceTool","server","generators","registerTool","title","description","content","type","text","join","map","pm","filter","p","includes"],"mappings":"AAAA;;;CAGC,GAGD,SAASA,aAAa,QAAQ,+BAA+B;AAC7D,SAASC,cAAc,EAAEC,eAAe,QAAQ,uBAAuB;AACvE,SAASC,gBAAgB,QAAQ,eAAe;AAChD,SAASC,wBAAwB,QAAQ,sBAAsB;AAE/D;;;;CAIC,GACD,MAAMC,yBAAyB;IAC7B;IACA;IACA;CACD;AAED,OAAO,MAAMC,uBAAuB,CAAC;;;;;;;;+FAQ0D,CAAC,CAAC;AAEjG;;CAEC,GACD,OAAO,MAAMC,yBAAyB,CACpCC,QACAC;IAEAD,OAAOE,YAAY,CACjB,oBACA;QACEC,OAAO;QACPC,aACE;IACJ,GACA,UAAa,CAAA;YACXC,SAAS;gBACP;oBACEC,MAAM;oBACNC,MAAM,CAAC;;AAEjB,EAAET,qBAAqB;;;;yDAIkC,EAAEH,iBAAiBa,IAAI,CAAC,MAAM;+EACR,EAAEhB,cAAcgB,IAAI,CAAC,MAAM;;;;;;;AAO1G,EAAEb,iBAAiBc,GAAG,CAAC,CAACC,KAAOjB,eAAe,aAAaiB,KAAKF,IAAI,CAAC,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqC9E,EAAEb,iBAAiBc,GAAG,CACpB,CAACC,KAAO,CAAC;EACT,EAAEjB,eAAe,kHAAkHiB,IAAI;IACrI,EAAEjB,eAAe,gHAAgHiB,IAAI;IACrI,EAAEjB,eAAe,8JAA8JiB,IAAI;IACnL,EAAEjB,eAAe,2DAA2DiB,IAAI;IAChF,EAAEjB,eAAe,QAAQiB,IAAI;QACzB,CAAC,EACPF,IAAI,CAAC,MAAM;;;;;;;2MAO8L,EAAEZ,yBAAyBe,MAAM,CAChO,CAACC,IAAM,CAACf,uBAAuBgB,QAAQ,CAACD,IAEvCH,GAAG,CAAC,CAACG,IAAM,CAAC,EAAE,EAAEA,EAAE,EAAE,CAAC,EACrBJ,IAAI,CAAC,MAAM;;AAExB,EAAE,MAAMd,gBAAgB;2BAAIG;qBAAuB,EAAEI,YAAY;;IAE7D,CAAC;gBACG;aACD;QACH,CAAA;AAEJ,EAAE"}

package/src/migrations/latest/checkov-scan-cache-inputs/metadata.json

@@ -0,0 +1,3 @@
+{
+  "description": "Scope the CDK infrastructure checkov target's cache inputs so the security scan cannot serve a stale pass"
+}

package/src/migrations/latest/checkov-scan-cache-inputs/migration.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type MigrationReturnObject, type Tree } from '@nx/devkit';
+export default function migration(tree: Tree): Promise<MigrationReturnObject>;

package/src/migrations/latest/checkov-scan-cache-inputs/migration.js

@@ -0,0 +1,58 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { getProjects, updateProjectConfiguration } from "@nx/devkit";
+import { INFRA_APP_GENERATOR_INFO } from "../../../infra/app/generator.js";
+import { formatFilesInSubtree } from "../../../utils/format.js";
+/**
+ * Point the CDK infrastructure `checkov` target's cache inputs at the project
+ * rather than at the synth output directory.
+ *
+ * The target declared `["{workspaceRoot}/dist/{projectRoot}/cdk.out"]`, a
+ * fileset input. Nx resolves a fileset against the files it tracks, and `dist`
+ * is gitignored — so the input matched nothing and hashed to a constant. Once
+ * the scan had been cached, every later run was a hit: adding a non-compliant
+ * resource to a stack left `build` reporting success, and restored a
+ * `checkov_report.json` recording zero resources scanned.
+ *
+ * `["default"]` is what its `synth` sibling declares. It covers the project's
+ * own sources and carries the transitive `dependentTasksOutputFiles` entry from
+ * `nx.json`, which Nx resolves against the upstream `synth` task — so the hash
+ * follows the template the scan actually reads.
+ */ const CHECKOV_TARGET = 'checkov';
+/** The inputs the pre-fix generator declared, replaced in place. */ const VENDED_INPUTS = [
+    '{workspaceRoot}/dist/{projectRoot}/cdk.out'
+];
+/** The inputs the generator declares now, matching the `synth` sibling. */ const FIXED_INPUTS = [
+    'default'
+];
+const divergedMessage = (projectName)=>`${projectName}:${CHECKOV_TARGET}: its \`inputs\` have diverged from the generated shape - left untouched. Confirm they cover the synthesized template the scan reads: an input pointed only at \`dist\` matches no tracked file, so the scan can report a cached pass on infrastructure it never scanned.`;
+/** Whether a target's inputs are exactly the ones the generator vended. */ const hasVendedInputs = (target)=>Array.isArray(target.inputs) && target.inputs.length === VENDED_INPUTS.length && target.inputs.every((input, index)=>input === VENDED_INPUTS[index]);
+export default async function migration(tree) {
+    const nextSteps = [];
+    for (const [projectName, project] of getProjects(tree)){
+        const generator = project.metadata?.generator;
+        if (generator !== INFRA_APP_GENERATOR_INFO.id) continue;
+        const target = project.targets?.[CHECKOV_TARGET];
+        if (!target) continue;
+        // A target already declaring the fixed inputs needs nothing, which also
+        // makes a re-run — and a project generated after the fix — a no-op.
+        if (Array.isArray(target.inputs) && target.inputs.length === FIXED_INPUTS.length && target.inputs.every((input, index)=>input === FIXED_INPUTS[index])) {
+            continue;
+        }
+        if (!hasVendedInputs(target)) {
+            nextSteps.push(divergedMessage(projectName));
+            continue;
+        }
+        target.inputs = [
+            ...FIXED_INPUTS
+        ];
+        updateProjectConfiguration(tree, projectName, project);
+    }
+    await formatFilesInSubtree(tree);
+    return {
+        nextSteps
+    };
+}
+
+//# sourceMappingURL=migration.js.map

package/src/migrations/latest/checkov-scan-cache-inputs/migration.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../packages/nx-plugin/src/migrations/latest/checkov-scan-cache-inputs/migration.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  getProjects,\n  type MigrationReturnObject,\n  type ProjectConfiguration,\n  type TargetConfiguration,\n  type Tree,\n  updateProjectConfiguration,\n} from '@nx/devkit';\nimport { INFRA_APP_GENERATOR_INFO } from '../../../infra/app/generator.js';\nimport { formatFilesInSubtree } from '../../../utils/format.js';\n\n/**\n * Point the CDK infrastructure `checkov` target's cache inputs at the project\n * rather than at the synth output directory.\n *\n * The target declared `[\"{workspaceRoot}/dist/{projectRoot}/cdk.out\"]`, a\n * fileset input. Nx resolves a fileset against the files it tracks, and `dist`\n * is gitignored — so the input matched nothing and hashed to a constant. Once\n * the scan had been cached, every later run was a hit: adding a non-compliant\n * resource to a stack left `build` reporting success, and restored a\n * `checkov_report.json` recording zero resources scanned.\n *\n * `[\"default\"]` is what its `synth` sibling declares. It covers the project's\n * own sources and carries the transitive `dependentTasksOutputFiles` entry from\n * `nx.json`, which Nx resolves against the upstream `synth` task — so the hash\n * follows the template the scan actually reads.\n */\n\nconst CHECKOV_TARGET = 'checkov';\n\n/** The inputs the pre-fix generator declared, replaced in place. */\nconst VENDED_INPUTS = ['{workspaceRoot}/dist/{projectRoot}/cdk.out'];\n\n/** The inputs the generator declares now, matching the `synth` sibling. */\nconst FIXED_INPUTS = ['default'];\n\nconst divergedMessage = (projectName: string) =>\n  `${projectName}:${CHECKOV_TARGET}: its \\`inputs\\` have diverged from the generated shape - left untouched. Confirm they cover the synthesized template the scan reads: an input pointed only at \\`dist\\` matches no tracked file, so the scan can report a cached pass on infrastructure it never scanned.`;\n\n/** Whether a target's inputs are exactly the ones the generator vended. */\nconst hasVendedInputs = (target: TargetConfiguration): boolean =>\n  Array.isArray(target.inputs) &&\n  target.inputs.length === VENDED_INPUTS.length &&\n  target.inputs.every((input, index) => input === VENDED_INPUTS[index]);\n\nexport default async function migration(\n  tree: Tree,\n): Promise<MigrationReturnObject> {\n  const nextSteps: string[] = [];\n\n  for (const [projectName, project] of getProjects(tree)) {\n    const generator = (project.metadata as { generator?: string } | undefined)\n      ?.generator;\n    if (generator !== INFRA_APP_GENERATOR_INFO.id) continue;\n\n    const target = project.targets?.[CHECKOV_TARGET];\n    if (!target) continue;\n\n    // A target already declaring the fixed inputs needs nothing, which also\n    // makes a re-run — and a project generated after the fix — a no-op.\n    if (\n      Array.isArray(target.inputs) &&\n      target.inputs.length === FIXED_INPUTS.length &&\n      target.inputs.every((input, index) => input === FIXED_INPUTS[index])\n    ) {\n      continue;\n    }\n\n    if (!hasVendedInputs(target)) {\n      nextSteps.push(divergedMessage(projectName));\n      continue;\n    }\n\n    target.inputs = [...FIXED_INPUTS];\n    updateProjectConfiguration(\n      tree,\n      projectName,\n      project as ProjectConfiguration,\n    );\n  }\n\n  await formatFilesInSubtree(tree);\n\n  return { nextSteps };\n}\n"],"names":["getProjects","updateProjectConfiguration","INFRA_APP_GENERATOR_INFO","formatFilesInSubtree","CHECKOV_TARGET","VENDED_INPUTS","FIXED_INPUTS","divergedMessage","projectName","hasVendedInputs","target","Array","isArray","inputs","length","every","input","index","migration","tree","nextSteps","project","generator","metadata","id","targets","push"],"mappings":"AAAA;;;CAGC,GACD,SACEA,WAAW,EAKXC,0BAA0B,QACrB,aAAa;AACpB,SAASC,wBAAwB,QAAQ,kCAAkC;AAC3E,SAASC,oBAAoB,QAAQ,2BAA2B;AAEhE;;;;;;;;;;;;;;;CAeC,GAED,MAAMC,iBAAiB;AAEvB,kEAAkE,GAClE,MAAMC,gBAAgB;IAAC;CAA6C;AAEpE,yEAAyE,GACzE,MAAMC,eAAe;IAAC;CAAU;AAEhC,MAAMC,kBAAkB,CAACC,cACvB,GAAGA,YAAY,CAAC,EAAEJ,eAAe,yQAAyQ,CAAC;AAE7S,yEAAyE,GACzE,MAAMK,kBAAkB,CAACC,SACvBC,MAAMC,OAAO,CAACF,OAAOG,MAAM,KAC3BH,OAAOG,MAAM,CAACC,MAAM,KAAKT,cAAcS,MAAM,IAC7CJ,OAAOG,MAAM,CAACE,KAAK,CAAC,CAACC,OAAOC,QAAUD,UAAUX,aAAa,CAACY,MAAM;AAEtE,eAAe,eAAeC,UAC5BC,IAAU;IAEV,MAAMC,YAAsB,EAAE;IAE9B,KAAK,MAAM,CAACZ,aAAaa,QAAQ,IAAIrB,YAAYmB,MAAO;QACtD,MAAMG,YAAaD,QAAQE,QAAQ,EAC/BD;QACJ,IAAIA,cAAcpB,yBAAyBsB,EAAE,EAAE;QAE/C,MAAMd,SAASW,QAAQI,OAAO,EAAE,CAACrB,eAAe;QAChD,IAAI,CAACM,QAAQ;QAEb,wEAAwE;QACxE,oEAAoE;QACpE,IACEC,MAAMC,OAAO,CAACF,OAAOG,MAAM,KAC3BH,OAAOG,MAAM,CAACC,MAAM,KAAKR,aAAaQ,MAAM,IAC5CJ,OAAOG,MAAM,CAACE,KAAK,CAAC,CAACC,OAAOC,QAAUD,UAAUV,YAAY,CAACW,MAAM,GACnE;YACA;QACF;QAEA,IAAI,CAACR,gBAAgBC,SAAS;YAC5BU,UAAUM,IAAI,CAACnB,gBAAgBC;YAC/B;QACF;QAEAE,OAAOG,MAAM,GAAG;eAAIP;SAAa;QACjCL,2BACEkB,MACAX,aACAa;IAEJ;IAEA,MAAMlB,qBAAqBgB;IAE3B,OAAO;QAAEC;IAAU;AACrB"}

package/src/migrations/latest/gateway-url-accessor/__snapshots__/migration.spec.ts.snap

@@ -0,0 +1,84 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`gateway-url-accessor migration > should add the gatewayUrl accessor to the vended core construct 1`] = `
+"import * as agentcore from 'aws-cdk-lib/aws-bedrockagentcore';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import { Construct } from 'constructs';
+
+export class AgentCoreGateway extends Construct implements iam.IGrantable {
+  public readonly gateway: agentcore.Gateway;
+
+  constructor(scope: Construct, id: string) {
+    super(scope, id);
+    this.gateway = undefined as any;
+  }
+
+  /**
+   * The principal to grant permissions to.
+   */
+  public get grantPrincipal(): iam.IPrincipal {
+    return this.gateway.role.grantPrincipal;
+  }
+
+  /**
+   * The gateway's URL endpoint. The Gateway L2 types its own \`gatewayUrl\` as
+   * optional and only populates it when created from its own props, so fall
+   * back to the CloudFormation attribute.
+   */
+  public get gatewayUrl(): string {
+    return (
+      this.gateway.gatewayUrl ??
+      (this.gateway.node.defaultChild as agentcore.CfnGateway).attrGatewayUrl
+    );
+  }
+
+  public addGateway(
+    gateway: Construct & {
+      readonly gateway: agentcore.Gateway;
+      readonly gatewayName: string;
+      readonly gatewayUrl: string;
+    },
+    props?: {
+      gatewayTargetName?: string;
+    },
+  ): agentcore.CfnGatewayTarget {
+    const target = this.addGatewayTarget({
+      gatewayTargetName: props?.gatewayTargetName ?? gateway.gatewayName,
+      gatewayUrl: gateway.gatewayUrl,
+      gatewayArn: gateway.gateway.gatewayArn,
+    });
+    target.node.addDependency(gateway);
+    return target;
+  }
+
+  public addGatewayTarget(props: {
+    gatewayTargetName: string;
+    gatewayUrl: string;
+    gatewayArn: string;
+  }): agentcore.CfnGatewayTarget {
+    return undefined as any;
+  }
+}
+"
+`;
+
+exports[`gateway-url-accessor migration > should point vended app-level gateway constructs at the accessor 1`] = `
+"import { Construct } from 'constructs';
+import { AgentCoreGateway } from '../../../core/agentcore-gateway/agentcore-gateway';
+import { RuntimeConfig } from '../../../core/runtime-config';
+
+export class MyGateway extends AgentCoreGateway {
+  public readonly gatewayName = 'my-gateway';
+
+  constructor(scope: Construct, id: string) {
+    super(scope, id);
+
+    const rc = RuntimeConfig.ensure(this);
+    rc.set('agentcore', 'gateways', {
+      ...rc.get('agentcore').gateways,
+      MyGateway: this.gatewayUrl,
+    });
+  }
+}
+"
+`;

package/src/migrations/latest/gateway-url-accessor/metadata.json

@@ -0,0 +1,3 @@
+{
+  "description": "Expose a non-optional gatewayUrl accessor on the vended AgentCoreGateway construct"
+}

package/src/migrations/latest/gateway-url-accessor/migration.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { MigrationReturnObject, Tree } from '@nx/devkit';
+export default function migration(tree: Tree): Promise<MigrationReturnObject>;

package/src/migrations/latest/gateway-url-accessor/migration.js

@@ -0,0 +1,94 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { applyGritQL, GRIT_INSERT_PLACEHOLDER, insertViaGritQL, matchGritQL } from "../../../utils/ast.js";
+import { formatFilesInSubtree } from "../../../utils/format.js";
+import { PACKAGES_DIR, SHARED_CONSTRUCTS_DIR } from "../../../utils/shared-constructs-constants.js";
+/**
+ * The CDK `Gateway` L2 types its `gatewayUrl` as `string | undefined`, so
+ * reaching through the vended `AgentCoreGateway` construct to
+ * `gateway.gateway.gatewayUrl` does not typecheck where a `string` is required —
+ * the DCR proxy's `upstreamUrl`, for example. `AgentCoreGateway` gains a
+ * non-optional `gatewayUrl` accessor falling back to the CloudFormation
+ * attribute, which `addGateway` and the vended app-level gateway constructs then
+ * read.
+ */ const CONSTRUCTS_SRC = `${PACKAGES_DIR}/${SHARED_CONSTRUCTS_DIR}/src`;
+const GATEWAY_CONSTRUCT_FILE = `${CONSTRUCTS_SRC}/core/agentcore-gateway/agentcore-gateway.ts`;
+const GATEWAYS_DIR = `${CONSTRUCTS_SRC}/app/gateways`;
+const GATEWAY_URL_ACCESSOR = `/**
+   * The gateway's URL endpoint. The Gateway L2 types its own \`gatewayUrl\` as
+   * optional and only populates it when created from its own props, so fall
+   * back to the CloudFormation attribute.
+   */
+  public get gatewayUrl(): string {
+    return (
+      this.gateway.gatewayUrl ??
+      (this.gateway.node.defaultChild as agentcore.CfnGateway).attrGatewayUrl
+    );
+  }`;
+const divergedCoreMessage = `${GATEWAY_CONSTRUCT_FILE}: the AgentCoreGateway construct has diverged from the generated shape - left untouched. To use a gateway's URL where a \`string\` is required, add a \`public get gatewayUrl(): string\` accessor returning \`this.gateway.gatewayUrl ?? (this.gateway.node.defaultChild as agentcore.CfnGateway).attrGatewayUrl\`.`;
+/**
+ * Add the `gatewayUrl` accessor to the vended core construct, and route
+ * `addGateway` and the shape it requires of its argument through it. Returns
+ * whether the core construct ends up carrying the accessor — app-level
+ * constructs may only be pointed at it once it exists.
+ */ const migrateCoreConstruct = async (tree, nextSteps)=>{
+    if (!tree.exists(GATEWAY_CONSTRUCT_FILE)) {
+        return false;
+    }
+    const hasAccessor = await matchGritQL(tree, GATEWAY_CONSTRUCT_FILE, '`public get gatewayUrl(): string { $_ }`');
+    if (!hasAccessor) {
+        // Anchored on the grantPrincipal accessor, present in every vended version.
+        const added = await insertViaGritQL(tree, GATEWAY_CONSTRUCT_FILE, `\`public get grantPrincipal(): iam.IPrincipal { $body }\` as $accessor => \`$accessor
+
+  ${GRIT_INSERT_PLACEHOLDER}\``, GATEWAY_URL_ACCESSOR);
+        if (!added) {
+            nextSteps.push(divergedCoreMessage);
+            return false;
+        }
+    }
+    const addGatewayUsesAccessor = await matchGritQL(tree, GATEWAY_CONSTRUCT_FILE, '`gatewayUrl: gateway.gatewayUrl`');
+    if (!addGatewayUsesAccessor) {
+        // The accessor is part of the shape addGateway requires of its argument.
+        await applyGritQL(tree, GATEWAY_CONSTRUCT_FILE, `\`readonly gatewayName: string\` as $member => \`$member;
+      readonly gatewayUrl: string\``);
+        // addGateway reads the accessor rather than repeating the fallback inline.
+        await applyGritQL(tree, GATEWAY_CONSTRUCT_FILE, `\`this.addGatewayTarget({ gatewayTargetName: $name, gatewayUrl: $url, gatewayArn: $arn })\` where {
+  $url <: contains \`attrGatewayUrl\`
+} => \`this.addGatewayTarget({
+      gatewayTargetName: $name,
+      gatewayUrl: gateway.gatewayUrl,
+      gatewayArn: $arn,
+    })\``);
+    }
+    return true;
+};
+/**
+ * Point each vended app-level gateway construct's runtime config entry at the
+ * accessor.
+ */ const migrateAppConstructs = async (tree)=>{
+    if (!tree.exists(GATEWAYS_DIR)) {
+        return;
+    }
+    for (const dir of tree.children(GATEWAYS_DIR)){
+        const constructFile = `${GATEWAYS_DIR}/${dir}/${dir}.ts`;
+        if (!tree.exists(constructFile)) {
+            continue;
+        }
+        await applyGritQL(tree, constructFile, '`this.gateway.gatewayUrl` => `this.gatewayUrl`');
+    }
+};
+export default async function migration(tree) {
+    const nextSteps = [];
+    // The app constructs read the accessor, so they may only be migrated once the
+    // core construct carries it.
+    if (await migrateCoreConstruct(tree, nextSteps)) {
+        await migrateAppConstructs(tree);
+    }
+    await formatFilesInSubtree(tree);
+    return {
+        nextSteps
+    };
+}
+
+//# sourceMappingURL=migration.js.map

package/src/migrations/latest/gateway-url-accessor/migration.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../packages/nx-plugin/src/migrations/latest/gateway-url-accessor/migration.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport type { MigrationReturnObject, Tree } from '@nx/devkit';\nimport {\n  applyGritQL,\n  GRIT_INSERT_PLACEHOLDER,\n  insertViaGritQL,\n  matchGritQL,\n} from '../../../utils/ast.js';\nimport { formatFilesInSubtree } from '../../../utils/format.js';\nimport {\n  PACKAGES_DIR,\n  SHARED_CONSTRUCTS_DIR,\n} from '../../../utils/shared-constructs-constants.js';\n\n/**\n * The CDK `Gateway` L2 types its `gatewayUrl` as `string | undefined`, so\n * reaching through the vended `AgentCoreGateway` construct to\n * `gateway.gateway.gatewayUrl` does not typecheck where a `string` is required —\n * the DCR proxy's `upstreamUrl`, for example. `AgentCoreGateway` gains a\n * non-optional `gatewayUrl` accessor falling back to the CloudFormation\n * attribute, which `addGateway` and the vended app-level gateway constructs then\n * read.\n */\n\nconst CONSTRUCTS_SRC = `${PACKAGES_DIR}/${SHARED_CONSTRUCTS_DIR}/src`;\n\nconst GATEWAY_CONSTRUCT_FILE = `${CONSTRUCTS_SRC}/core/agentcore-gateway/agentcore-gateway.ts`;\n\nconst GATEWAYS_DIR = `${CONSTRUCTS_SRC}/app/gateways`;\n\nconst GATEWAY_URL_ACCESSOR = `/**\n   * The gateway's URL endpoint. The Gateway L2 types its own \\`gatewayUrl\\` as\n   * optional and only populates it when created from its own props, so fall\n   * back to the CloudFormation attribute.\n   */\n  public get gatewayUrl(): string {\n    return (\n      this.gateway.gatewayUrl ??\n      (this.gateway.node.defaultChild as agentcore.CfnGateway).attrGatewayUrl\n    );\n  }`;\n\nconst divergedCoreMessage = `${GATEWAY_CONSTRUCT_FILE}: the AgentCoreGateway construct has diverged from the generated shape - left untouched. To use a gateway's URL where a \\`string\\` is required, add a \\`public get gatewayUrl(): string\\` accessor returning \\`this.gateway.gatewayUrl ?? (this.gateway.node.defaultChild as agentcore.CfnGateway).attrGatewayUrl\\`.`;\n\n/**\n * Add the `gatewayUrl` accessor to the vended core construct, and route\n * `addGateway` and the shape it requires of its argument through it. Returns\n * whether the core construct ends up carrying the accessor — app-level\n * constructs may only be pointed at it once it exists.\n */\nconst migrateCoreConstruct = async (\n  tree: Tree,\n  nextSteps: string[],\n): Promise<boolean> => {\n  if (!tree.exists(GATEWAY_CONSTRUCT_FILE)) {\n    return false;\n  }\n\n  const hasAccessor = await matchGritQL(\n    tree,\n    GATEWAY_CONSTRUCT_FILE,\n    '`public get gatewayUrl(): string { $_ }`',\n  );\n\n  if (!hasAccessor) {\n    // Anchored on the grantPrincipal accessor, present in every vended version.\n    const added = await insertViaGritQL(\n      tree,\n      GATEWAY_CONSTRUCT_FILE,\n      `\\`public get grantPrincipal(): iam.IPrincipal { $body }\\` as $accessor => \\`$accessor\n\n  ${GRIT_INSERT_PLACEHOLDER}\\``,\n      GATEWAY_URL_ACCESSOR,\n    );\n    if (!added) {\n      nextSteps.push(divergedCoreMessage);\n      return false;\n    }\n  }\n\n  const addGatewayUsesAccessor = await matchGritQL(\n    tree,\n    GATEWAY_CONSTRUCT_FILE,\n    '`gatewayUrl: gateway.gatewayUrl`',\n  );\n\n  if (!addGatewayUsesAccessor) {\n    // The accessor is part of the shape addGateway requires of its argument.\n    await applyGritQL(\n      tree,\n      GATEWAY_CONSTRUCT_FILE,\n      `\\`readonly gatewayName: string\\` as $member => \\`$member;\n      readonly gatewayUrl: string\\``,\n    );\n\n    // addGateway reads the accessor rather than repeating the fallback inline.\n    await applyGritQL(\n      tree,\n      GATEWAY_CONSTRUCT_FILE,\n      `\\`this.addGatewayTarget({ gatewayTargetName: $name, gatewayUrl: $url, gatewayArn: $arn })\\` where {\n  $url <: contains \\`attrGatewayUrl\\`\n} => \\`this.addGatewayTarget({\n      gatewayTargetName: $name,\n      gatewayUrl: gateway.gatewayUrl,\n      gatewayArn: $arn,\n    })\\``,\n    );\n  }\n\n  return true;\n};\n\n/**\n * Point each vended app-level gateway construct's runtime config entry at the\n * accessor.\n */\nconst migrateAppConstructs = async (tree: Tree): Promise<void> => {\n  if (!tree.exists(GATEWAYS_DIR)) {\n    return;\n  }\n  for (const dir of tree.children(GATEWAYS_DIR)) {\n    const constructFile = `${GATEWAYS_DIR}/${dir}/${dir}.ts`;\n    if (!tree.exists(constructFile)) {\n      continue;\n    }\n    await applyGritQL(\n      tree,\n      constructFile,\n      '`this.gateway.gatewayUrl` => `this.gatewayUrl`',\n    );\n  }\n};\n\nexport default async function migration(\n  tree: Tree,\n): Promise<MigrationReturnObject> {\n  const nextSteps: string[] = [];\n\n  // The app constructs read the accessor, so they may only be migrated once the\n  // core construct carries it.\n  if (await migrateCoreConstruct(tree, nextSteps)) {\n    await migrateAppConstructs(tree);\n  }\n\n  await formatFilesInSubtree(tree);\n\n  return { nextSteps };\n}\n"],"names":["applyGritQL","GRIT_INSERT_PLACEHOLDER","insertViaGritQL","matchGritQL","formatFilesInSubtree","PACKAGES_DIR","SHARED_CONSTRUCTS_DIR","CONSTRUCTS_SRC","GATEWAY_CONSTRUCT_FILE","GATEWAYS_DIR","GATEWAY_URL_ACCESSOR","divergedCoreMessage","migrateCoreConstruct","tree","nextSteps","exists","hasAccessor","added","push","addGatewayUsesAccessor","migrateAppConstructs","dir","children","constructFile","migration"],"mappings":"AAAA;;;CAGC,GAED,SACEA,WAAW,EACXC,uBAAuB,EACvBC,eAAe,EACfC,WAAW,QACN,wBAAwB;AAC/B,SAASC,oBAAoB,QAAQ,2BAA2B;AAChE,SACEC,YAAY,EACZC,qBAAqB,QAChB,gDAAgD;AAEvD;;;;;;;;CAQC,GAED,MAAMC,iBAAiB,GAAGF,aAAa,CAAC,EAAEC,sBAAsB,IAAI,CAAC;AAErE,MAAME,yBAAyB,GAAGD,eAAe,4CAA4C,CAAC;AAE9F,MAAME,eAAe,GAAGF,eAAe,aAAa,CAAC;AAErD,MAAMG,uBAAuB,CAAC;;;;;;;;;;GAU3B,CAAC;AAEJ,MAAMC,sBAAsB,GAAGH,uBAAuB,oTAAoT,CAAC;AAE3W;;;;;CAKC,GACD,MAAMI,uBAAuB,OAC3BC,MACAC;IAEA,IAAI,CAACD,KAAKE,MAAM,CAACP,yBAAyB;QACxC,OAAO;IACT;IAEA,MAAMQ,cAAc,MAAMb,YACxBU,MACAL,wBACA;IAGF,IAAI,CAACQ,aAAa;QAChB,4EAA4E;QAC5E,MAAMC,QAAQ,MAAMf,gBAClBW,MACAL,wBACA,CAAC;;EAEL,EAAEP,wBAAwB,EAAE,CAAC,EACzBS;QAEF,IAAI,CAACO,OAAO;YACVH,UAAUI,IAAI,CAACP;YACf,OAAO;QACT;IACF;IAEA,MAAMQ,yBAAyB,MAAMhB,YACnCU,MACAL,wBACA;IAGF,IAAI,CAACW,wBAAwB;QAC3B,yEAAyE;QACzE,MAAMnB,YACJa,MACAL,wBACA,CAAC;mCAC4B,CAAC;QAGhC,2EAA2E;QAC3E,MAAMR,YACJa,MACAL,wBACA,CAAC;;;;;;QAMC,CAAC;IAEP;IAEA,OAAO;AACT;AAEA;;;CAGC,GACD,MAAMY,uBAAuB,OAAOP;IAClC,IAAI,CAACA,KAAKE,MAAM,CAACN,eAAe;QAC9B;IACF;IACA,KAAK,MAAMY,OAAOR,KAAKS,QAAQ,CAACb,cAAe;QAC7C,MAAMc,gBAAgB,GAAGd,aAAa,CAAC,EAAEY,IAAI,CAAC,EAAEA,IAAI,GAAG,CAAC;QACxD,IAAI,CAACR,KAAKE,MAAM,CAACQ,gBAAgB;YAC/B;QACF;QACA,MAAMvB,YACJa,MACAU,eACA;IAEJ;AACF;AAEA,eAAe,eAAeC,UAC5BX,IAAU;IAEV,MAAMC,YAAsB,EAAE;IAE9B,8EAA8E;IAC9E,6BAA6B;IAC7B,IAAI,MAAMF,qBAAqBC,MAAMC,YAAY;QAC/C,MAAMM,qBAAqBP;IAC7B;IAEA,MAAMT,qBAAqBS;IAE3B,OAAO;QAAEC;IAAU;AACrB"}

package/src/migrations/latest/infra-deploy-express-mode/metadata.json

@@ -1,3 +1,3 @@
 {
-  "description": "Deploy using CloudFormation express mode from the deploy and deploy-sandbox targets of ts#infra projects"
+  "description": "Deploy using CloudFormation express mode from the deploy-sandbox target of ts#infra projects, and wait for full stabilization from deploy"
 }

package/src/migrations/latest/infra-deploy-express-mode/migration.js

@@ -5,29 +5,31 @@
 import { INFRA_APP_GENERATOR_INFO } from "../../../infra/app/generator.js";
 import { formatFilesInSubtree } from "../../../utils/format.js";
 /**
- * Deploy using CloudFormation express mode from the deploy and deploy-sandbox
- * targets of ts#infra projects
+ * Deploy using CloudFormation express mode from the deploy-sandbox target of
+ * ts#infra projects, and wait for full stabilization everywhere else.
  *
- * Express mode completes each resource operation as soon as its configuration
- * is applied rather than waiting for full stabilization, which is a much faster
- * iteration cycle for development deploys.
+ * Express mode completes each resource operation as soon as its configuration is
+ * applied rather than waiting for full stabilization, which is a much faster
+ * iteration cycle for development deploys. It returns before resources have
+ * settled, so it suits only the stage you iterate on.
  *
- * Two targets keep waiting for full stabilization: `deploy-ci`, since pipeline
- * deployments should never skip it, and - when stages are configured - `deploy`,
- * which deploys whichever stage is named, including beta and prod.
- */ const DEPLOY_TARGETS = [
-    'deploy',
-    'deploy-sandbox'
-];
-const EXPRESS_FLAG = '--express';
+ * `deploy-sandbox` therefore gets it, since it only ever deploys the sandbox
+ * stage. `deploy` names whichever stage you give it, including beta and prod, and
+ * `deploy-ci` runs from a pipeline - both wait for full stabilization.
+ */ const EXPRESS_FLAG = '--express';
+const NO_EXPRESS_FLAG = '--no-express';
+/** Whether `deploy-sandbox` should carry the flag, and `deploy` should not. */ const WANTS_EXPRESS = {
+    'deploy-sandbox': true,
+    deploy: false
+};
 /**
  * Whether the command is one of the deploy commands this migration vends -
  * either a direct `cdk deploy`, or the stage-config `infra-deploy.ts` script
  * that wraps it. Anything else has been hand-written and is reported rather
  * than rewritten.
  */ const isGeneratedDeployCommand = (command)=>/(^|\s)cdk\s+deploy(\s|$)/.test(command) || command.includes('infra-deploy.ts');
-/** Whether the command runs the stage-config deploy script. */ const isStageConfigDeploy = (command)=>command.includes('infra-deploy.ts');
-const divergedNextStep = (projectName, target)=>`${projectName}: its ${target} target has been customised, so it was left as it is. Add "${EXPRESS_FLAG}" to the target's command to deploy using CloudFormation express mode.`;
+const divergedNextStep = (projectName, target, wantsExpress)=>wantsExpress ? `${projectName}: its ${target} target has been customised, so it was left as it is. Add "${EXPRESS_FLAG}" to the target's command to deploy using CloudFormation express mode.` : `${projectName}: its ${target} target has been customised, so it was left as it is. Remove "${EXPRESS_FLAG}" from the target's command so it waits for full resource stabilization - this target can name any stage, including production.`;
+/** Drops the flag wherever it sits, leaving the rest of the command untouched. */ const withoutExpress = (command)=>command.split(/\s+/).filter((arg)=>arg !== EXPRESS_FLAG).join(' ');
 export default async function migration(tree) {
     const nextSteps = [];
     let migrated = false;
@@ -36,35 +38,31 @@ export default async function migration(tree) {
             continue;
         }
         let projectChanged = false;
-        for (const targetName of DEPLOY_TARGETS){
+        for (const [targetName, wantsExpress] of Object.entries(WANTS_EXPRESS)){
             const target = project.targets?.[targetName];
             const command = target?.options?.command;
             if (!target || typeof command !== 'string') {
                 continue;
             }
-            // Already migrated (or generated by a version that already passes it) -
-            // skip so re-running is a no-op.
-            if (command.split(/\s+/).includes(EXPRESS_FLAG)) {
+            const args = command.split(/\s+/);
+            const hasExpress = args.includes(EXPRESS_FLAG);
+            // Already in the wanted state, so re-running - and a project generated
+            // after this change - is a no-op.
+            if (hasExpress === wantsExpress) {
                 continue;
             }
             // `--no-express` is a deliberate opt-out, so honour it rather than
             // flipping the user back to express mode.
-            if (command.split(/\s+/).includes('--no-express')) {
+            if (wantsExpress && args.includes(NO_EXPRESS_FLAG)) {
                 continue;
             }
             if (!isGeneratedDeployCommand(command)) {
-                nextSteps.push(divergedNextStep(name, targetName));
-                continue;
-            }
-            // When stages are configured, `deploy` deploys whichever stage is named,
-            // including beta and prod, so it stays on full stabilization. Only its
-            // sandbox counterpart opts into express mode.
-            if (targetName === 'deploy' && isStageConfigDeploy(command)) {
+                nextSteps.push(divergedNextStep(name, targetName, wantsExpress));
                 continue;
             }
             // Appended last so it stays clear of the stage pattern, which the
             // stage-config deploy script reads from the first positional argument.
-            target.options.command = `${command} ${EXPRESS_FLAG}`;
+            target.options.command = wantsExpress ? `${command} ${EXPRESS_FLAG}` : withoutExpress(command);
             projectChanged = true;
         }
         if (projectChanged) {