@aws/nx-plugin 1.0.0-rc.7 → 1.0.0-rc.71

package/src/ts/nx-migration/files/migration.ts.template

@@ -0,0 +1,65 @@
+import { type MigrationReturnObject, type Tree } from '@nx/devkit';
+import { formatFilesInSubtree } from '<%- formatImportPath %>';
+
+/**
+ * <%= description %>
+<%_ if (isHybrid) { _%>
+ *
+ * Hybrid migration: this codemod does the mechanical part, then the paired
+ * prompt (prompt.md) hands off to the user's agent for the rest.
+ *
+ * How to write a migration:
+ * - https://nx.dev/docs/kb/migration-generators
+ * - `nextSteps` and `agentContext`: https://nx.dev/docs/reference/devkit/MigrationReturnObject
+ *
+ * Guardrails:
+ * - Transform source with GritQL (`applyGritQL`, `matchGritQL`), not regexes or
+ *   string replacements: it matches the AST, so it holds up against however the
+ *   user's copy has been formatted. Use `updateJson` for JSON.
+ * - Pattern-match before writing: skip files that have diverged from the shape
+ *   your generators produce, and report them via `agentContext` so the prompt
+ *   can pick them up, rather than clobbering the user's changes.
+ * - `nextSteps` is for work left for the user to do by hand, not a log of the
+ *   edits you made: an edit that applied cleanly needs no entry.
+ * - Idempotent: re-running must be a no-op.
+ * - Format what you write: finish with `formatFilesInSubtree` so the files your
+ *   migration wrote are formatted correctly.
+ */
+<%_ } else { _%>
+ *
+ * How to write a migration:
+ * - https://nx.dev/docs/kb/migration-generators
+ * - What `nextSteps` means: https://nx.dev/docs/reference/devkit/MigrationReturnObject
+ *
+ * Guardrails:
+ * - Transform source with GritQL (`applyGritQL`, `matchGritQL`), not regexes or
+ *   string replacements: it matches the AST, so it holds up against however the
+ *   user's copy has been formatted. Use `updateJson` for JSON.
+ * - Pattern-match before writing: skip files that have diverged from the shape
+ *   your generators produce and report them via `nextSteps`, or consider a
+ *   hybrid migration, rather than clobbering the user's changes.
+ * - `nextSteps` is for work left for the user to do by hand, not a log of the
+ *   edits you made: an edit that applied cleanly needs no entry.
+ * - Idempotent: re-running must be a no-op.
+ * - Format what you write: finish with `formatFilesInSubtree` so the files your
+ *   migration wrote are formatted correctly.
+ */
+<%_ } _%>
+export default async function migration(
+  tree: Tree,
+): Promise<MigrationReturnObject> {
+  const nextSteps: string[] = [];
+<% if (isHybrid) { %>  const agentContext: string[] = [];
+<% } %>
+  // TODO: read the workspace's files and update the ones matching the shape
+  // your generators produce, noting any you skip in `nextSteps`.
+<% if (isHybrid) { %>
+  // `agentContext` reaches the paired prompt under `--agentic` and is dropped
+  // otherwise.
+  // TODO: describe what changed in `agentContext`, e.g.:
+  // agentContext.push('Renamed the `foo` target to `bar` in every project.json.');
+<% } %>
+  await formatFilesInSubtree(tree);
+
+  return { nextSteps<% if (isHybrid) { %>, agentContext<% } %> };
+}

package/src/ts/nx-migration/files/prompt.md.template

