nx 23.2.0-beta.4 → 23.2.0-beta.6

package/dist/src/command-line/migrate/version-skew-guard.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NEW_MIGRATE_FLAGS = exports.NEW_MIGRATE_FLAGS_FLOOR = void 0;
+exports.findNewMigrateFlag = findNewMigrateFlag;
+exports.resolveNewMigrateFlagsRunTarget = resolveNewMigrateFlagsRunTarget;
+exports.assertWorkspaceNxSupportsNewMigrateFlags = assertWorkspaceNxSupportsNewMigrateFlags;
+const semver_1 = require("semver");
+const logger_1 = require("../../utils/logger");
+const output_1 = require("../../utils/output");
+const version_utils_1 = require("./version-utils");
+// The first stable release shipping --run-migration. Deliberately the final
+// release rather than its first prerelease: 23.2.0 prereleases published
+// before the feature landed do not carry it, so a prerelease floor would
+// wrongly accept them. The cost is that a later 23.2.0 prerelease that does
+// carry the feature is refused too, which fails toward refusal. Permanent;
+// never bumped at release time, but it must name the release that actually
+// ships the feature: if that slips past 23.2.0, versions in the gap pass
+// this floor and route to a temp CLI that drops the new flags and runs the
+// plan phase instead.
+exports.NEW_MIGRATE_FLAGS_FLOOR = '23.2.0';
+// yargs accepts both spellings and the raw argv is forwarded across both
+// migrate hops, so detection must catch each one.
+exports.NEW_MIGRATE_FLAGS = ['--run-migration', '--runMigration'];
+/**
+ * Matches an exact token or `<flag>=<value>`. The `=` matters: a bare
+ * `startsWith` would also match `--run-migrations` (trailing s).
+ */
+function findNewMigrateFlag(argv) {
+    for (const arg of argv) {
+        // Everything after the -- separator is positional data, not options.
+        if (arg === '--') {
+            return undefined;
+        }
+        for (const flag of exports.NEW_MIGRATE_FLAGS) {
+            if (arg === flag || arg.startsWith(`${flag}=`)) {
+                return flag;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Guard A (local side, before hop A). The current nx knows the new flags, but
+ * the temp CLI 'nx migrate' is about to install may be older and would
+ * silently drop them. Decides where a new-flag invocation runs:
+ *
+ * - No new flag in `argv`, or the temp CLI version resolves at or above the
+ *   feature floor: 'temp-cli', the normal temp-installation path.
+ * - The temp CLI resolves below the floor, or resolution fails (a registry
+ *   error, or a minimum-release-age violation that a temp install must not
+ *   bypass): 'local-nx', provided the workspace-local nx can take the flags.
+ *   The local nx qualifies when it is the exact version running this code
+ *   (it parsed the flag, so it supports it regardless of the floor) or is at
+ *   or above the floor. An unreadable local version throws: the hand-off's
+ *   spawn normally lands on the very install this read verifies, and a
+ *   layout where the version cannot be read gives no such assurance, so
+ *   handing off blind could run a below-floor nx that silently drops the
+ *   flag.
+ * - Neither side is capable: throw with remediation.
+ *
+ * An explicit NX_MIGRATE_CLI_VERSION pinned below the floor throws instead of
+ * silently overriding the user's pin with the local fallback.
+ *
+ * `cliVersionSpec` is NX_MIGRATE_CLI_VERSION when set, else 'latest'.
+ */
+async function resolveNewMigrateFlagsRunTarget(options) {
+    const flag = findNewMigrateFlag(options.argv);
+    if (!flag) {
+        return 'temp-cli';
+    }
+    // `valid()` returns null for a dist-tag like 'latest' and a normalized
+    // version for a concrete spec, which then skips the registry round-trip.
+    const concrete = (0, semver_1.valid)(options.cliVersionSpec);
+    let resolved;
+    try {
+        resolved =
+            concrete ?? (await options.resolveVersion(options.cliVersionSpec));
+    }
+    catch (e) {
+        // The local-fallback check below decides what a failed resolution means.
+        logger_1.logger.verbose(`Could not resolve the nx version for '${options.cliVersionSpec}': ${e}`);
+    }
+    if (resolved !== undefined &&
+        !(0, semver_1.lt)((0, version_utils_1.normalizeVersion)(resolved), exports.NEW_MIGRATE_FLAGS_FLOOR)) {
+        return 'temp-cli';
+    }
+    if (resolved !== undefined && options.fromEnvOverride) {
+        throw new Error(`The nx version 'nx migrate' is about to install (${resolved}) does not support ${flag}. ` +
+            `This flag ships in nx ${exports.NEW_MIGRATE_FLAGS_FLOOR} or newer. ` +
+            `NX_MIGRATE_CLI_VERSION is set to '${options.cliVersionSpec}'. ` +
+            `Unset it or set it to nx ${exports.NEW_MIGRATE_FLAGS_FLOOR} or newer.`);
+    }
+    const localNxVersion = options.readLocalNxVersion();
+    if (localNxVersion !== undefined &&
+        (localNxVersion === options.ownNxVersion ||
+            !(0, semver_1.lt)((0, version_utils_1.normalizeVersion)(localNxVersion), exports.NEW_MIGRATE_FLAGS_FLOOR))) {
+        // A pinned spec reaching this point failed to resolve: a resolved pin
+        // either returned 'temp-cli' or threw above.
+        if (options.fromEnvOverride) {
+            output_1.output.warn({
+                title: `The nx version pinned by NX_MIGRATE_CLI_VERSION ('${options.cliVersionSpec}') could not be resolved. Running ${flag} with the workspace's installed nx (${localNxVersion}) instead.`,
+            });
+        }
+        return 'local-nx';
+    }
+    const tempSideOutcome = resolved !== undefined
+        ? `resolves to ${resolved}, which does not support it`
+        : `could not be resolved`;
+    const localSideOutcome = localNxVersion !== undefined
+        ? `the workspace's installed nx (${localNxVersion}) does not support it either`
+        : `the workspace's installed nx version could not be read to verify support`;
+    // The worked example assumes the steady state, where 'latest' satisfies
+    // the floor: this branch then fires only when the spec could not be
+    // resolved (default or pinned), and updating the workspace to latest
+    // genuinely fixes it. Before the floor's stable release the example
+    // cannot resolve high enough; that window is deliberately not catered
+    // for, since no stable release carries the flags then anyway.
+    throw new Error(`${flag} requires nx ${exports.NEW_MIGRATE_FLAGS_FLOOR} or newer. ` +
+        `'${options.cliVersionSpec}' (the version 'nx migrate' would install) ${tempSideOutcome}, ` +
+        `and ${localSideOutcome}. ` +
+        `Update the workspace to nx ${exports.NEW_MIGRATE_FLAGS_FLOOR} or newer first, ` +
+        `for example by running 'nx migrate nx@latest' (without ${flag}) or by updating your dependencies.`);
+}
+/**
+ * Guard B (temp side, before hop B). The temp CLI knows the new flags, but the
+ * workspace-local nx it is about to hand off to may be older and would silently
+ * drop them.
+ *
+ * A workspace pinned to a feature-carrying 23.2.0 prerelease is refused here
+ * too: published prereleases that predate the feature cannot be told apart by
+ * version alone. Guard A's same-version bypass does not apply on this side
+ * because the invoking nx's version is not forwarded across hop A; the
+ * refusal names the workspace update that resolves it.
+ *
+ * `readLocalNxVersion` returning undefined does not block: the hand-off then
+ * resolves nx as it always does, which may fail visibly or land on another nx
+ * the package manager locates.
+ */
+function assertWorkspaceNxSupportsNewMigrateFlags(options) {
+    const flag = findNewMigrateFlag(options.argv);
+    if (!flag) {
+        return;
+    }
+    const localNxVersion = options.readLocalNxVersion();
+    if (!localNxVersion) {
+        return;
+    }
+    if ((0, semver_1.lt)((0, version_utils_1.normalizeVersion)(localNxVersion), exports.NEW_MIGRATE_FLAGS_FLOOR)) {
+        // The worked example assumes the steady state (latest at or above the
+        // floor); the pre-floor stable window is deliberately not catered for.
+        throw new Error(`The workspace's installed nx (${localNxVersion}) does not support ${flag}. ` +
+            `Update the workspace to nx ${exports.NEW_MIGRATE_FLAGS_FLOOR} or newer first, ` +
+            `for example by running 'nx migrate nx@latest' (without ${flag}) or by updating your dependencies.`);
+    }
+}

package/dist/src/command-line/nx-cloud/start-nx-agents/command-object.d.ts

@@ -0,0 +1,2 @@
+import { CommandModule } from 'yargs';
+export declare const yargsStartNxAgentsCommand: CommandModule;

package/dist/src/command-line/nx-cloud/start-nx-agents/command-object.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.yargsStartNxAgentsCommand = void 0;
+const handle_import_1 = require("../../../utils/handle-import");
+const shared_options_1 = require("../../yargs-utils/shared-options");
+exports.yargsStartNxAgentsCommand = {
+    command: 'start-nx-agents [options]',
+    describe: 'Provisions Nx Agents for distributed task execution, reading configuration from `.nx/ci-config.yaml`. This command is an alias for [`nx-cloud start-nx-agents`](/docs/reference/nx-cloud-cli#nx-cloud-start-nx-agents).',
+    builder: (yargs) => (0, shared_options_1.withVerbose)(yargs)
+        .help(false)
+        .showHelpOnFail(false)
+        .option('help', { describe: 'Show help.', type: 'boolean' }),
+    handler: async (args) => {
+        process.exit(await (await (0, handle_import_1.handleImport)('./start-nx-agents.js', __dirname)).startNxAgentsHandler(args));
+    },
+};

package/dist/src/command-line/nx-cloud/start-nx-agents/start-nx-agents.d.ts

@@ -0,0 +1,4 @@
+export interface StartNxAgentsArgs {
+    verbose?: boolean;
+}
+export declare function startNxAgentsHandler(args: StartNxAgentsArgs): Promise<number>;

package/dist/src/command-line/nx-cloud/start-nx-agents/start-nx-agents.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startNxAgentsHandler = startNxAgentsHandler;
+const nx_json_1 = require("../../../config/nx-json");
+const nx_cloud_utils_1 = require("../../../utils/nx-cloud-utils");
+const utils_1 = require("../utils");
+function startNxAgentsHandler(args) {
+    if (!(0, nx_cloud_utils_1.isNxCloudUsed)((0, nx_json_1.readNxJson)())) {
+        (0, utils_1.warnNotConnectedToCloud)();
+        return Promise.resolve(0);
+    }
+    return (0, utils_1.executeNxCloudCommand)('start-nx-agents', args.verbose);
+}

package/dist/src/command-line/nx-commands.js

@@ -31,17 +31,18 @@ const command_object_21 = require("./nx-cloud/logout/command-object");
 const command_object_22 = require("./nx-cloud/record/command-object");
 const command_object_23 = require("./nx-cloud/start-agent/command-object");
 const command_object_24 = require("./nx-cloud/start-ci-run/command-object");
-const command_object_25 = require("./register/command-object");
-const command_object_26 = require("./release/command-object");
-const command_object_27 = require("./repair/command-object");
-const command_object_28 = require("./report/command-object");
-const command_object_29 = require("./reset/command-object");
-const command_object_30 = require("./run-many/command-object");
-const command_object_31 = require("./run/command-object");
-const command_object_32 = require("./show/command-object");
-const command_object_33 = require("./sync/command-object");
-const command_object_34 = require("./watch/command-object");
-const command_object_35 = require("./completion/command-object");
+const command_object_25 = require("./nx-cloud/start-nx-agents/command-object");
+const command_object_26 = require("./register/command-object");
+const command_object_27 = require("./release/command-object");
+const command_object_28 = require("./repair/command-object");
+const command_object_29 = require("./report/command-object");
+const command_object_30 = require("./reset/command-object");
+const command_object_31 = require("./run-many/command-object");
+const command_object_32 = require("./run/command-object");
+const command_object_33 = require("./show/command-object");
+const command_object_34 = require("./sync/command-object");
+const command_object_35 = require("./watch/command-object");
+const command_object_36 = require("./completion/command-object");
 const trigger_1 = require("./completion/trigger");
 // Ensure that the output takes up the available width of the terminal.
 yargs.wrap(yargs.terminalWidth());
@@ -59,7 +60,7 @@ exports.commandsObject = yargs
     .parserConfiguration(exports.parserConfiguration)
     .usage(pc.bold('Smart Monorepos · Fast Builds'))
     .demandCommand(1, '')
-    .command(command_object_25.yargsRegisterCommand)
+    .command(command_object_26.yargsRegisterCommand)
     .command(command_object_1.yargsAddCommand)
     .command(command_object_3.yargsConfigureAiAgentsCommand)
     .command(command_object_2.yargsAffectedBuildCommand)
@@ -82,29 +83,30 @@ exports.commandsObject = yargs
     .command(command_object_13.yargsMigrateCommand)
     .command(command_object_14.yargsNewCommand)
     .command(command_objects_1.yargsPrintAffectedCommand)
-    .command(command_object_26.yargsReleaseCommand)
-    .command(command_object_27.yargsRepairCommand)
-    .command(command_object_28.yargsReportCommand)
-    .command(command_object_29.yargsResetCommand)
-    .command(command_object_31.yargsRunCommand)
-    .command(command_object_30.yargsRunManyCommand)
-    .command(command_object_32.yargsShowCommand)
-    .command(command_object_33.yargsSyncCommand)
-    .command(command_object_33.yargsSyncCheckCommand)
+    .command(command_object_27.yargsReleaseCommand)
+    .command(command_object_28.yargsRepairCommand)
+    .command(command_object_29.yargsReportCommand)
+    .command(command_object_30.yargsResetCommand)
+    .command(command_object_32.yargsRunCommand)
+    .command(command_object_31.yargsRunManyCommand)
+    .command(command_object_33.yargsShowCommand)
+    .command(command_object_34.yargsSyncCommand)
+    .command(command_object_34.yargsSyncCheckCommand)
     .command(command_object_17.yargsViewLogsCommand)
-    .command(command_object_34.yargsWatchCommand)
-    .command(command_object_31.yargsNxInfixCommand)
+    .command(command_object_35.yargsWatchCommand)
+    .command(command_object_32.yargsNxInfixCommand)
     .command(command_object_20.yargsLoginCommand)
     .command(command_object_21.yargsLogoutCommand)
     .command(command_object_22.yargsRecordCommand)
     .command(command_object_24.yargsStartCiRunCommand)
+    .command(command_object_25.yargsStartNxAgentsCommand)
     .command(command_object_23.yargsStartAgentCommand)
     .command(command_object_16.yargsStopAllAgentsCommand)
     .command(command_object_19.yargsFixCiCommand)
     .command(command_object_15.yargsApplyLocallyCommand)
     .command(command_object_18.yargsDownloadCloudClientCommand)
     .command(command_object_12.yargsMcpCommand)
-    .command(command_object_35.yargsCompletionCommand)
+    .command(command_object_36.yargsCompletionCommand)
     .command(resolveConformanceCommandObject())
     .command(resolveConformanceCheckCommandObject())
     .scriptName('nx')

package/dist/src/command-line/release/changelog.js

@@ -305,6 +305,11 @@ function createAPI(overrideReleaseConfig, ignoreNxJsonConfig) {
             const projectNodes = projects.map((name) => projectGraph.nodes[name]);
             if (releaseGroup.projectsRelationship === 'independent') {
                 for (const project of projectNodes) {
+                    if (!projectsVersionData[project.name] ||
+                        (projectsVersionData[project.name].newVersion === null &&
+                            !projectsVersionData[project.name].dockerVersion)) {
+                        continue;
+                    }
                     let changes = null;
                     if (releaseGroup.resolvedVersionPlans) {
                         changes = (0, version_plan_utils_1.createChangesFromProjectsVersionPlans)(releaseGroup.resolvedVersionPlans, project.name);

package/dist/src/command-line/release/utils/git.js

@@ -468,7 +468,7 @@ function getAllAuthorsForCommit(commit) {
 }
 // https://www.conventionalcommits.org/en/v1.0.0/
 // https://regex101.com/r/FSfNvA/1
-const ConventionalCommitRegex = /(?<type>[a-z]+)(\((?<scope>.+)\))?(?<breaking>!)?: (?<description>.+)/i;
+const ConventionalCommitRegex = /^(?<type>[^\s():!]+)(?:\s*\((?<scope>.+)\))?(?<breaking>!)?: (?<description>.+)$/u;
 const CoAuthoredByRegex = /co-authored-by:\s*(?<name>.+)(<(?<email>.+)>)/gim;
 // GitHub style PR references
 const PullRequestRE = /\([ a-z]*(#\d+)\s*\)/gm;

package/dist/src/command-line/release/utils/release-graph.d.ts

@@ -91,6 +91,7 @@ export declare class ReleaseGraph {
     }[]>;
     readonly releaseGroupToFilteredProjects: Map<ReleaseGroupWithName, Set<string>>;
     private originalFilteredProjects;
+    private matchedProjectsForFilter;
     /**
      * Store the affected graph per commit per project
      * to avoid recomputation of the graph on workspace

package/dist/src/command-line/release/utils/release-graph.js

@@ -4,6 +4,7 @@ exports.ReleaseGraph = exports.validReleaseVersionPrefixes = void 0;
 exports.createReleaseGraph = createReleaseGraph;
 const affected_project_graph_1 = require("../../../project-graph/affected/affected-project-graph");
 const file_utils_1 = require("../../../project-graph/file-utils");
+const find_matching_projects_1 = require("../../../utils/find-matching-projects");
 const config_1 = require("../config/config");
 const project_logger_1 = require("../version/project-logger");
 const resolve_current_version_1 = require("../version/resolve-current-version");
@@ -43,6 +44,7 @@ class ReleaseGraph {
         this.originalDependentProjectsPerProject = new Map();
         this.releaseGroupToFilteredProjects = new Map();
         this.originalFilteredProjects = new Set();
+        this.matchedProjectsForFilter = new Set();
         /**
          * Store the affected graph per commit per project
          * to avoid recomputation of the graph on workspace
@@ -61,6 +63,12 @@ class ReleaseGraph {
      * @internal - Called by createReleaseGraph(), not meant for external use
      */
     async init(options) {
+        if (this.filters.projects?.length) {
+            this.matchedProjectsForFilter = new Set((0, find_matching_projects_1.findMatchingProjects)([...this.filters.projects], options.projectGraph.nodes));
+            if (this.matchedProjectsForFilter.size === 0) {
+                throw new Error(`Your --projects filter "${this.filters.projects}" did not match any projects in the workspace`);
+            }
+        }
         // Step 1: Setup project to release group mapping
         this.setupProjectReleaseGroupMapping();
         // Step 2: Apply initial filtering to determine base set of projects and groups to process
@@ -122,7 +130,7 @@ class ReleaseGraph {
             const filteredProjects = new Set();
             for (const project of releaseGroup.projects) {
                 if (this.filters.projects?.length &&
-                    !this.filters.projects.includes(project)) {
+                    !this.matchedProjectsForFilter.has(project)) {
                     continue;
                 }
                 filteredProjects.add(project);
@@ -162,7 +170,7 @@ class ReleaseGraph {
                 if (filters.groups?.includes(groupName)) {
                     projectsToProcess.add(project);
                 }
-                else if (filters.projects?.includes(project)) {
+                else if (this.matchedProjectsForFilter.has(project)) {
                     projectsToProcess.add(project);
                 }
                 const projectGraphNode = projectGraph.nodes[project];
@@ -662,7 +670,11 @@ Valid values are: ${exports.validReleaseVersionPrefixes
             head: commit.shortHash,
         });
         // Use the same affected detection logic as `nx affected`
-        affectedGraph = await (0, affected_project_graph_1.filterAffected)(projectGraph, touchedFiles);
+        affectedGraph = await (0, affected_project_graph_1.filterAffected)(projectGraph, touchedFiles, undefined, undefined, 
+        // Release evaluates historical commits against the current project
+        // graph. A project configuration which no longer exists must not make
+        // every surviving release project relevant to that commit.
+        false);
         this.affectedGraphPerCommit.set(shortHash, affectedGraph);
         return affectedGraph;
     }

package/dist/src/command-line/release/version/version-actions.d.ts

@@ -45,6 +45,14 @@ export declare abstract class VersionActions {
      * If a manifest file is not applicable to the current versioning use-case, this should be set to null.
      */
     abstract validManifestFilenames: string[] | null;
+    /**
+     * Whether manifests updated by this implementation should be excluded from
+     * the final Prettier pass performed by Nx Release.
+     *
+     * Custom implementations must opt in explicitly. This defaults to false so
+     * their existing formatting behavior does not change.
+     */
+    excludeManifestsFromFormatting: boolean;
     /**
      * The interpolated manifest paths to update, if applicable based on the user's configuration, when new
      * versions and dependencies are determined. If no manifest files should be updated based on the user's

package/dist/src/command-line/release/version/version-actions.js

@@ -84,6 +84,14 @@ class VersionActions {
         this.releaseGroup = releaseGroup;
         this.projectGraphNode = projectGraphNode;
         this.finalConfigForProject = finalConfigForProject;
+        /**
+         * Whether manifests updated by this implementation should be excluded from
+         * the final Prettier pass performed by Nx Release.
+         *
+         * Custom implementations must opt in explicitly. This defaults to false so
+         * their existing formatting behavior does not change.
+         */
+        this.excludeManifestsFromFormatting = false;
         /**
          * The interpolated manifest paths to update, if applicable based on the user's configuration, when new
          * versions and dependencies are determined. If no manifest files should be updated based on the user's

package/dist/src/command-line/release/version.js

@@ -173,11 +173,15 @@ function createAPI(overrideReleaseConfig, ignoreNxJsonConfig) {
             // Bubble up the error so that the CLI can print the error and exit, or the programmatic API can handle it
             throw err;
         }
-        /**
-         * Ensure that formatting is applied so that version bump diffs are as minimal as possible
-         * within the context of the user's workspace.
-         */
-        await (0, format_changed_files_with_prettier_if_available_1.formatChangedFilesWithPrettierIfAvailable)(tree, { silent: true });
+        // A version actions implementation can opt its manifests out of this final
+        // pass when it already preserves their formatting while updating values.
+        const manifestsToExcludeFromFormatting = new Set(Array.from(releaseGraph.projectsToVersionActions.values()).flatMap((versionActions) => versionActions.excludeManifestsFromFormatting
+            ? versionActions.manifestsToUpdate.map(({ manifestPath }) => manifestPath)
+            : []));
+        await (0, format_changed_files_with_prettier_if_available_1.formatChangedFilesWithPrettierIfAvailable)(tree, {
+            silent: true,
+            excludePaths: manifestsToExcludeFromFormatting,
+        });
         printAndFlushChanges(tree, !!args.dryRun);
         const { changedFiles: changed, deletedFiles: deleted } = await processor.afterAllProjectsVersioned({
             ...nxReleaseConfig.version

package/dist/src/command-line/reset/reset.js

@@ -137,7 +137,12 @@ function cleanupCacheEntries() {
 }
 function cleanupNativeFileCache() {
     return incrementalBackoff(INCREMENTAL_BACKOFF_FIRST_DELAY, INCREMENTAL_BACKOFF_MAX_DURATION, () => {
-        (0, node_fs_1.rmSync)((0, native_file_cache_location_1.getNativeFileCacheLocation)(), { recursive: true, force: true });
+        // Null when the native cache root is not a real directory we own, which
+        // would mean deleting through a path another user planted.
+        const cacheDir = (0, native_file_cache_location_1.getNativeFileCacheLocationToDelete)();
+        if (cacheDir) {
+            (0, node_fs_1.rmSync)(cacheDir, { recursive: true, force: true });
+        }
     });
 }
 function cleanupWorkspaceData() {

package/dist/src/command-line/run/run-one.js

@@ -51,6 +51,7 @@ async function runOne(cwd, args, extraTargetDependencies = {}, extraOptions = {
     }
     else {
         const status = await (0, run_command_1.runCommand)(projects, projectGraph, { nxJson }, nxArgs, overrides, projectName, extraTargetDependencies, extraOptions);
+        await output_1.output.drain();
         process.exit(status);
     }
 }

package/dist/src/command-line/run-many/run-many.js

@@ -41,6 +41,7 @@ async function runMany(args, extraTargetDependencies = {}, extraOptions = {
     }
     else {
         const status = await (0, run_command_1.runCommand)(projects, projectGraph, { nxJson }, nxArgs, overrides, null, extraTargetDependencies, extraOptions);
+        await output_1.output.drain();
         process.exit(status);
     }
 }

package/dist/src/config/misc-interfaces.d.ts

@@ -66,15 +66,24 @@ export type PackageJsonUpdates = {
  *
  * - `nextSteps`: workspace-wide notes surfaced to the human in the `nx migrate`
  *   post-run summary. Same audience as the legacy `string[]` return.
- * - `agentContext`: for hybrid migrations (`implementation` + `prompt`). When the
- *   paired prompt runs under `--agentic`, these strings are delivered to the
- *   agent as part of its outer prompt. When no agent runs, this bucket is
- *   silently dropped — it is agent-only by contract. Content meant for the
- *   human in any scenario belongs in `nextSteps`.
+ * - `agentContext`: agent-only by contract. With the agentic flow on it is
+ *   delivered to the agent as part of its outer prompt, but only when the step
+ *   it feeds actually runs: a hybrid's paired prompt, or the validation pass
+ *   after a generator-only migration, which also needs file changes and no
+ *   `--no-validate`. When `nx migrate` itself runs inside an outer agent it goes
+ *   to stdout for that agent instead. Anything else drops it, so content meant
+ *   for the human in any scenario belongs in `nextSteps`.
+ * - `skipAgentic`: set to `true` to declare that the deterministic run handled
+ *   everything, so `nx migrate` skips the AI step it would otherwise run: the
+ *   paired prompt of a hybrid migration, or the generic validation step of a
+ *   generator-only one. Omitting it keeps the AI step, so this is opt-in.
+ *   Where the waiver takes effect, `agentContext` is dropped along with the
+ *   step it was meant for.
  */
 export interface MigrationReturnObject {
     nextSteps?: string[];
     agentContext?: string[];
+    skipAgentic?: boolean;
 }
 export type Migration = (tree: Tree) => void | string[] | MigrationReturnObject | Promise<void | string[] | MigrationReturnObject>;
 export interface MigrationsJsonEntry {
@@ -87,8 +96,11 @@ export interface MigrationsJsonEntry {
     /**
      * Path to a markdown doc describing the migration, relative to the
      * `migrations.json` and resolved like `implementation`/`factory`. Always
-     * supplementary; never stands in for them. Under `--run-migrations
-     * --agentic` the resolved path is passed to the agent as extra context.
+     * supplementary; never stands in for them. Under `--run-migrations` it is
+     * resolved only when the agentic flow is on, and goes to the agent running
+     * the prompt or the validation pass. `--run-migration` resolves it for those
+     * same steps, and again when it hands a prompt off instead of running it, to
+     * an outer agent or to the user.
      */
     documentation?: string;
 }