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

package/docs/get_started/upgrading.mdx

@@ -0,0 +1,147 @@
+---
+title: Upgrading Your Workspace
+description: How to upgrade Nx and @aws/nx-plugin with nx migrate.
+---
+import { Aside } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import InstallCommand from '@components/install-command.astro';
+import NxCommands from '@components/nx-commands.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
+
+`@aws/nx-plugin` ships migrations that update your workspace automatically when you upgrade it, using [`nx migrate`](https://nx.dev/docs/features/automate-updating-dependencies).
+
+<Aside type="tip">
+You can use your agentic coding tool of choice to upgrade your workspace for you, using the <Link path="get_started/building-with-ai">MCP server</Link>. Try the prompt:
+
+> Upgrade Nx and the Nx Plugin for AWS in this workspace.
+</Aside>
+
+## Upgrading @aws/nx-plugin
+
+First, run the following command to update the plugin version and prepare migrations:
+
+<NxCommands commands={['migrate @aws/nx-plugin@latest']} />
+
+```
+ NX   The migrate command has run successfully.
+
+- package.json has been updated.
+- migrations.json has been generated.
+- 1 AI migration prompt(s) have been written to tools/ai-migrations/.
+
+ NX   Next steps:
+
+- Make sure package.json changes make sense and then run 'pnpm install --no-frozen-lockfile',
+- Review and tweak the AI migration prompts in tools/ai-migrations/ as needed.
+- Run 'pnpm exec nx migrate --run-migrations'
+- To learn more go to https://nx.dev/features/automate-updating-dependencies
+```
+
+Review the `package.json` changes then install:
+
+<InstallCommand />
+
+Then run the migrations:
+
+<NxCommands commands={['migrate --run-migrations']} />
+
+### Deterministic migrations
+
+Most migrations are deterministic codemods — they run unattended and report anything they deliberately skipped:
+
+```
+ NX   Running migrations from 'migrations.json'
+
+Running the following migrations:
+- @aws/nx-plugin: update-vitest-workspace-config — Add a coverage reporter to vitest configs
+- @aws/nx-plugin: update-custom-api-handlers — Update custom API handlers for the new middleware signature
+
+── Migration 1 of 2 · @aws/nx-plugin:update-vitest-workspace-config ─────
+→ Running generator…
+Changes:
+  UPDATE packages/api/vite.config.mts
+
+...
+
+ NX   Successfully finished running migrations from 'migrations.json'.
+
+2 migrations applied, 0 commits created.
+
+ NX   Some migrations have additional information, see below.
+
+- packages/website/vite.config.mts has a customised shape; add a coverage reporter manually.
+```
+
+Pay attention to the **additional information** at the end: when a migration finds a file you have customised beyond what it can safely update, it leaves your changes alone and reports the manual follow-up there instead.
+
+### Agentic migrations
+
+Some migrations target code you own, where the right edit depends on what you've built — these ship as prompts applied by your local AI coding agent (Claude Code, Codex or OpenCode). When any are pending, Nx asks for consent before involving an agent:
+
+```
+? Enable the agentic flow? …
+❯ Yes, just this time      Apply 1 prompt migration and validate generator output with an AI agent
+  Yes, always              Saved to nx.json so Nx won't ask again
+  No, just this time       Skip prompts and run generators without AI validation
+  No, never                Saved to nx.json so Nx won't ask again
+```
+
+If you accept, the agent applies each prompt migration in place and summarises what it changed:
+
+```
+── Migration 2 of 2 · @aws/nx-plugin:update-custom-api-handlers ─────────
+→ Running prompt with Claude Code…
+✓ update-custom-api-handlers: Updated 3 API handlers to the new middleware signature.
+```
+
+If you decline — or no agent is installed, or the run is non-interactive (e.g. CI) — the prompt migrations are skipped and saved for you to apply by hand:
+
+```
+── Migration 2 of 2 · @aws/nx-plugin:update-custom-api-handlers ─────────
+↷ Skipped — agentic flow disabled. Listed in next steps.
+
+ NX   Successfully finished running migrations from 'migrations.json'.
+
+1 migration applied, 0 commits created, 1 prompt migration skipped.
+
+ NX   Some migrations have additional information, see below.
+
+- Some prompt migrations were skipped. Review and apply each of the following
+  prompt files to the workspace, in the listed order:
+  - tools/ai-migrations/@aws/nx-plugin/2.0.0/prompt.md
+```
+
+Each skipped prompt is a self-contained markdown instruction file in `tools/ai-migrations/` — paste it into your coding agent, or follow its steps manually.
+
+Finally, verify everything still builds, then delete `migrations.json` and commit:
+
+<PackageManagerShortCommand commands={['build']} />
+
+## 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:
+
+```
+── Migration 2 of 2 · @aws/nx-plugin:update-custom-api-handlers ─────────
+↷ Skipped — deferred to the AI agent driving this run. Listed in next steps.
+
+ NX   Successfully finished running migrations from 'migrations.json'.
+
+1 migration applied, 0 commits created, 1 prompt migration deferred.
+
+ NX   Next steps for the AI agent driving this run
+
+Apply the deferred prompts below, in order:
+  1. tools/ai-migrations/@aws/nx-plugin/2.0.0/prompt.md
+       (update-custom-api-handlers — prompt-only migration)
+Then relay these migration-emitted notes to the user:
+  - packages/website/vite.config.mts has a customised shape; add a coverage reporter manually.
+Finally, summarize what was done across the run and commit the changes per workspace conventions.
+```
+
+An agent conducting an upgrade should:
+
+1. Run the cycle above for one package at a time (`nx migrate <package>@latest`, install, `nx migrate --run-migrations`), passing `--no-interactive` to suppress any remaining prompts.
+2. After the run, read each deferred prompt file listed under **Next steps**, in the listed order, and apply its steps directly to the workspace.
+3. Relay any migration-emitted notes (skipped customised files, manual follow-ups) to the user.
+4. Verify the workspace builds, then delete `migrations.json` and commit before starting the next package's upgrade.

package/docs/guides/nx-migration.mdx

@@ -0,0 +1,163 @@
+---
+title: Nx Migration Generator
+description: Generates an Nx Migration for an Nx Plugin
+generator: ts#nx-migration
+---
+
+import { FileTree } from '@astrojs/starlight/components';
+import RunGenerator from '@components/run-generator.astro';
+import NxCommands from '@components/nx-commands.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import Link from '@components/link.astro';
+
+Adds an [Nx Migration](https://nx.dev/docs/kb/migration-generators) to an Nx Plugin. Migrations let `nx migrate` automatically update projects that were generated by a previous version of your plugin when you make a breaking change — renamed targets, changed vended config, or a dependency bump that requires accompanying code changes.
+
+The generator scaffolds the migration, registers it in your plugin's `migrations.json`, and wires the `nx-migrations` field into your plugin's `package.json` (creating both if they don't exist yet).
+
+:::tip[Recommended Setup]
+We recommend using the <Link path="/guides/ts-nx-plugin">`ts#nx-plugin`</Link> generator as the base project for your migrations, since it configures a plugin project set up to publish generators and migrations.
+:::
+
+## Usage
+
+### Generate a Migration
+
+<RunGenerator generator="ts#nx-migration" />
+
+### Options
+
+<GeneratorParameters generator="ts#nx-migration" />
+
+## The three kinds of migration
+
+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.
+
+## Generator Output
+
+The generator creates the following files under your plugin project's source folder, depending on the chosen `kind`:
+
+<FileTree>
+  - src/migrations/latest/\<name>/
+    - migration.ts Codemod implementation (deterministic and hybrid)
+    - migration.spec.ts Tests for your migration (deterministic and hybrid)
+    - prompt.md Agent/human instructions (agentic and hybrid)
+  - migrations.json Created or updated to register your migration
+  - package.json Created or updated to add an "nx-migrations" entry
+</FileTree>
+
+A new migration lands in `latest/`. Grouping migrations by the release that ships them keeps their order visible at a glance as the collection grows — move a migration into a `v<x.y.z>/` folder (and update its paths in `migrations.json`) when you assign its version.
+
+It registers the migration in `migrations.json` with the fields for its kind and no `version` — see [Versioning](#versioning) below. The registered key is prefixed with the folder the migration lives in (`latest-<name>`), so reusing a name for a later change can't silently overwrite a migration that has already shipped.
+
+## Implementing a Migration
+
+A deterministic (or hybrid) migration is a function which mutates the virtual filesystem (the `Tree`), returning a [`MigrationReturnObject`](https://nx.dev/docs/reference/devkit/MigrationReturnObject). Here's a hybrid one, which returns both:
+
+```ts
+import { type MigrationReturnObject, type Tree } from '@nx/devkit';
+import { formatFilesInSubtree } from '@aws/nx-plugin/sdk/utils/format';
+
+export default async function migration(
+  tree: Tree,
+): Promise<MigrationReturnObject> {
+  const nextSteps: string[] = [];
+  const agentContext: string[] = [];
+
+  // Read and update the files your generators produce here.
+
+  await formatFilesInSubtree(tree);
+
+  return { nextSteps, agentContext };
+}
+```
+
+- **`nextSteps`** — workspace-wide notes surfaced to the user after `nx migrate` runs. Use these to report files you skipped (see the guardrails below) or manual follow-up the migration couldn't perform.
+- **`agentContext`** (hybrid only) — a summary of what the codemod changed, passed to the paired `prompt` when it runs under Nx's agentic flow so the agent can focus on the user-owned parts.
+
+For some example operations you can perform in your migration (generating files, modifying existing files using GritQL, reading and updating JSON), refer to the <Link path="/guides/nx-generator">Nx Generator guide</Link>.
+
+### Guardrails
+
+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.
+- **Format what you write.** Finish with `formatFilesInSubtree(tree)` so the files your migration wrote are formatted correctly.
+
+### Testing Your Migration
+
+The scaffolded `migration.spec.ts` uses `createTreeUsingTsSolutionSetup()` to build a virtual workspace matching the shape our preset generates. Test that the migration takes a workspace from the "before" state to the target state, skips (and reports) code it doesn't recognise, and is idempotent:
+
+```ts
+import type { Tree } from '@nx/devkit';
+import { createTreeUsingTsSolutionSetup } from '@aws/nx-plugin/sdk/utils/test';
+import migration from './migration';
+
+describe('my migration', () => {
+  let tree: Tree;
+
+  beforeEach(() => {
+    tree = createTreeUsingTsSolutionSetup();
+  });
+
+  it('should update the generated shape', async () => {
+    // Set up a tree with the "before" state
+    tree.write('project.json', JSON.stringify({ targets: { foo: {} } }));
+
+    // Run the migration
+    await migration(tree);
+
+    // Check that the tree matches the target state
+    const projectJson = JSON.parse(tree.read('project.json', 'utf-8'));
+    expect(projectJson.targets).toHaveProperty('bar');
+    expect(projectJson.targets).not.toHaveProperty('foo');
+  });
+});
+```
+
+Unit tests only prove the migration does what you wrote it to do. Also test it against a workspace generated by the **published** version of your plugin — the state your users upgrade from — and confirm the result matches what your generators produce today: inspect the diff, generate the same projects into a fresh workspace and compare, check the workspace still builds, then re-run the migration to confirm it changes nothing. Repeat with a workspace you've customised first, to check the migration leaves your edits alone and reports them instead.
+
+## Versioning
+
+Nx runs a migration when the user's installed plugin version is less than the migration's `version`. This generator writes **no** `version` field — assign it (or stamp it from your release process) when you cut the release that ships the migration, so it runs for everyone upgrading from an earlier version.
+
+Once you assign versions, a `migrations.json` registering one migration of each kind looks like this:
+
+```json
+{
+  "$schema": "http://json-schema.org/schema",
+  "name": "my-plugin",
+  "generators": {
+    "v2.0.0-rename-foo-target": {
+      "version": "2.0.0",
+      "description": "Rename the foo target to bar",
+      "implementation": "./src/migrations/v2.0.0/rename-foo-target/migration"
+    },
+    "v3.0.0-migrate-custom-handlers": {
+      "version": "3.0.0",
+      "description": "Update custom handlers for the new API",
+      "prompt": "./src/migrations/v3.0.0/migrate-custom-handlers/prompt.md"
+    },
+    "v4.0.0-upgrade-framework": {
+      "version": "4.0.0",
+      "description": "Upgrade the framework and reconcile call sites",
+      "implementation": "./src/migrations/v4.0.0/upgrade-framework/migration",
+      "prompt": "./src/migrations/v4.0.0/upgrade-framework/prompt.md"
+    }
+  }
+}
+```
+
+## Running Migrations
+
+Users apply your plugin's migrations with the two-step `nx migrate` flow — generate the pending migrations, install, then run them:
+
+<NxCommands commands={['migrate my-plugin@latest', 'migrate --run-migrations']} />
+
+Agentic and hybrid migrations are applied by the user's local coding agent during `nx migrate --run-migrations` when one is available.
+
+For the full flow from the upgrading user's perspective — including example output for deterministic and agentic migrations — see <Link path="get_started/upgrading">Upgrading Your Workspace</Link>.

package/generators.json

@@ -231,6 +231,13 @@
       "metric": "g17",
       "guidePages": ["nx-generator"]
     },
+    "ts#nx-migration": {
+      "factory": "./src/ts/nx-migration/generator",
+      "schema": "./src/ts/nx-migration/schema.json",
+      "description": "Generator for adding an Nx Migration to an Nx Plugin, applied by nx migrate when users upgrade",
+      "metric": "g68",
+      "guidePages": ["nx-migration"]
+    },
     "ts#nx-plugin": {
       "factory": "./src/ts/nx-plugin/generator",
       "schema": "./src/ts/nx-plugin/schema.json",

package/package.json

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

package/src/ts/nx-migration/schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "TsNxMigration",
+  "title": "Create an Nx Migration",
+  "description": "Scaffold a migration for an Nx Plugin, applied by nx migrate when users upgrade",
+  "type": "object",
+  "properties": {
+    "project": {
+      "type": "string",
+      "description": "The Nx Plugin project to add the migration to. We recommend using the ts#nx-plugin generator to create this.",
+      "x-priority": "important",
+      "x-prompt": "Choose the Nx Plugin project to add the migration to",
+      "x-dropdown": "projects",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      }
+    },
+    "name": {
+      "type": "string",
+      "description": "Migration name, in kebab-case (e.g. rename-foo-target)",
+      "x-priority": "important",
+      "x-prompt": "What is the name of the migration? (kebab-case, e.g. rename-foo-target)"
+    },
+    "description": {
+      "type": "string",
+      "description": "A description of what the migration does, shown by nx migrate",
+      "x-priority": "important",
+      "x-prompt": "Describe what the migration does"
+    },
+    "kind": {
+      "type": "string",
+      "description": "The kind of migration: deterministic (a codemod), agentic (an AI-applied prompt for user-owned code), or hybrid (a codemod that does the mechanical part then hands off to an agent)",
+      "enum": ["deterministic", "agentic", "hybrid"],
+      "default": "deterministic",
+      "x-priority": "important",
+      "x-prompt": {
+        "message": "What kind of migration is this?",
+        "type": "list",
+        "items": [
+          {
+            "value": "deterministic",
+            "label": "Deterministic — a codemod with an exact before/after (runs unattended, incl. CI)"
+          },
+          {
+            "value": "agentic",
+            "label": "Agentic — an AI-applied prompt for changes to user-owned code"
+          },
+          {
+            "value": "hybrid",
+            "label": "Hybrid — a codemod for the mechanical part that hands off to an agent for the rest"
+          }
+        ]
+      }
+    },
+    "preferInstallDependencies": {
+      "type": "boolean",
+      "description": "Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.",
+      "default": true
+    }
+  },
+  "required": ["project", "name"]
+}