@@ -0,0 +1,46 @@
+<%_ if (isHybrid) { _%>
+<!-- Authoring guide (delete before shipping): this file is the `prompt` for the
+agentic half of a hybrid migration. The codemod half (migration.ts) has already
+run its mechanical changes and passes a summary via `agentContext`. The prompt is
+applied by the user's AI coding agent, and shown verbatim to users who run
+`nx migrate` without one, so write self-contained, human-actionable steps.
+See https://nx.dev/docs/kb/migration-generators -->
+<%_ } else { _%>
+<!-- Authoring guide (delete before shipping): this file is the `prompt` for an
+agentic migration. It is applied by the user's AI coding agent, and shown
+verbatim to users who run `nx migrate` without one, so write self-contained,
+human-actionable steps.
+See https://nx.dev/docs/kb/migration-generators -->
+<%_ } _%>
+
+# <%= description %>
+
+## Overview
+
+<%_ if (isHybrid) { _%>
+<!-- TODO: describe the breaking change and what remains to be done in
+user-owned code after the codemod has run. -->
+<%_ } else { _%>
+<!-- TODO: describe the breaking change and what the workspace needs to end up
+looking like. -->
+<%_ } _%>
+
+## Steps
+
+<%_ if (isHybrid) { _%>
+1. <!-- TODO: identify the user-owned call sites the codemod could not update
+   (e.g. "handlers that call the renamed API"). -->
+<%_ } else { _%>
+1. <!-- TODO: identify the files/patterns affected (e.g. "search for `oldApi(`
+   across the workspace"). -->
+<%_ } _%>
+2. <!-- TODO: describe the transformation with before/after examples. -->
+3. <!-- TODO: how to verify: run `nx run-many --target build --all` (and any
+   relevant tests) and confirm they pass. -->
+
+## Guard rails
+
+- Only change what these instructions describe. Do not reformat unrelated code.
+- Do not weaken or delete tests to make them pass.
+- If a file has been customised in a way these instructions don't cover, leave
+  it and note it for the user rather than guessing.

package/src/ts/nx-migration/generator.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type GeneratorCallback, type Tree } from '@nx/devkit';
+import { type NxGeneratorInfo } from '../../utils/nx';
+import type { TsNxMigrationGeneratorSchema } from './schema';
+export declare const DEPENDENCIES: import("../../utils/declared-dependencies").DependencyDeclaration<readonly [{
+    readonly name: "@nx/devkit";
+}], readonly import("../../utils/declared-dependencies").DeclaredPyDependency<"a2a-sdk" | "ag-ui-langgraph" | "ag-ui-protocol" | "ag-ui-strands" | "aws-lambda-powertools" | "aws-lambda-powertools[tracer]" | "aws-lambda-powertools[parser]" | "aws-opentelemetry-distro" | "bedrock-agentcore" | "boto3" | "checkov" | "fastapi" | "fastapi[standard]" | "httpx" | "langchain" | "langchain-aws" | "langchain-mcp-adapters" | "langgraph" | "mcp" | "pip-check-updates" | "pip-licenses" | "ruff" | "strands-agents" | "strands-agents[a2a]" | "strands-agents-tools" | "ty" | "pynamodb" | "uvicorn" | "sqlmodel" | "alembic" | "aiomysql" | "asyncpg" | "greenlet", Record<string, never>>[]>;
+export declare const NX_MIGRATION_GENERATOR_INFO: NxGeneratorInfo;
+/**
+ * Scaffolds a migration in an Nx Plugin project and registers it in the
+ * plugin's `migrations.json` (creating the manifest and wiring the
+ * `nx-migrations` field into the plugin's `package.json` if absent), so
+ * `nx migrate` applies it when users upgrade the plugin.
+ *
+ * Supports all three migration kinds:
+ * - `deterministic`: a codemod (`implementation`).
+ * - `agentic`: a `prompt` markdown file applied by the user's agent.
+ * - `hybrid`: both — the codemod does the mechanical part and returns
+ *   `agentContext`, then the prompt hands off to the agent for the rest.
+ *
+ * No `version` is written — the plugin author stamps versions at release time.
+ */
+export declare const tsNxMigrationGenerator: (tree: Tree, options: TsNxMigrationGeneratorSchema) => Promise<GeneratorCallback | void>;
+export default tsNxMigrationGenerator;

package/src/ts/nx-migration/generator.js

