@aws/nx-plugin-mcp 1.0.0-rc.49 → 1.0.0-rc.50

package/docs/get_started/concepts.mdx

@@ -39,6 +39,21 @@ This means:
 
 If you don't like something in the generated code, you are free to modify it. Generators give you a head start, not a cage.
 
+## In step with improvements
+
+Owning your code usually comes at a cost: the moment you start editing a scaffold, you're cut off from the fixes and improvements made upstream. Adopting them again means reading a changelog, regenerating, and reconciling a diff by hand. <Link path="/get_started/upgrading">Migrations</Link> are how the `@aws/nx-plugin` works to keep that from happening.
+
+Releases ship migrations alongside them, aiming to bring the code earlier generators produced into step with the improvements we've made since. When we fix a bug, harden a security default or refine a generated pattern, running `nx migrate` applies that change to your code, in place — instead of leaving you to spot it in a changelog and port it across yourself.
+
+In practice:
+
+- **Upgrading is automated, not a re-adoption exercise.** A workspace generated months ago can move forward with the plugin rather than drifting further from it.
+- **Customisations are pattern-matched, not overwritten.** Migrations check that a file still matches the shape the generator produced. Where it has diverged beyond what they can safely update, they leave your code alone and report the manual follow-up instead.
+- **Some changes arrive as agent prompts.** Where the right edit depends on what you've built, the migration is a prompt your AI coding agent applies rather than a codemod.
+- **Upgrades are opt-in.** Nothing in your workspace changes until you choose to run `nx migrate`.
+
+Migrations narrow the gap rather than close it: how far your code has moved decides how much they can do, and some steps will still need your hands.
+
 ## Minimal dependencies
 
 The `@aws/nx-plugin` strives to keep the number of global dependencies to a minimum. What you need to get started boils down to which generators you invoke.

package/docs/get_started/tutorials/dungeon-game/1.mdx

@@ -200,6 +200,7 @@ import {
   IntegrationBuilder,
   RestApiIntegration,
 } from '../../core/api/utils.js';
+import { findCloudFrontDomainNames } from '../../core/cloudfront.js';
 import { AddCorsPreflightAspect, RestApi } from '../../core/api/rest-api.js';
 import { Procedures, routerToOperations } from '../../core/api/trpc-utils.js';
 import { AppRouter, appRouter } from '@dungeon-adventure/game-api';
