@aws/nx-plugin-mcp 1.0.0-rc.4 → 1.0.0-rc.5

package/docs/guides/license.mdx

@@ -6,10 +6,12 @@ generator: license
 import { FileTree } from '@astrojs/starlight/components';
 import RunGenerator from '@components/run-generator.astro';
 import GeneratorParameters from '@components/generator-parameters.astro';
+import Drawer from '@components/drawer.astro';
+import LicenseAllowlist from '@components/license-allowlist.astro';
+import NxCommands from '@components/nx-commands.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
 
-Automatically manage `LICENSE` files and source code headers in your workspace.
-
-This generator registers a [sync generator](https://nx.dev/concepts/sync-generators) to execute as part of your `lint` targets which will ensure that your source files conform to the desired license content and format, as well as ensuring that your project's `LICENSE` files are correct, and licensing information is included in relevant project files (`package.json`, `pyproject.toml`).
+Manage licensing across your workspace: synchronise `LICENSE` files and source code headers for your own code (`license.source`), and check that every dependency conforms to a license allowlist (`license.dependencies`).
 
 ## Usage
 
@@ -26,15 +28,17 @@ This generator registers a [sync generator](https://nx.dev/concepts/sync-generat
 The generator will create or update the following files:
 
 <FileTree>
-  - nx.json The lint target is configured to run the license sync generator
-  - aws-nx-plugin.config.mts Configuration for the license sync generator
+  - nx.json The lint target is configured to run the license sync generator and depends on the license-check target
+  - aws-nx-plugin.config.mts Configuration for license source sync (`license.source`) and dependency checking (`license.dependencies`)
 </FileTree>
 
-Some default configuration for license header content and format is added to `aws-nx-plugin.config.mts` to write appropriate headers for a handful of file types. You may wish to customise this further; please see the [configuration section](#configuration) below.
+## License Headers & Files
+
+The generator registers a [sync generator](https://nx.dev/concepts/sync-generators) to execute as part of your `lint` targets which ensures that your source files contain the correct license headers, your projects contain `LICENSE` files, and licensing metadata is set in `package.json` and `pyproject.toml`.
 
-## Workflow
+### Workflow
 
-Whenever you build your projects (and a `lint` target runs), the license sync generator will make sure that the licensing in your project matches your configuration (see [license sync behaviour below](#license-sync-behaviour)). If it detects that anything is out of sync, you will receive a message such as:
+Whenever you build your projects (and a `lint` target runs), the license sync generator will make sure that the licensing in your project matches your configuration. If it detects that anything is out of sync, you will receive a message such as:
 
 ```bash
   NX   The workspace is out of sync
@@ -67,40 +71,36 @@ Select `Yes` to sync the changes.
 Make sure you check the changes the license sync generator makes in to version control to ensure that any continuous integration build tasks don't fail due to licenses being out of sync.
 :::
 
-## License Sync Behaviour
+### Sync Behaviour
 
 The license sync generator performs three main tasks:
 
-### 1. Synchronise Source File License Headers
+#### 1. Synchronise Source File License Headers
 
 When the sync generator is run, it will ensure that all source code files in your workspace (based on your configuration) contain the appropriate license header. The header is written as the first block comment or consecutive series of line comments in the file (besides the shebang/hashbang if present in a file).
 
-You can update the configuration at any time to change which files should be included or excluded, as well as the content or format of license headers for different file types. For more details, please see the [configuration section](#configuration) below.
-
-### 2. Synchronise LICENSE Files
+#### 2. Synchronise LICENSE Files
 
 When the sync generator is run, it will ensure that the root `LICENSE` file corresponds to your configured license, as well as ensuring that all subprojects in your workspace also contain the correct `LICENSE` file.
 
-You can exclude projects in the configuration if required. For more details, please see the [configuration section](#configuration) below.
-
-### 3. Synchronise licensing information in project files
+#### 3. Synchronise licensing information in project files
 
 When the sync generator is run, it will ensure the `license` fields in `package.json` and `pyproject.toml` files are set to your configured license.
 
-You can exclude projects in the configuration if required. For more details, please see the [configuration section](#configuration) below.
-
-## Configuration
+### Header & File Configuration
 
 Configuration is defined in the `aws-nx-plugin.config.mts` file in the root of your workspace.
 
-### SPDX and Copyright Holder
+#### SPDX and Copyright Holder
 
 Your chosen license can be updated at any time via the `spdx` configuration property:
 
-```typescript title="aws-nx-plugin.config.mts" {3}
+```typescript title="aws-nx-plugin.config.mts" {4}
 export default {
   license: {
-    spdx: 'MIT',
+    source: {
+      spdx: 'MIT',
+    },
   },
 } satisfies AwsNxPluginConfig;
 ```
@@ -109,36 +109,38 @@ When the sync generator runs, all `LICENSE` files, `package.json` and `pyproject
 
 You can additionally configure the copyright holder and copyright year, which are included in some `LICENSE` files:
 
-```typescript title="aws-nx-plugin.config.mts" {4,5}
+```typescript title="aws-nx-plugin.config.mts" {5,6}
 export default {
   license: {
-    spdx: 'MIT',
-    copyrightHolder: 'Amazon.com, Inc. or its affiliates',
-    copyrightYear: 2025,
+    source: {
+      spdx: 'MIT',
+      copyrightHolder: 'Amazon.com, Inc. or its affiliates',
+      copyrightYear: 2025,
+    },
   },
 } satisfies AwsNxPluginConfig;
 ```
 
-### License Headers
-
-#### Content
+#### License Header Content
 
 The license header content can be configured in two ways:
 
 1. Using inline content:
 
-```typescript title="aws-nx-plugin.config.mts" {5-9}
+```typescript title="aws-nx-plugin.config.mts" {6-10}
 export default {
   license: {
-    header: {
-      content: {
-        lines: [
-          'Copyright: My Company, Incorporated.',
-          'Licensed under the MIT License',
-          'All rights reserved',
-        ];
+    source: {
+      header: {
+        content: {
+          lines: [
+            'Copyright: My Company, Incorporated.',
+            'Licensed under the MIT License',
+            'All rights reserved',
+          ];
+        }
+        // ... format configuration
       }
-      // ... format configuration
     }
   }
 } satisfies AwsNxPluginConfig;
@@ -146,51 +148,55 @@ export default {
 
 2. Loading from a file:
 
-```typescript title="aws-nx-plugin.config.mts" {5}
+```typescript title="aws-nx-plugin.config.mts" {6}
 export default {
   license: {
-    header: {
-      content: {
-        filePath: 'license-header.txt'; // relative to workspace root
+    source: {
+      header: {
+        content: {
+          filePath: 'license-header.txt'; // relative to workspace root
+        }
+        // ... format configuration
       }
-      // ... format configuration
     }
   }
 } satisfies AwsNxPluginConfig;
 ```
 
-#### Format
+#### Header Format
 
 You can specify how license headers should be formatted for different file types using glob patterns. The format configuration supports line comments, block comments, or a combination of both:
 
-```typescript title="aws-nx-plugin.config.mts" {7-29}
+```typescript title="aws-nx-plugin.config.mts" {8-30}
 export default {
   license: {
-    header: {
-      content: {
-        lines: ['Copyright notice here'],
-      },
-      format: {
-        // Line comments
-        '**/*.ts': {
-          lineStart: '// ',
-        },
-        // Block comments
-        '**/*.css': {
-          blockStart: '/*',
-          blockEnd: '*/',
+    source: {
+      header: {
+        content: {
+          lines: ['Copyright notice here'],
         },
-        // Block comments with line prefixes
-        '**/*.java': {
-          blockStart: '/*',
-          lineStart: ' * ',
-          blockEnd: ' */',
-        },
-        // Line comments with header/footer
-        '**/*.py': {
-          blockStart: '# ------------',
-          lineStart: '# ',
-          blockEnd: '# ------------',
+        format: {
+          // Line comments
+          '**/*.ts': {
+            lineStart: '// ',
+          },
+          // Block comments
+          '**/*.css': {
+            blockStart: '/*',
+            blockEnd: '*/',
+          },
+          // Block comments with line prefixes
+          '**/*.java': {
+            blockStart: '/*',
+            lineStart: ' * ',
+            blockEnd: ' */',
+          },
+          // Line comments with header/footer
+          '**/*.py': {
+            blockStart: '# ------------',
+            lineStart: '# ',
+            blockEnd: '# ------------',
+          },
         },
       },
     },
@@ -209,27 +215,29 @@ The format configuration supports:
 
 For file types that aren't natively supported, you can specify custom comment syntax to tell the sync generator how to identify existing license headers in these file types.
 
-```typescript title="aws-nx-plugin.config.mts" {12-22}
+```typescript title="aws-nx-plugin.config.mts" {13-23}
 export default {
   license: {
-    header: {
-      content: {
-        lines: ['My license header'],
-      },
-      format: {
-        '**/*.xyz': {
-          lineStart: '## ',
+    source: {
+      header: {
+        content: {
+          lines: ['My license header'],
         },
-      },
-      commentSyntax: {
-        xyz: {
-          line: '##', // Define line comment syntax
+        format: {
+          '**/*.xyz': {
+            lineStart: '## ',
+          },
         },
-        abc: {
-          block: {
-            // Define block comment syntax
-            start: '<!--',
-            end: '-->',
+        commentSyntax: {
+          xyz: {
+            line: '##', // Define line comment syntax
+          },
+          abc: {
+            block: {
+              // Define block comment syntax
+              start: '<!--',
+              end: '-->',
+            },
           },
         },
       },
@@ -238,56 +246,203 @@ export default {
 } satisfies AwsNxPluginConfig;
 ```
 
-#### Excluding files
+#### Excluding Files from Header Sync
 
 By default, in a git repository, all `.gitignore` files are honored to ensure that only files managed by version control are synchronized. In non-git repositories, all files are considered unless explicitly excluded in configuration.
 
 You can exclude additional files from license header synchronization using glob patterns:
 
-```typescript title="aws-nx-plugin.config.mts" {12-16}
+```typescript title="aws-nx-plugin.config.mts" {13}
 export default {
   license: {
-    header: {
-      content: {
-        lines: ['My license header'],
-      },
-      format: {
-        '**/*.ts': {
-          lineStart: '// ',
+    source: {
+      header: {
+        content: {
+          lines: ['My license header'],
+        },
+        format: {
+          '**/*.ts': {
+            lineStart: '// ',
+          },
         },
+        exclude: ['**/generated/**', '**/dist/**', 'some-specific-file.ts'],
       },
-      exclude: ['**/generated/**', '**/dist/**', 'some-specific-file.ts'],
     },
   },
 } satisfies AwsNxPluginConfig;
 ```
 
-### Excluding project files from sync
+#### Excluding Projects from File Sync
 
 All `LICENSE` files, `package.json` files and `pyproject.toml` files are synchronised with the configured license by default.
 
 You can exclude specific projects or files from synchronization using glob patterns:
 
-```typescript title="aws-nx-plugin.config.mts" {3-10}
+```typescript title="aws-nx-plugin.config.mts" {4-11}
 export default {
   license: {
-    files: {
-      exclude: [
-        // do not sync LICENSE file, package.json or pyproject.toml
-        'packages/excluded-project',
-        // do not sync LICENSE file, but sync package.json and/or pyproject.toml
-        'apps/internal/LICENSE',
-      ];
+    source: {
+      files: {
+        exclude: [
+          // do not sync LICENSE file, package.json or pyproject.toml
+          'packages/excluded-project',
+          // do not sync LICENSE file, but sync package.json and/or pyproject.toml
+          'apps/internal/LICENSE',
+        ];
+      }
     }
   }
 } satisfies AwsNxPluginConfig;
 ```
 
-## Disabling license sync
+### Disabling License Sync
 
-To disable the license sync generator:
+License source sync is enabled by the presence of the `license.source` key in your configuration. To disable it:
 
-1. Remove the `license` section from your configuration in `aws-nx-plugin.config.mts` (or remove the `aws-nx-plugin.config.mts` file)
-2. Remove the `@aws/nx-plugin:license#sync` generator from `targetDefaults.lint.syncGenerators`
+1. Remove the `license.source` section from your configuration in `aws-nx-plugin.config.mts` (you can keep `license.dependencies` if you still want dependency license checking)
+2. If you also want to fully remove the sync generator, remove the `@aws/nx-plugin:license#sync` generator from `targetDefaults.lint.syncGenerators`
 
 To re-enable license sync, simply run the `license` generator again.
+
+## Dependency License Checks
+
+The `license` generator also configures a `license-check` target that fails when one of your project's dependencies (or any transitive dependency) declares a license that is not in your allowlist.
+
+### How it runs
+
+The generator writes a `license-check` target to your root `project.json`:
+
+```json title="project.json"
+{
+  "targets": {
+    "license-check": {
+      "executor": "@aws/nx-plugin:license-check",
+      "cache": true,
+      "inputs": [
+        "{workspaceRoot}/pnpm-lock.yaml",
+        "{workspaceRoot}/aws-nx-plugin.config.mts"
+      ],
+      "options": {}
+    }
+  }
+}
+```
+
+The `inputs` are computed for your workspace: only lockfiles that are actually present are included, along with `aws-nx-plugin.config.mts`, plus a `{workspaceRoot}/**/uv.lock` glob when Python dependency checking is enabled (i.e. a Python collector is configured).
+
+You can run the check directly:
+
+<NxCommands commands={['license-check']} />
+
+Results are cached against your lockfiles and `aws-nx-plugin.config.mts` — re-runs are instant when nothing has changed.
+
+Collectors determine what gets scanned. The `npmCollector` uses [license-checker-rseidelsohn](https://github.com/nicedoc/license-checker-rseidelsohn), and the `pythonCollector` uses [pip-licenses](https://github.com/raimon49/pip-licenses). If no installed dependencies are found, the check passes with nothing to inspect.
+
+### Running as part of lint/build
+
+The dependency license check runs automatically whenever you `lint` or `build` any project in your workspace. The `license` generator wires each project's `lint` target to depend on the root `license-check` target, and the project generators (`ts#*` and `py#*`) do the same when they run — so the check is wired up regardless of the order generators are run in.
+
+This means you don't need to run the check explicitly, though you can still do so with the `license-check` target:
+
+<NxCommands commands={['license-check']} />
+
+The wiring is a cross-project `dependsOn` on each project's `lint` target that points at the root `license-check` target. To skip the check during a lint or build, set the `LICENSE_DEPENDENCY_CHECK=skip` environment variable:
+
+<PackageManagerShortCommand commands={["LICENSE_DEPENDENCY_CHECK=skip lint"]} />
+
+### Configuration
+
+By default the check uses a built-in set of common permissive licenses (MIT, Apache-2.0, BSD, ISC, etc.) exported as `DEFAULT_LICENSE_ALLOWLIST`. You can extend or override this in your config:
+
+```typescript title="aws-nx-plugin.config.mts"
+import { AwsNxPluginConfig } from '@aws/nx-plugin';
+import { DEFAULT_LICENSE_ALLOWLIST } from '@aws/nx-plugin/sdk/license';
+
+export default {
+  license: {
+    // ...
+    dependencies: {
+      allow: [...DEFAULT_LICENSE_ALLOWLIST, { spdxId: 'LGPL-2.1-or-later', fullName: 'GNU Lesser General Public License v2.1 or later', aliases: [] }],
+      exceptions: [
+        { package: 'some-package', reason: 'Audited manually — ships MIT text without SPDX field' },
+      ],
+    },
+  },
+} satisfies AwsNxPluginConfig;
+```
+
+<Drawer title="Default License Allowlist" trigger="View the full list of licenses in DEFAULT_LICENSE_ALLOWLIST">
+<LicenseAllowlist />
+</Drawer>
+
+#### Customizing the allowlist
+
+To restrict the allowlist, replace `DEFAULT_LICENSE_ALLOWLIST` with your own array. To extend it, spread the default and add entries. Entries are matched by SPDX id, full license name, or any of the listed aliases (case-insensitive).
+
+#### Per-package exceptions
+
+Use `exceptions` for packages that fail the check — either because their license is not in the allowlist, or because they ship without detectable license metadata. The `reason` field is required so reviewers can see why the exception was granted.
+
+```typescript
+exceptions: [
+  {
+    package: 'union',
+    version: '0.5.0',
+    reason: 'Package ships verbatim MIT text without declaring license',
+  },
+];
+```
+
+Generators that introduce dependencies with problematic metadata (e.g. the MCP server generator) automatically add the required exceptions to your config when they run.
+
+#### Collectors
+
+Collectors discover dependencies and extract license metadata. The built-in collectors are `npmCollector()` (scans `node_modules`) and `pythonCollector()` (scans Python virtual environments). The license generator configures `npmCollector()` by default and adds `pythonCollector()` when Python projects are present.
+
+To implement a custom collector, conform to the `LicenseCollector` interface:
+
+```typescript
+import type { LicenseCollector } from '@aws/nx-plugin/sdk/license';
+
+const myCollector = (): LicenseCollector => ({
+  name: 'my-ecosystem',
+  traceCommand: 'my-tool why <package>',
+  async collect({ workspaceRoot }) {
+    return [
+      { name: 'some-dep', version: '1.0.0', rawLicense: 'MIT', ecosystem: 'my-ecosystem' },
+    ];
+  },
+});
+```
+
+#### The onDependency hook
+
+`license.dependencies` accepts an optional `onDependency` callback that is invoked once for every discovered dependency, regardless of whether it passes or fails the check. It receives `{ package, spdx }`, where `package` is the package name and `spdx` is the resolved SPDX license expression. An exception's `spdx` takes precedence over the raw declared license, and `spdx` may be an empty string if no license was declared.
+
+This is a handy way to print out all of the licenses across your project. Run the `license-check` target to see the output:
+
+```typescript title="aws-nx-plugin.config.mts"
+import { AwsNxPluginConfig } from '@aws/nx-plugin';
+import { DEFAULT_LICENSE_ALLOWLIST } from '@aws/nx-plugin/sdk/license';
+
+export default {
+  license: {
+    dependencies: {
+      allow: DEFAULT_LICENSE_ALLOWLIST,
+      onDependency: ({ package: pkg, spdx }) => {
+        console.log(`${pkg} - ${spdx}`);
+      },
+    },
+  },
+} satisfies AwsNxPluginConfig;
+```
+
+### Disabling Dependency Checks
+
+Dependency license checking is enabled by the presence of the `license.dependencies` key in your configuration.
+
+To disable the checks for a single run, set the `LICENSE_DEPENDENCY_CHECK=skip` environment variable:
+
+<PackageManagerShortCommand commands={["LICENSE_DEPENDENCY_CHECK=skip lint"]} />
+
+To disable permanently, remove the `license.dependencies` key from your configuration in `aws-nx-plugin.config.mts`. You can also re-run the `license` generator with `--dependencyCheck=false` to scaffold without it.

package/docs/guides/ts-rdb.mdx

@@ -38,8 +38,8 @@ The generator will create the following project structure in the `<directory>/<n
       - example.prisma Example model definition
     - schema.prisma Main Prisma schema (references models)
   - scripts
-    - docker-pull.ts Pulls the database Docker image for local development
-    - docker-start.ts Starts a local database container
+    - pull-image.ts Pulls the database container image for local development
+    - start-container.ts Starts a local database container
     - wait-for-db.ts Waits for the local database to be ready
   - src
     - index.ts Project entry point
@@ -169,7 +169,7 @@ The client automatically:
 
 After adding or updating models under `prisma/models/`, use `migrate dev` to generate migration files and apply them to your local database at the same time.
 
-The generated `prisma` target automatically starts a local database via Docker before running:
+The generated `prisma` target automatically starts a local database container before running:
 
 <NxCommands commands={['run <project>:prisma migrate dev']} />
 
@@ -204,12 +204,26 @@ The generated `prisma` target exposes the Prisma CLI, so you can use it to run a
 
 <NxCommands commands={['run <project>:prisma <prisma-command>']} />
 
-### Prisma Studio
+### Using Prisma Studio
 
 [Prisma Studio](https://www.prisma.io/studio) is a visual editor for your local database. Use it to browse tables, inspect and edit records, filter data, follow relations, and run raw SQL via the built-in SQL console. It is useful for verifying migrations and seeding test data during development. Launch it with:
 
 <NxCommands commands={['run <project>:prisma studio']} />
 
+### Stopping the Local Database
+
+Stopping `serve-local` (e.g. with `Ctrl+C`) automatically removes the local database container, but preserves the named volume so your data persists across restarts.
+
+:::caution[Windows]
+Due to limitations with signal handling on Windows, the container is not automatically removed when `serve-local` is stopped. You will need to remove it manually:
+
+```bash
+<engine> rm -f <scope>-<db-name>
+```
+
+Replace `<engine>` with your container engine (`docker` or `finch`), `<scope>` with your Nx workspace scope (e.g. `proj`), and `<db-name>` with your database project name (e.g. `my-db`).
+:::
+
 ## Connecting to the Database
 
 In any TypeScript project, import `getPrisma` from your database package and call it to get a type-safe Prisma client:
@@ -524,9 +538,9 @@ module "my_database" {
 
 Pin a specific Aurora engine version.
 
-By default, the generated local Docker database image matches the default Aurora engine version. If you change the Aurora engine version, it's recommended to also use a matching local Docker database version for maximum compatibility. See the AWS release notes for [Aurora PostgreSQL versions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraPostgreSQLReleaseNotes/aurorapostgresql-release-calendar.html) and [Aurora MySQL versions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraMySQLReleaseNotes/AuroraMySQL.Updates.30Updates.html) to identify the corresponding community database version.
+By default, the generated local database container image matches the default Aurora engine version. If you change the Aurora engine version, it's recommended to also use a matching local container image version for maximum compatibility. See the AWS release notes for [Aurora PostgreSQL versions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraPostgreSQLReleaseNotes/aurorapostgresql-release-calendar.html) and [Aurora MySQL versions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraMySQLReleaseNotes/AuroraMySQL.Updates.30Updates.html) to identify the corresponding community database version.
 
-The local database image is configured in the generated database project's `serve-local` target in `project.json`. Update the image argument passed to `scripts/docker-start.ts` when you change engine versions.
+The local database image is configured in the generated database project's `serve-local` target in `project.json`. Update the image argument passed to `scripts/start-container.ts` when you change engine versions.
 
 <OptionFilter when={{ engine: 'postgres' }}>
 <Infrastructure>

package/docs/snippets/required-prerequisites.mdx

@@ -4,7 +4,7 @@ title: Required Prerequisites
 - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
 - [Node >= 22](https://nodejs.org/en/download) (We recommend using something like [NVM](https://github.com/nvm-sh/nvm) to manage your node versions)
   - verify by running `node --version`
-- [PNPM >= 10](https://pnpm.io/installation#using-npm) (you can also use [Yarn >= 4](https://yarnpkg.com/getting-started/install), [Bun >= 1](https://bun.sh/docs/installation), or [NPM >= 10](https://nodejs.org/en/learn/getting-started/an-introduction-to-the-npm-package-manager) if you prefer)
+- [PNPM >= 11](https://pnpm.io/installation#using-npm) (you can also use [Yarn >= 4](https://yarnpkg.com/getting-started/install), [Bun >= 1](https://bun.sh/docs/installation), or [NPM >= 10](https://nodejs.org/en/learn/getting-started/an-introduction-to-the-npm-package-manager) if you prefer)
   - verify by running `pnpm --version`, `yarn --version`, `bun --version` or `npm --version`
 - [UV >= 0.5.29](https://docs.astral.sh/uv/getting-started/installation/)
   1. install Python 3.14 by running: `uv python install 3.14.0`

package/package.json

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

package/src/license/schema.json

@@ -17,6 +17,12 @@
       "description": "The copyright holder, included in the LICENSE file and source file headers by default.",
       "default": "Amazon.com, Inc. or its affiliates",
       "x-priority": "important"
+    },
+    "dependencyCheck": {
+      "type": "boolean",
+      "description": "Configure a license-check target that fails when dependencies declare licenses outside the configured allowlist.",
+      "default": true,
+      "x-priority": "important"
     }
   },
   "required": []