@@ -0,0 +1,147 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { generateFiles, joinPathFragments, OverwriteStrategy, readJson, writeJson } from "@nx/devkit";
+import PackageJson from "../../../package.json" with {
+    type: 'json'
+};
+import { declareDependencies } from "../../utils/declared-dependencies.js";
+import { formatFilesInSubtree } from "../../utils/format.js";
+import { installDependencies } from "../../utils/install.js";
+import { addGeneratorMetricsIfApplicable } from "../../utils/metrics.js";
+import { LATEST_MIGRATIONS_DIR, migrationKey } from "../../utils/migration-versions.js";
+import { isEsmWorkspace } from "../../utils/module-format.js";
+import { kebabCase } from "../../utils/names.js";
+import { getGeneratorInfo, isNxPluginForAwsWorkspace } from "../../utils/nx.js";
+import { sortObjectKeys } from "../../utils/object.js";
+import { addNxPluginDependencies, configureNxPluginPackageJson, NX_PLUGIN_DEPENDENCIES, readNxPluginProject } from "../nx-plugin/utils.js";
+export const DEPENDENCIES = declareDependencies()({
+    ts: [
+        ...NX_PLUGIN_DEPENDENCIES
+    ]
+});
+export const NX_MIGRATION_GENERATOR_INFO = getGeneratorInfo(import.meta.filename);
+/**
+ * Scaffolds a migration in an Nx Plugin project and registers it in the
+ * plugin's `migrations.json` (creating the manifest and wiring the
+ * `nx-migrations` field into the plugin's `package.json` if absent), so
+ * `nx migrate` applies it when users upgrade the plugin.
+ *
+ * Supports all three migration kinds:
+ * - `deterministic`: a codemod (`implementation`).
+ * - `agentic`: a `prompt` markdown file applied by the user's agent.
+ * - `hybrid`: both — the codemod does the mechanical part and returns
+ *   `agentContext`, then the prompt hands off to the agent for the rest.
+ *
+ * No `version` is written — the plugin author stamps versions at release time.
+ */ export const tsNxMigrationGenerator = async (tree, options)=>{
+    const name = kebabCase(options.name);
+    // Shown by `nx migrate` when the migration runs, so it needs to say something
+    const description = options.description ?? 'TODO: Add short description of the migration';
+    const kind = options.kind ?? 'deterministic';
+    const hasImplementation = kind === 'deterministic' || kind === 'hybrid';
+    const hasPrompt = kind === 'agentic' || kind === 'hybrid';
+    const isHybrid = kind === 'hybrid';
+    const plugin = readNxPluginProject(tree, options.project);
+    const sourceRoot = plugin.sourceRoot ?? joinPathFragments(plugin.root, 'src');
+    const srcDir = sourceRoot.split('/').filter(Boolean).pop();
+    // Migrations are grouped by the release that ships them. A new one lands in
+    // `latest` — the release that picks it up moves it into its version folder.
+    const migrationPath = `${srcDir}/migrations/${LATEST_MIGRATIONS_DIR}/${name}`;
+    const migrationDir = joinPathFragments(sourceRoot, 'migrations', LATEST_MIGRATIONS_DIR, name);
+    const key = migrationKey(LATEST_MIGRATIONS_DIR, name);
+    const isNxPluginForAws = isNxPluginForAwsWorkspace(tree);
+    // Point the plugin at its migrations manifest so `nx migrate` finds them
+    const pluginPackageJsonPath = configureNxPluginPackageJson(tree, plugin, 'nx-migrations', {
+        migrations: './migrations.json'
+    });
+    // Migrations sit three levels below the source root, so in this repo the
+    // shared utils are relative. Elsewhere they come from the SDK.
+    const formatImportPath = isNxPluginForAws ? '../../../utils/format' : `${PackageJson.name}/sdk/utils/format`;
+    const testImportPath = isNxPluginForAws ? '../../../utils/test' : `${PackageJson.name}/sdk/utils/test`;
+    // A generated workspace resolves with `nodenext`, which needs the explicit
+    // extension on the spec's sibling import; this repo resolves with `bundler`,
+    // which takes it extensionless.
+    const esm = !isNxPluginForAws && isEsmWorkspace(tree);
+    // One template set covers all kinds — scaffold it, then prune what this kind
+    // doesn't use.
+    generateFiles(tree, joinPathFragments(import.meta.dirname, 'files'), migrationDir, {
+        name,
+        description,
+        isHybrid,
+        formatImportPath,
+        testImportPath,
+        esm
+    }, {
+        overwriteStrategy: OverwriteStrategy.KeepExisting
+    });
+    if (!hasImplementation) {
+        tree.delete(joinPathFragments(migrationDir, 'migration.ts'));
+        tree.delete(joinPathFragments(migrationDir, 'migration.spec.ts'));
+    }
+    if (!hasPrompt) {
+        tree.delete(joinPathFragments(migrationDir, 'prompt.md'));
+    }
+    if (isNxPluginForAws) {
+        // In the plugin's own repo migrations.json is assembled from these folders
+        // at build time (see utils/migration-manifest.ts), so registration is just
+        // the description beside the code — its kind comes from the files present.
+        // Two migration PRs then touch disjoint files rather than one shared manifest.
+        const metadataPath = joinPathFragments(migrationDir, 'metadata.json');
+        if (!tree.exists(metadataPath)) {
+            writeJson(tree, metadataPath, {
+                description
+            });
+        }
+    } else {
+        // Elsewhere, register the migration under its folder-prefixed key. The fields
+        // present discriminate the kind for nx, and paths are relative to
+        // migrations.json. No version is written, but an already-stamped one is kept.
+        const migrationsJsonPath = joinPathFragments(plugin.root, 'migrations.json');
+        const migrationsJson = tree.exists(migrationsJsonPath) ? readJson(tree, migrationsJsonPath) : {
+            $schema: 'http://json-schema.org/schema',
+            name: readJson(tree, pluginPackageJsonPath).name ?? plugin.name,
+            generators: {}
+        };
+        writeJson(tree, migrationsJsonPath, {
+            ...migrationsJson,
+            generators: sortObjectKeys({
+                ...migrationsJson.generators,
+                [key]: {
+                    ...migrationsJson.generators?.[key]?.version ? {
+                        version: migrationsJson.generators[key].version
+                    } : {},
+                    description,
+                    ...hasImplementation ? {
+                        implementation: `./${migrationPath}/migration`
+                    } : {},
+                    ...hasPrompt ? {
+                        prompt: `./${migrationPath}/prompt.md`
+                    } : {}
+                }
+            })
+        });
+    }
+    // Codemods import @nx/devkit and the @aws/nx-plugin SDK, both of which must
+    // resolve for nx to run them
+    if (hasImplementation) {
+        addNxPluginDependencies(tree, pluginPackageJsonPath, DEPENDENCIES);
+    }
+    await addGeneratorMetricsIfApplicable(tree, [
+        NX_MIGRATION_GENERATOR_INFO
+    ]);
+    await formatFilesInSubtree(tree);
+    if (hasImplementation && !isNxPluginForAws) {
+        return ()=>installDependencies(tree, options.preferInstallDependencies, {
+                languages: [
+                    'typescript'
+                ],
+                ensureResolvable: [
+                    '@nx/devkit'
+                ]
+            });
+    }
+};
+export default tsNxMigrationGenerator;
+
+//# sourceMappingURL=generator.js.map