@@ -241,7 +242,7 @@ export class GameApi<
   public static defaultIntegrations = (scope: Construct) => {
     return IntegrationBuilder.rest({
       operations: routerToOperations(appRouter),
-      defaultIntegrationOptions: <FunctionProps>{
+      defaultIntegrationOptions: {
         runtime: Runtime.NODEJS_LATEST,
         handler: 'index.handler',
         code: Code.fromAsset(
@@ -254,7 +255,7 @@ export class GameApi<
         ),
         timeout: Duration.seconds(30),
         tracing: Tracing.ACTIVE,
-      },
+      } as FunctionProps,
       buildDefaultIntegration: (op, props: FunctionProps) => {
         const handler = new Function(scope, `GameApi${op}Handler`, props);
         return {
@@ -302,19 +303,23 @@ export class GameApi<
    *
    * Configures the CloudFront distribution domains or origin strings
    * as the only permitted CORS origins in API Gateway preflight responses and the AWS
-   * Lambda integrations.
+   * Lambda integrations. Any custom domain names (aliases) configured on a CloudFront
+   * distribution are included automatically alongside its default `*.cloudfront.net`
+   * domain.
    *
    * @param origins - The origin strings, CloudFront distributions, or objects containing a CloudFront distribution to grant CORS from
    */
   public restrictCorsTo(
     ...origins: (string | Distribution | { cloudFrontDistribution: Distribution })[]
   ) {
-    const allowedOrigins = origins.map((origin) =>
+    const allowedOrigins = origins.flatMap((origin) =>
       typeof origin === 'string'
-        ? origin
-        : 'cloudFrontDistribution' in origin
-          ? `https://${origin.cloudFrontDistribution.distributionDomainName}`
-          : `https://${origin.distributionDomainName}`,
+        ? [origin]
+        : findCloudFrontDomainNames(
+            'cloudFrontDistribution' in origin
+              ? origin.cloudFrontDistribution
+              : origin,
+          ).map((domain) => `https://${domain}`),
     );
 
     this.allowedOrigins = allowedOrigins;

package/docs/guides/nx-migration.mdx

@@ -32,9 +32,9 @@ We recommend using the <Link path="/guides/ts-nx-plugin">`ts#nx-plugin`</Link> g
 
 Migrations come in three forms, discriminated by which fields the `migrations.json` entry carries. Pass `--kind` to choose (default `deterministic`):
 
-- **Deterministic** (`implementation`) — a codemod with an exact before/after. Runs unattended, including in CI and non-interactive terminals. Use it alone when the change has a shape you can match reliably everywhere it appears.
-- **Agentic** (`prompt`) — a markdown instruction file applied by the user's local coding agent via Nx's agentic `nx migrate` flow. Use it alone when no mechanical before/after holds, because the correct edit depends on what the user has built. When no agent runs (CI, no agent installed, consent declined), Nx surfaces the prompt as manual instructions — so write prompts as self-contained, human-actionable steps.
-- **Hybrid** (`implementation` + `prompt`) — both halves of one change, and usually the right choice. Everything your generators vend is code the user owns and may have modified, so the codemod does as much as it can safely match and returns `agentContext` describing what it changed *and what it skipped*; Nx passes that context to the paired `prompt`, which directs the agent at the rest.
+- **Deterministic** (`implementation`) — a codemod with an exact before/after, and the one to reach for first. It runs unattended, including in CI and non-interactive terminals, and applies identically for every user. Use it alone when the change has a shape you can match reliably everywhere it appears, reporting anything it skipped via `nextSteps`.
+- **Hybrid** (`implementation` + `prompt`) — both halves of one change. Use it when a change is breaking and can't be fully applied mechanically: the codemod does as much as it can safely match and returns `agentContext` describing what it changed *and what it skipped*; Nx passes that context to the paired `prompt`, which directs the agent at the rest. The prompt is what stops a workspace being left broken when the leftover edits span too many shapes to codemod.
+- **Agentic** (`prompt`) — a markdown instruction file applied by the user's local coding agent via Nx's agentic `nx migrate` flow. Use it alone when no mechanical before/after holds at all, because the correct edit depends on what the user has built. When no agent runs (CI, no agent installed, consent declined), Nx surfaces the prompt as manual instructions — so write prompts as self-contained, human-actionable steps.
 
 ## Generator Output
 
@@ -84,8 +84,9 @@ For some example operations you can perform in your migration (generating files,
 
 Migrations run against workspaces you don't control, so it is recommended to adhere to the following (the scaffolded skeleton bakes these in):
 
-- **Pattern-match before writing.** If a target file has diverged from the shape your generators produce, skip it and report it via `nextSteps`, or consider a hybrid migration, rather than clobbering the user's changes.
-- **Idempotent.** Re-running the migration must be a no-op.
+- **Transform source code with GritQL.** Use the <Link path="/guides/nx-generator">GritQL helpers</Link> (`applyGritQL`, `matchGritQL`) to edit source rather than regexes or string replacements. GritQL matches the AST, so one pattern holds across the formatting, whitespace and quoting a user's copy may have drifted into, where text matching quietly misses equivalent code or corrupts the file. Use `updateJson` for JSON and the matching parser for other structured config.
+- **Pattern-match before writing.** If a target file has diverged from the shape your generators produce, skip it and report it via `nextSteps`, or consider a hybrid migration, rather than clobbering the user's changes. `matchGritQL` is a convenient way to make that check.
+- **Idempotent.** Re-running the migration must be a no-op. Guard GritQL rewrites that inject code with a `where { ... <: not contains ... }` clause so a second run doesn't append a duplicate.
 - **Format what you write.** Finish with `formatFilesInSubtree(tree)` so the files your migration wrote are formatted correctly.
 
 ### Testing Your Migration

package/package.json

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