@aws/nx-plugin-mcp 1.0.0-rc.89 → 1.0.0-rc.90

package/bin/aws-nx-mcp.js

@@ -53603,6 +53603,11 @@ const filterableOptionsFromSchema = (schema) => {
 * SPDX-License-Identifier: Apache-2.0
 */
 /**
+* Warn agents that an experimental generator's output may change in a future
+* release without a migration to carry an existing workspace across.
+*/
+const renderExperimentalWarning = (generatorId) => `> [!WARNING] Experimental: the \`${generatorId}\` generator's behaviour and generated output may change in a future release without a migration being published to apply the change to an existing workspace.`;
+/**
 * Render summary information about a generator
 */
 const renderGeneratorInfo = (packageManager, info) => {
@@ -53610,7 +53615,7 @@ const renderGeneratorInfo = (packageManager, info) => {
 	return `${info.id}
 
 Description: ${info.description}
-
+${info.experimental ? `\n${renderExperimentalWarning(info.id)}\n` : ""}
 Available Parameters:
 ${renderSchema(schema)}
 
@@ -53697,7 +53702,7 @@ const renderUnsupportedMessage = (info, requested, predicates) => {
 	return `## ${info.id}
 
 > [!WARNING] Unsupported combination: ${requestedDesc}. The \`${info.id}\` generator has no guide variant matching this combination — running it will likely fail.
-
+${info.experimental ? `\n${renderExperimentalWarning(info.id)}\n` : ""}
 Supported combinations:
 ${supportedList}
 
@@ -54150,8 +54155,16 @@ const addUpgradeWorkspaceTool = (server, generators) => {
 	});
 };
 //#endregion
-//#region ../nx-plugin/generators.json
-var generators$1 = {
+//#region ../nx-plugin/src/utils/generators.ts
+/**
+* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+* SPDX-License-Identifier: Apache-2.0
+*/
+/**
+* Typed view of the `generators.json` entries, keyed by generator id, so every
+* consumer that describes a generator reads the same declared shape.
+*/
+const generatorsJsonEntries = {
 	"init": {
 		"factory": "./src/init/generator",
 		"schema": "./src/init/schema.json",
@@ -54198,7 +54211,8 @@ var generators$1 = {
 		"schema": "./src/agentcore-harness/schema.json",
 		"description": "Generate an AgentCore Harness project",
 		"metric": "g71",
-		"guidePages": ["agentcore-harness"]
+		"guidePages": ["agentcore-harness"],
+		"experimental": true
 	},
 	"connection": {
 		"factory": "./src/connection/generator",
@@ -54697,23 +54711,18 @@ var generators$1 = {
 		"hidden": true
 	}
 };
-//#endregion
-//#region ../nx-plugin/src/utils/generators.ts
-/**
-* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-* SPDX-License-Identifier: Apache-2.0
-*/
 /**
 * Build the list of generator info, resolving schema/factory paths relative to the given base directory.
 */
-const buildGeneratorInfoList = (baseDir) => Object.entries(generators$1).map(([id, info]) => ({
+const buildGeneratorInfoList = (baseDir) => Object.entries(generatorsJsonEntries).map(([id, info]) => ({
 	id,
 	metric: info.metric,
 	resolvedFactoryPath: path$3.resolve(baseDir, info.factory),
 	resolvedSchemaPath: path$3.resolve(baseDir, info.schema),
 	description: info.description,
-	..."hidden" in info && info.hidden ? { hidden: info.hidden } : {},
-	..."guidePages" in info && info.guidePages ? { guidePages: info.guidePages } : {}
+	...info.hidden ? { hidden: info.hidden } : {},
+	...info.experimental ? { experimental: info.experimental } : {},
+	...info.guidePages ? { guidePages: info.guidePages } : {}
 }));
 //#endregion
 //#region src/index.ts

package/docs/get_started/upgrading.mdx

@@ -123,6 +123,10 @@ Migrations don't cover every change to the infrastructure we vend. Where updatin
 To pick those changes up, compare your infrastructure against what today's generators produce and apply the parts you want by hand, taking care over the deployment path for your existing resources.
 </Aside>
 
+<Aside type="caution" title="Experimental generators are not migrated">
+Some generators are marked as experimental — their guide page carries a banner saying so. Changes to these generators may ship without a migration to apply them to an existing workspace, so if you use one, check its guide after upgrading and reconcile any differences with your project yourself.
+</Aside>
+
 ## Upgrading with an AI agent
 
 The whole flow can be driven by an AI coding agent end to end — nothing blocks on an interactive terminal. When `nx migrate --run-migrations` runs from inside an agent, Nx detects this, skips the agentic consent prompt, and instead of spawning a nested agent it **defers** each prompt migration back to the agent driving the run:

package/docs/guides/docker-bundling.mdx

@@ -8,14 +8,12 @@ import NxCommands from '@components/nx-commands.astro';
 import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
 import Link from '@components/link.astro';
 import Infrastructure from '@components/infrastructure.astro';
-import TrivyVersion from '@components/trivy-version.astro';
 import { CONTAINER_VERSIONS } from '../../../../../../packages/nx-plugin/src/utils/versions';
 
 export const trivyTarget = `{
   "targets": {
     "trivy": {
-      "cache": true,
-      "inputs": ["default", "^production"],
+      "cache": false,
       "outputs": ["{workspaceRoot}/dist/{projectRoot}/trivy"],
       "executor": "nx:run-commands",
       "options": {
@@ -68,7 +66,7 @@ The Docker build context is written to your project's `dist` folder. Your infras
 :::tip[Why bundle outside the Dockerfile?]
 Keeping the bundle step in Nx (rather than inside the `Dockerfile`) means:
 
-- Nx can **cache** the bundle target, so repeated builds are fast.
+- Nx can **cache** the bundle target — its output is a directory on disk, so a cache hit genuinely restores it.
 - The `Dockerfile` does not need access to your monorepo, private registries, or build-time secrets.
 - The image layer is tiny — a single `COPY` of already-built artifacts, with no transitive `node_modules` or build toolchain.
 :::
@@ -84,6 +82,7 @@ Configure a `bundle` target that invokes Rolldown. If you are starting from a <L
   "targets": {
     "bundle": {
       "cache": true,
+      "inputs": ["default"],
       "executor": "nx:run-commands",
       "outputs": ["{workspaceRoot}/dist/{projectRoot}/bundle"],
       "options": {
@@ -167,7 +166,7 @@ Add a `docker` target which:
 {
   "targets": {
     "docker": {
-      "cache": true,
+      "cache": false,
       "executor": "nx:run-commands",
       "options": {
         "commands": [
@@ -182,6 +181,10 @@ Add a `docker` target which:
 }
 ```
 
+:::caution[Do not cache image builds]
+Set `"cache": false` on image build targets. A built image is not written to an `outputs` path in the filesystem, so Nx has nothing to restore on a cache hit. Container engines cache image layers regardless, so there is no performance penalty.
+:::
+
 :::tip[Cross-platform file copy]
 The `ncp` package provides a cross-platform file/directory copy command, avoiding `cp` (unavailable on Windows). Install it at the root of your workspace with `pnpm add -D -w ncp`.
 :::
@@ -256,7 +259,7 @@ Add a `docker` target which copies the `Dockerfile` into the bundle output direc
 {
   "targets": {
     "docker": {
-      "cache": true,
+      "cache": false,
       "executor": "nx:run-commands",
       "options": {
         "commands": [
@@ -296,10 +299,6 @@ The scan is intentionally not wired into `build` since this can introduce unnece
 Instead we recommend running the above command as a dedicated step in your CI pipeline prior to deployment to production stages.
 :::
 
-:::tip[Caching skips unchanged images]
-Because the image is fully determined by your project source, declaring `inputs` (here `default` and `^production`, matching the `bundle` target) lets Nx cache the scan and skip re-scanning an image that hasn't changed. Pin the Trivy image version (e.g. <code>trivy:<TrivyVersion /></code>) so scans are reproducible.
-:::
-
 :::note[Suppressing findings]
 Trivy reads a `.trivyignore` file (a list of vulnerability IDs, one per line) from the root of your project. `--ignore-unfixed` skips vulnerabilities with no available fix, so the scan only fails on issues you can action by upgrading tooling in your `Dockerfile`. See the [Trivy filtering documentation](https://trivy.dev/latest/docs/configuration/filtering/#by-finding-ids) for details.
 :::

package/docs/guides/python-project.mdx

@@ -96,6 +96,7 @@ When you use your Python project as runtime code (for example as the handler for
     ...
     "bundle": {
       "cache": true,
+      "inputs": ["production", "^production"],
       "executor": "nx:run-commands",
       "outputs": ["{workspaceRoot}/dist/packages/my_library/bundle"],
       "options": {
@@ -139,6 +140,18 @@ Or use the shorthand command:
 
 <PackageManagerShortCommand commands={["build"]} />
 
+### Assembling
+
+Your project also has an `assemble` target, which produces whatever your project contributes to a deployment (for example its compiled or bundled output), without running the lint, test or type-check gates.
+
+<NxCommands commands={['assemble <project-name>']} />
+
+The deploy targets depend on `assemble`, so deploying builds only what it is about to deploy.
+
+:::caution[Use `build` in your pipeline]
+`assemble` is used for faster iteration during development. Run `build` in your CI pipeline to ensure your project passes quality gates prior to a production deployment.
+:::
+
 ## Testing
 
 [pytest](https://docs.pytest.org/en/stable/) is configured for testing your project.
@@ -175,6 +188,16 @@ You can run an individual test or suite of tests using the `-k` flag, specifying
 
 <NxCommands commands={["test <project-name> -k 'test_say_hello'"]} />
 
+### Test Files and Caching
+
+Your project's `tests` directory is excluded from the `production` named input in `nx.json`.
+
+Targets whose output cannot contain a test file - such as `compile` and any bundle targets - read `production` rather than `default`, so editing a test does not invalidate them or any task in a project which depends on yours.
+
+The exclusion is deliberately limited to the `tests` directory. A `test_*.py` file inside your package directory is treated as production code, since it is packaged into your built distribution, and so still invalidates the build.
+
+The `test`, `lint`, `format` and `typecheck` targets read `default` and so still re-run when you edit a test. Note that `typecheck` type checks your tests too, so a type error in a test is still reported.
+
 ## Type Checking
 
 Python projects use [ty](https://docs.astral.sh/ty/) for type checking.

package/docs/guides/terraform-project.mdx

@@ -9,6 +9,7 @@ import Link from '@components/link.astro';
 import GeneratorParameters from '@components/generator-parameters.astro';
 import NxCommands from '@components/nx-commands.astro';
 import OptionFilter from '@components/option-filter.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
 
 [Terraform](https://www.terraform.io/) is an open-source infrastructure as code software tool that enables you to safely and predictably create, change, and improve infrastructure.
 
@@ -53,6 +54,7 @@ For application projects (`--type=application`), the generator creates a complet
     - bootstrap.ts Pulls/pushes the bootstrap tfstate and runs `terraform apply`
     - bootstrap-destroy.ts Empties the state bucket and runs `terraform destroy`
     - init.ts Runs `terraform init` with the S3 backend config
+    - env.ts Points `terraform init` at the shared provider cache
   - checkov.yml Checkov configuration, including the checks to skip
   - project.json Project configuration and build targets
 
@@ -245,11 +247,45 @@ You can validate your Terraform configuration using the `validate` target:
 
 <NxCommands commands={['validate tf-infra']} />
 
-#### Formatting your Code
+#### Linting
 
-Format your Terraform code using the `fmt` target:
+Terraform projects use [`terraform fmt`](https://developer.hashicorp.com/terraform/cli/commands/fmt) to check formatting.
 
-<NxCommands commands={['fmt tf-infra']} />
+##### Running the Linter
+
+To invoke the linter to check your project, you can run the `lint` target.
+
+<NxCommands commands={["lint tf-infra"]} />
+
+##### Fixing Lint Issues
+
+The majority of linting or formatting issues can be fixed automatically by running with the `--configuration=fix` argument.
+
+<NxCommands commands={["lint tf-infra --configuration=fix"]} />
+
+Similarly if you would like to fix all lint issues in all packages in your workspace, you can run:
+
+<NxCommands commands={["run-many --target lint --all --configuration=fix"]} />
+
+:::tip[Shorthand Command]
+This has a shorthand command from the root of your workspace:
+
+<PackageManagerShortCommand commands={["lint"]} />
+:::
+
+##### Skipping Lint Issues
+
+To avoid linting issues slowing you down during development (particularly if you have non auto-fixable issues in your project), you can run a build with the `skip-lint` configuration:
+
+<NxCommands commands={["run-many --target build --configuration=skip-lint"]} />
+
+This skips the format check entirely during build.
+
+:::tip[Shorthand Command]
+This has a shorthand command from the root of your workspace:
+
+<PackageManagerShortCommand commands={["build:skip-lint"]} />
+:::
 
 #### Security Testing
 
@@ -259,6 +295,8 @@ Run security checks on your infrastructure using Checkov with the `checkov` targ
 
 You will find your security test results in the root `dist` folder, under `dist/packages/<my-terraform-project>/checkov`.
 
+Checkov runs as part of `build`.
+
 Checks are configured in the project's `checkov.yml`. Add a check id to `skip-check` to suppress it across the whole project:
 
 ```yaml title="checkov.yml"
@@ -313,6 +351,10 @@ run "plan_is_valid" {
 
 Set every variable your configuration requires in the `variables` block, otherwise the run fails with "has a required variable ... with no set value".
 
+Every target that runs `terraform init` reuses a provider cache under `.terraform/plugin-cache` in your workspace root, so providers are downloaded once rather than on every run. Each project gets its own directory there: two `terraform init` runs filling one cache at the same time can each compute a different hash for the same provider, which terraform then rejects against your `.terraform.lock.hcl`. See the [Terraform documentation](https://developer.hashicorp.com/terraform/cli/config/config-file#provider-plugin-cache) for more information.
+
+Set `TF_PLUGIN_CACHE_DIR` in your environment to point the vended `init` script at a cache you manage yourself — a volume shared between workspaces, say. Note that the `test` target reads its path from `project.json`, so change it there too.
+
 <OptionFilter when={{ type: 'application' }} description="Application-only targets: plan / apply / destroy / etc.">
 ### Application-Only Targets
 
@@ -326,6 +368,12 @@ Before applying changes, you can see what Terraform will do by running the `plan
 
 This will create a plan file in `dist/packages/<my-terraform-project>/terraform/dev.tfplan`.
 
+`plan` depends on `assemble`, so it produces the artifacts your modules reference, such as the Lambda bundles and generated operations metadata, without running the lint, test and type-check gates.
+
+:::caution[Use `build` in your pipeline]
+`assemble` is used for faster iteration during development. Run `build` in your CI pipeline to ensure your project passes quality gates prior to a production deployment.
+:::
+
 #### Initializing Terraform
 
 Initialize your Terraform working directory with the `init` target:

package/docs/guides/typescript-infrastructure.mdx

@@ -321,6 +321,8 @@ As part of your `build` target, as well as running the <Link path="guides/typesc
 
 You will find your synthesized cloud assembly in the root `dist` folder, under `dist/packages/<my-infra-project>/cdk.out`.
 
+`synth` depends on `^assemble`, so synthesizing builds the artifacts your stacks deploy, such as the Lambda bundles, container images and generated specifications, without running every upstream project's lint, test and type-check gates. See <Link path="guides/typescript-project#assembling">Assembling</Link> for more detail on `assemble`.
+
 ## Security Testing
 
 A `checkov` target is added to your project which runs security checks on your infrastructure using [Checkov](https://www.checkov.io/).
@@ -383,6 +385,12 @@ Your project has three deploy targets, each suited to a different situation:
 | `deploy`         | Deploying any stage, by naming the stage or stacks you want.                      |
 | `deploy-ci`      | Deploying from a CI/CD pipeline, using a pre-synthesized cloud assembly.          |
 
+`deploy-sandbox` and `deploy` depend on `^assemble`, so they build the artifacts they are about to deploy and nothing else. `deploy-ci` deploys an assembly your pipeline already built, so it has no build dependencies at all.
+
+:::caution[Use `build` in your pipeline]
+`assemble` is used for faster iteration during development. Run `build` in your CI pipeline to ensure your project passes quality gates prior to a production deployment.
+:::
+
 First, make sure you have AWS credentials configured. If you generated with `stageConfig` and have configured stage credentials in `packages/common/infra-config/src/stages.config.ts`, the deploy command will automatically resolve and apply the correct credentials for the target stage. Otherwise, ensure your AWS credentials are set in your environment (e.g., via `AWS_PROFILE` or environment variables). See the [AWS credentials documentation](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) for the available options.
 
 ### Deploying your Sandbox Stage

package/docs/guides/typescript-project.mdx

@@ -332,6 +332,18 @@ Or use the shorthand command:
 
 <PackageManagerShortCommand commands={["build"]} />
 
+### Assembling
+
+Your project also has an `assemble` target, which produces whatever your project contributes to a deployment (for example its compiled or bundled output), without running the lint, test or type-check gates.
+
+<NxCommands commands={['assemble <project-name>']} />
+
+The <Link path="guides/typescript-infrastructure#deploying-to-aws">deploy targets</Link> depend on `assemble`, so deploying builds only what it is about to deploy.
+
+:::caution[Use `build` in your pipeline]
+`assemble` is used for faster iteration during development. Run `build` in your CI pipeline to ensure your project passes quality gates prior to a production deployment.
+:::
+
 ## Testing
 
 [Vitest](https://vitest.dev/) is configured for testing your project.
@@ -379,6 +391,14 @@ You can run an individual test or suite of tests using Vitest's `-t` flag. Pass
 If you are a VSCode user, we recommend installing the [Vitest Runner for VSCode that actually works](https://marketplace.visualstudio.com/items?itemName=rluvaton.vscode-vitest) extension, which allows you to run, watch or debug tests from your IDE.
 :::
 
+### Test Coverage
+
+Pass Vitest's `--coverage` flag after a `--` separator to collect coverage:
+
+<NxCommands commands={['test <project-name> -- --coverage']} />
+
+Reports are written to `dist/<project-root>/test-output/vitest/coverage`, with the HTML report at `index.html`.
+
 ## Linting
 
 TypeScript projects use [Biome](https://biomejs.dev/) for linting and formatting. Biome is configured in the workspace root `biome.json` file — changes to this apply to all TypeScript projects in your workspace and ensure consistency.

package/docs/snippets/experimental-generator.mdx

@@ -0,0 +1,8 @@
+---
+title: Experimental Generator
+---
+import Link from '@components/link.astro';
+
+:::caution[Experimental]
+This generator is experimental. Its behaviour and generated output may change in a future release without a <Link path="get_started/upgrading">migration</Link> being published to apply the change to an existing workspace, so you may need to reconcile those changes yourself when you upgrade.
+:::

package/docs/snippets/trivy-image-scan.mdx

@@ -8,7 +8,7 @@ The Docker image built for this project can be scanned for vulnerabilities using
 
 A `trivy` target is added to your project which scans the built image and **exits non-zero** if any `HIGH` or `CRITICAL` severity vulnerability is found. The generated `Dockerfile` uses a base image with no known fixable vulnerabilities of these severities at time of generation, and upgrades bundled tooling (such as `npm`) to keep it that way.
 
-The scan uses the same container engine as your image build (`docker` or `finch`), so no additional tooling is required. Since the scan is only re-run when the image changes, an unchanged image is not re-scanned. The vended `trivy` root script scans every image in the workspace:
+The scan uses the same container engine as your image build (`docker` or `finch`), so no additional tooling is required. The scan is not cached, since the image it reads lives in the container engine rather than on disk — so it always scans the real image, and fails loudly rather than reporting a cached pass for an image that is no longer there. Each run therefore takes tens of seconds per image and refreshes Trivy's vulnerability database, so it needs network access. The vended `trivy` root script scans every image in the workspace:
 
 <PackageManagerShortCommand commands={['trivy']} />
 

package/generators.json

@@ -49,7 +49,8 @@
       "schema": "./src/agentcore-harness/schema.json",
       "description": "Generate an AgentCore Harness project",
       "metric": "g71",
-      "guidePages": ["agentcore-harness"]
+      "guidePages": ["agentcore-harness"],
+      "experimental": true
     },
     "connection": {
       "factory": "./src/connection/generator",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/nx-plugin-mcp",
-  "version": "1.0.0-rc.89",
+  "version": "1.0.0-rc.90",
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/nx-plugin-for-aws.git",