package/src/ts/nx-migration/generator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../packages/nx-plugin/src/ts/nx-migration/generator.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  type GeneratorCallback,\n  generateFiles,\n  joinPathFragments,\n  OverwriteStrategy,\n  readJson,\n  type Tree,\n  writeJson,\n} from '@nx/devkit';\nimport PackageJson from '../../../package.json' with { type: 'json' };\nimport { declareDependencies } from '../../utils/declared-dependencies';\nimport { formatFilesInSubtree } from '../../utils/format';\nimport { installDependencies } from '../../utils/install';\nimport { addGeneratorMetricsIfApplicable } from '../../utils/metrics';\nimport {\n  LATEST_MIGRATIONS_DIR,\n  migrationKey,\n} from '../../utils/migration-versions';\nimport { isEsmWorkspace } from '../../utils/module-format';\nimport { kebabCase } from '../../utils/names';\nimport {\n  getGeneratorInfo,\n  isNxPluginForAwsWorkspace,\n  type NxGeneratorInfo,\n} from '../../utils/nx';\nimport { sortObjectKeys } from '../../utils/object';\nimport {\n  addNxPluginDependencies,\n  configureNxPluginPackageJson,\n  NX_PLUGIN_DEPENDENCIES,\n  readNxPluginProject,\n} from '../nx-plugin/utils';\nimport type { TsNxMigrationGeneratorSchema } from './schema';\n\nexport const DEPENDENCIES = declareDependencies()({\n  ts: [...NX_PLUGIN_DEPENDENCIES],\n});\n\nexport const NX_MIGRATION_GENERATOR_INFO: NxGeneratorInfo = getGeneratorInfo(\n  import.meta.filename,\n);\n\n/**\n * Scaffolds a migration in an Nx Plugin project and registers it in the\n * plugin's `migrations.json` (creating the manifest and wiring the\n * `nx-migrations` field into the plugin's `package.json` if absent), so\n * `nx migrate` applies it when users upgrade the plugin.\n *\n * Supports all three migration kinds:\n * - `deterministic`: a codemod (`implementation`).\n * - `agentic`: a `prompt` markdown file applied by the user's agent.\n * - `hybrid`: both — the codemod does the mechanical part and returns\n *   `agentContext`, then the prompt hands off to the agent for the rest.\n *\n * No `version` is written — the plugin author stamps versions at release time.\n */\nexport const tsNxMigrationGenerator = async (\n  tree: Tree,\n  options: TsNxMigrationGeneratorSchema,\n): Promise<GeneratorCallback | void> => {\n  const name = kebabCase(options.name);\n  // Shown by `nx migrate` when the migration runs, so it needs to say something\n  const description =\n    options.description ?? 'TODO: Add short description of the migration';\n  const kind = options.kind ?? 'deterministic';\n\n  const hasImplementation = kind === 'deterministic' || kind === 'hybrid';\n  const hasPrompt = kind === 'agentic' || kind === 'hybrid';\n  const isHybrid = kind === 'hybrid';\n\n  const plugin = readNxPluginProject(tree, options.project);\n\n  const sourceRoot = plugin.sourceRoot ?? joinPathFragments(plugin.root, 'src');\n  const srcDir = sourceRoot.split('/').filter(Boolean).pop();\n  // Migrations are grouped by the release that ships them. A new one lands in\n  // `latest` — the release that picks it up moves it into its version folder.\n  const migrationPath = `${srcDir}/migrations/${LATEST_MIGRATIONS_DIR}/${name}`;\n  const migrationDir = joinPathFragments(\n    sourceRoot,\n    'migrations',\n    LATEST_MIGRATIONS_DIR,\n    name,\n  );\n  const key = migrationKey(LATEST_MIGRATIONS_DIR, name);\n\n  const isNxPluginForAws = isNxPluginForAwsWorkspace(tree);\n\n  // Point the plugin at its migrations manifest so `nx migrate` finds them\n  const pluginPackageJsonPath = configureNxPluginPackageJson(\n    tree,\n    plugin,\n    'nx-migrations',\n    { migrations: './migrations.json' },\n  );\n\n  // Migrations sit three levels below the source root, so in this repo the\n  // shared utils are relative. Elsewhere they come from the SDK.\n  const formatImportPath = isNxPluginForAws\n    ? '../../../utils/format'\n    : `${PackageJson.name}/sdk/utils/format`;\n  const testImportPath = isNxPluginForAws\n    ? '../../../utils/test'\n    : `${PackageJson.name}/sdk/utils/test`;\n  // A generated workspace resolves with `nodenext`, which needs the explicit\n  // extension on the spec's sibling import; this repo resolves with `bundler`,\n  // which takes it extensionless.\n  const esm = !isNxPluginForAws && isEsmWorkspace(tree);\n\n  // One template set covers all kinds — scaffold it, then prune what this kind\n  // doesn't use.\n  generateFiles(\n    tree,\n    joinPathFragments(import.meta.dirname, 'files'),\n    migrationDir,\n    {\n      name,\n      description,\n      isHybrid,\n      formatImportPath,\n      testImportPath,\n      esm,\n    },\n    { overwriteStrategy: OverwriteStrategy.KeepExisting },\n  );\n  if (!hasImplementation) {\n    tree.delete(joinPathFragments(migrationDir, 'migration.ts'));\n    tree.delete(joinPathFragments(migrationDir, 'migration.spec.ts'));\n  }\n  if (!hasPrompt) {\n    tree.delete(joinPathFragments(migrationDir, 'prompt.md'));\n  }\n\n  if (isNxPluginForAws) {\n    // In the plugin's own repo migrations.json is assembled from these folders\n    // at build time (see utils/migration-manifest.ts), so registration is just\n    // the description beside the code — its kind comes from the files present.\n    // Two migration PRs then touch disjoint files rather than one shared manifest.\n    const metadataPath = joinPathFragments(migrationDir, 'metadata.json');\n    if (!tree.exists(metadataPath)) {\n      writeJson(tree, metadataPath, { description });\n    }\n  } else {\n    // Elsewhere, register the migration under its folder-prefixed key. The fields\n    // present discriminate the kind for nx, and paths are relative to\n    // migrations.json. No version is written, but an already-stamped one is kept.\n    const migrationsJsonPath = joinPathFragments(\n      plugin.root,\n      'migrations.json',\n    );\n    const migrationsJson = tree.exists(migrationsJsonPath)\n      ? readJson(tree, migrationsJsonPath)\n      : {\n          $schema: 'http://json-schema.org/schema',\n          name: readJson(tree, pluginPackageJsonPath).name ?? plugin.name,\n          generators: {},\n        };\n    writeJson(tree, migrationsJsonPath, {\n      ...migrationsJson,\n      generators: sortObjectKeys({\n        ...migrationsJson.generators,\n        [key]: {\n          ...(migrationsJson.generators?.[key]?.version\n            ? { version: migrationsJson.generators[key].version }\n            : {}),\n          description,\n          ...(hasImplementation\n            ? { implementation: `./${migrationPath}/migration` }\n            : {}),\n          ...(hasPrompt ? { prompt: `./${migrationPath}/prompt.md` } : {}),\n        },\n      }),\n    });\n  }\n\n  // Codemods import @nx/devkit and the @aws/nx-plugin SDK, both of which must\n  // resolve for nx to run them\n  if (hasImplementation) {\n    addNxPluginDependencies(tree, pluginPackageJsonPath, DEPENDENCIES);\n  }\n\n  await addGeneratorMetricsIfApplicable(tree, [NX_MIGRATION_GENERATOR_INFO]);\n\n  await formatFilesInSubtree(tree);\n\n  if (hasImplementation && !isNxPluginForAws) {\n    return () =>\n      installDependencies(tree, options.preferInstallDependencies, {\n        languages: ['typescript'],\n        ensureResolvable: ['@nx/devkit'],\n      });\n  }\n};\n\nexport default tsNxMigrationGenerator;\n"],"names":["generateFiles","joinPathFragments","OverwriteStrategy","readJson","writeJson","PackageJson","type","declareDependencies","formatFilesInSubtree","installDependencies","addGeneratorMetricsIfApplicable","LATEST_MIGRATIONS_DIR","migrationKey","isEsmWorkspace","kebabCase","getGeneratorInfo","isNxPluginForAwsWorkspace","sortObjectKeys","addNxPluginDependencies","configureNxPluginPackageJson","NX_PLUGIN_DEPENDENCIES","readNxPluginProject","DEPENDENCIES","ts","NX_MIGRATION_GENERATOR_INFO","filename","tsNxMigrationGenerator","tree","options","name","description","kind","hasImplementation","hasPrompt","isHybrid","plugin","project","sourceRoot","root","srcDir","split","filter","Boolean","pop","migrationPath","migrationDir","key","isNxPluginForAws","pluginPackageJsonPath","migrations","formatImportPath","testImportPath","esm","dirname","overwriteStrategy","KeepExisting","delete","metadataPath","exists","migrationsJsonPath","migrationsJson","$schema","generators","version","implementation","prompt","preferInstallDependencies","languages","ensureResolvable"],"mappings":"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"}

package/src/ts/nx-migration/schema.d.js

@@ -0,0 +1,6 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ export { };
+
+//# sourceMappingURL=schema.d.js.map

package/src/ts/nx-migration/schema.d.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../packages/nx-plugin/src/ts/nx-migration/schema.d.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nexport type NxMigrationKind = 'deterministic' | 'agentic' | 'hybrid';\n\nexport interface TsNxMigrationGeneratorSchema {\n  project: string;\n  name: string;\n  description?: string;\n  kind?: NxMigrationKind;\n  preferInstallDependencies?: boolean;\n}\n"],"names":[],"mappings":"AAAA;;;CAGC,GAGD,WAMC"}

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

@@ -0,0 +1,13 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export type NxMigrationKind = 'deterministic' | 'agentic' | 'hybrid';
+
+export interface TsNxMigrationGeneratorSchema {
+  project: string;
+  name: string;
+  description?: string;
+  kind?: NxMigrationKind;
+  preferInstallDependencies?: boolean;
+}

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"]
+}

package/src/ts/nx-plugin/__snapshots__/generator.spec.ts.snap

@@ -2,7 +2,7 @@
 
 exports[`ts#nx-plugin generator > should generate MCP server files > test-plugin/src/mcp-server/http.ts 1`] = `
 "#!/usr/bin/env node
-import { createServer } from './server';
+import { createServer } from './server.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import express, { Request, Response } from 'express';
 
@@ -90,7 +90,7 @@ void (async () => {
 `;
 
 exports[`ts#nx-plugin generator > should generate MCP server files > test-plugin/src/mcp-server/index.ts 1`] = `
-"export * from './server';
+"export * from './server.js';
 "
 `;
 
@@ -123,12 +123,11 @@ exports[`ts#nx-plugin generator > should generate MCP server files > test-plugin
 
 ## General Instructions
 
-- Workspaces contain a single \`package.json\` file at the root which defines the dependencies for all projects. Therefore when installing dependencies, you must add these to the root workspace using the appropriate command for your package manager:
-  - pnpm add -w -D <package>
-  - yarn add -D <package>
-  - npm install --legacy-peer-deps -D <package>
-  - bun install -D <package>
-  - (Omit -D for production dependencies)
+- Each project declares the third-party runtime dependencies its source imports in its own \`package.json\`; shared build/test tooling 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:
+  - 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>\`
+  - 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>\`
+- The \`noUndeclaredDependencies\` lint rule enforces that a project's source only imports packages declared in its own \`package.json\`
+- 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
 - 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
 - When no generator exists for a specific framework required, look for more generic project generators if availalbe and build on top of these.
 
@@ -157,11 +156,11 @@ export const PackageManagerSchema = z.enum(PACKAGE_MANAGERS);
 
 exports[`ts#nx-plugin generator > should generate MCP server files > test-plugin/src/mcp-server/server.ts 1`] = `
 "import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { registerCreateWorkspaceCommandTool } from './tools/create-workspace-command';
-import { registerGeneralGuidanceTool } from './tools/general-guidance';
-import { registerListGeneratorsTool } from './tools/list-generators';
-import { registerGeneratorGuideTool } from './tools/generator-guide';
-import { getPackageName } from './utils';
+import { registerCreateWorkspaceCommandTool } from './tools/create-workspace-command.js';
+import { registerGeneralGuidanceTool } from './tools/general-guidance.js';
+import { registerListGeneratorsTool } from './tools/list-generators.js';
+import { registerGeneratorGuideTool } from './tools/generator-guide.js';
+import { getPackageName } from './utils.js';
 
 /**
  * Create the MCP Server
@@ -203,7 +202,7 @@ This server provides resources and tools for quickly scaffolding projects using
 exports[`ts#nx-plugin generator > should generate MCP server files > test-plugin/src/mcp-server/stdio.ts 1`] = `
 "#!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { createServer } from './server';
+import { createServer } from './server.js';
 
 export const startMcpServer = async () => {
   const transport = new StdioServerTransport();
@@ -225,12 +224,12 @@ void (async () => {
 exports[`ts#nx-plugin generator > should generate MCP server files > test-plugin/src/mcp-server/tools/create-workspace-command.ts 1`] = `
 "import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { PackageManagerSchema } from '../schema';
+import { PackageManagerSchema } from '../schema.js';
 import {
   buildCreateCommand,
   buildInstallCommand,
   getPackageName,
-} from '../utils';
+} from '../utils.js';
 
 /**
  * Registers a tool which tells a model how to create an Nx workspace
@@ -316,7 +315,10 @@ export const registerGeneralGuidanceTool = (server: McpServer) => {
         {
           type: 'text' as const,
           text: fs.readFileSync(
-            path.resolve(__dirname, '../resources/GENERAL_GUIDANCE.md'),
+            path.resolve(
+              import.meta.dirname,
+              '../resources/GENERAL_GUIDANCE.md',
+            ),
             'utf-8',
           ),
         },
@@ -330,8 +332,8 @@ export const registerGeneralGuidanceTool = (server: McpServer) => {
 exports[`ts#nx-plugin generator > should generate MCP server files > test-plugin/src/mcp-server/tools/generator-guide.ts 1`] = `
 "import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { renderGeneratorInfo, listGenerators } from '../utils';
-import { PackageManagerSchema } from '../schema';
+import { renderGeneratorInfo, listGenerators } from '../utils.js';
+import { PackageManagerSchema } from '../schema.js';
 import * as fs from 'fs';
 import * as path from 'path';
 
@@ -379,8 +381,8 @@ export const registerGeneratorGuideTool = (server: McpServer) => {
 
 exports[`ts#nx-plugin generator > should generate MCP server files > test-plugin/src/mcp-server/tools/list-generators.ts 1`] = `
 "import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { PackageManagerSchema } from '../schema';
-import { renderGeneratorInfo, listGenerators } from '../utils';
+import { PackageManagerSchema } from '../schema.js';
+import { renderGeneratorInfo, listGenerators } from '../utils.js';
 
 /**
  * Registers a tool which lists details about the available generators
@@ -423,20 +425,29 @@ export interface NxGeneratorInfo {
 
 export const getPackageName = (): string =>
   JSON.parse(
-    fs.readFileSync(path.resolve(__dirname, '../../package.json'), 'utf-8'),
+    fs.readFileSync(
+      path.resolve(import.meta.dirname, '../../package.json'),
+      'utf-8',
+    ),
   ).name;
 
 export const listGenerators = (): NxGeneratorInfo[] =>
   Object.entries(
     JSON.parse(
       fs.readFileSync(
-        path.resolve(__dirname, '../../generators.json'),
+        path.resolve(import.meta.dirname, '../../generators.json'),
         'utf-8',
       ),
     ).generators,
   ).map(([id, info]: any) => ({
     id,
-    resolvedPath: path.resolve(__dirname, '..', '..', info.factory, '..'),
+    resolvedPath: path.resolve(
+      import.meta.dirname,
+      '..',
+      '..',
+      info.factory,
+      '..',
+    ),
     description: info.description,
   }));
 
@@ -470,7 +481,7 @@ export const buildInstallCommand = (pm: string, pkg: string) =>
     pnpm: \`pnpm add -Dw \${pkg}\`,
     yarn: \`yarn add -D \${pkg}\`,
     npm: \`npm install --legacy-peer-deps -D \${pkg}\`,
-    bun: \`bun install -D \${pkg}\`,
+    bun: \`bun add -D \${pkg}\`,
   })[pm];
 
 const renderSchema = (schema: any) =>

package/src/ts/nx-plugin/files/mcp-server/resources/GENERAL_GUIDANCE.md.template

@@ -26,12 +26,11 @@
 
 ## General Instructions
 
-- Workspaces contain a single `package.json` file at the root which defines the dependencies for all projects. Therefore when installing dependencies, you must add these to the root workspace using the appropriate command for your package manager:
-  - pnpm add -w -D <package>
-  - yarn add -D <package>
-  - npm install --legacy-peer-deps -D <package>
-  - bun install -D <package>
-  - (Omit -D for production dependencies)
+- Each project declares the third-party runtime dependencies its source imports in its own `package.json`; shared build/test tooling 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:
+  - 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>`
+  - 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>`
+- The `noUndeclaredDependencies` lint rule enforces that a project's source only imports packages declared in its own `package.json`
+- 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
 - 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
 - When no generator exists for a specific framework required, look for more generic project generators if availalbe and build on top of these.
 

package/src/ts/nx-plugin/files/mcp-server/server.ts.template

@@ -1,9 +1,9 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { registerCreateWorkspaceCommandTool } from './tools/create-workspace-command';
-import { registerGeneralGuidanceTool } from './tools/general-guidance';
-import { registerListGeneratorsTool } from './tools/list-generators';
-import { registerGeneratorGuideTool } from './tools/generator-guide';
-import { getPackageName } from './utils';
+import { registerCreateWorkspaceCommandTool } from './tools/create-workspace-command<% if (esm) { %>.js<% } %>';
+import { registerGeneralGuidanceTool } from './tools/general-guidance<% if (esm) { %>.js<% } %>';
+import { registerListGeneratorsTool } from './tools/list-generators<% if (esm) { %>.js<% } %>';
+import { registerGeneratorGuideTool } from './tools/generator-guide<% if (esm) { %>.js<% } %>';
+import { getPackageName } from './utils<% if (esm) { %>.js<% } %>';
 
 /**
  * Create the MCP Server

package/src/ts/nx-plugin/files/mcp-server/tools/create-workspace-command.ts.template

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { PackageManagerSchema } from '../schema';
-import { buildCreateCommand, buildInstallCommand, getPackageName } from '../utils';
+import { PackageManagerSchema } from '../schema<% if (esm) { %>.js<% } %>';
+import { buildCreateCommand, buildInstallCommand, getPackageName } from '../utils<% if (esm) { %>.js<% } %>';
 
 /**
  * Registers a tool which tells a model how to create an Nx workspace

package/src/ts/nx-plugin/files/mcp-server/tools/general-guidance.ts.template

@@ -16,7 +16,7 @@ export const registerGeneralGuidanceTool = (server: McpServer) => {
         {
           type: 'text' as const,
           text: fs.readFileSync(
-            path.resolve(__dirname, '../resources/GENERAL_GUIDANCE.md'),
+            path.resolve(<% if (esm) { %>import.meta.dirname<% } else { %>__dirname<% } %>, '../resources/GENERAL_GUIDANCE.md'),
             'utf-8',
           ),
         },

package/src/ts/nx-plugin/files/mcp-server/tools/generator-guide.ts.template

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { renderGeneratorInfo, listGenerators } from '../utils';
-import { PackageManagerSchema } from '../schema';
+import { renderGeneratorInfo, listGenerators } from '../utils<% if (esm) { %>.js<% } %>';
+import { PackageManagerSchema } from '../schema<% if (esm) { %>.js<% } %>';
 import * as fs from 'fs';
 import * as path from 'path';