nx 23.0.0-beta.2 → 23.0.0-beta.21

package/dist/src/command-line/migrate/agentic/types.d.ts

@@ -0,0 +1,102 @@
+import type { AgentId } from './cli-args';
+export type { AgentId };
+/**
+ * A coding agent that was found on the user's machine, ready to be spawned.
+ *
+ * Produced by `detect-installed.ts`. The `binary` is an absolute path so the
+ * runner can spawn it directly without re-resolving against PATH.
+ */
+export interface DetectedInstalledAgent {
+    id: AgentId;
+    displayName: string;
+    binary: string;
+    source: 'path' | 'well-known';
+}
+/**
+ * Inputs the runner provides when asking an agent definition to build its
+ * spawn arguments. Kept minimal — agent-specific quirks (e.g. transient agent
+ * name for OpenCode) are encoded inside the definition, not here.
+ */
+export interface InvocationContext {
+    systemContext: string;
+    userPrompt: string;
+    workspaceRoot: string;
+}
+/**
+ * What an agent definition returns from `buildInteractive`. The runner combines
+ * this with the detected binary path to actually spawn.
+ */
+export interface InvocationSpec {
+    args: string[];
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+}
+/**
+ * Static description of an agent the migrate command knows how to dispatch to.
+ */
+export interface AgentDefinition {
+    id: AgentId;
+    displayName: string;
+    /** Binary names to probe via `which` (PATHEXT handled by `which` on Windows). */
+    binaryNames: string[];
+    /** Absolute paths to probe as a fallback when PATH lookup misses. */
+    wellKnownPaths(): string[];
+    buildInteractive(ctx: InvocationContext): InvocationSpec;
+}
+/**
+ * Output of the agent's handoff file, written at the end of an agentic step.
+ * The two locked fields drive the failure-handling matrix in the design doc;
+ * extra fields are tolerated and surfaced via `extras`.
+ */
+export interface HandoffFile {
+    status: 'success' | 'failed';
+    summary: string;
+    extras?: Record<string, unknown>;
+}
+/**
+ * Outcome the runner reports back to the migrate orchestrator after a single
+ * agentic step. The four kinds mirror the (a)/(b)/(c) matrix plus the user's
+ * choice when (c) fires.
+ *
+ * `ambiguous-abort.causeSummary`: pre-rendered explanation lines. Populated
+ * when Ctrl+C bypasses the ambiguous prompt (so the cause was never shown
+ * inline) and forwarded so the caller can surface it. Omitted when the user
+ * chose "abort" at the prompt — the cause was already shown there.
+ */
+export type HandoffOutcome = {
+    kind: 'success';
+    summary: string;
+    extras?: Record<string, unknown>;
+} | {
+    kind: 'failed';
+    summary: string;
+    extras?: Record<string, unknown>;
+} | {
+    kind: 'ambiguous-continue';
+} | {
+    kind: 'ambiguous-abort';
+    causeSummary?: string[];
+};
+/**
+ * Result of the up-front resolution phase that runs once per `--run-migrations`
+ * invocation, before the migration loop. Cached and consulted for every entry.
+ *
+ * - `inside-agent`: nx detected it is itself running inside another agent;
+ *   every agentic step is skipped and prompt migrations go to `nextSteps`.
+ * - `disabled`: the user opted out (explicit `--agentic=false`, declined the
+ *   up-front prompt, or non-TTY without the flag).
+ * - `enabled`: the agentic flow runs and `selectedAgent` is the agent it
+ *   dispatches to.
+ */
+export type ResolvedAgentic = {
+    kind: 'inside-agent';
+} | {
+    kind: 'disabled';
+} | {
+    kind: 'enabled';
+    selectedAgent: DetectedInstalledAgent;
+};
+/** The `enabled` variant, useful for narrowed function signatures. */
+export type EnabledResolvedAgentic = Extract<ResolvedAgentic, {
+    kind: 'enabled';
+}>;

package/dist/src/command-line/migrate/agentic/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/command-line/migrate/command-object.d.ts

@@ -1,3 +1,4 @@
 import { CommandModule } from 'yargs';
 export declare const yargsMigrateCommand: CommandModule;
 export declare const yargsInternalMigrateCommand: CommandModule;
+export declare const DEFAULT_MIGRATION_COMMIT_PREFIX = "chore: [nx migration] ";

package/dist/src/command-line/migrate/command-object.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.yargsInternalMigrateCommand = exports.yargsMigrateCommand = void 0;
+exports.DEFAULT_MIGRATION_COMMIT_PREFIX = exports.yargsInternalMigrateCommand = exports.yargsMigrateCommand = void 0;
 const handle_import_1 = require("../../utils/handle-import");
 const documentation_1 = require("../yargs-utils/documentation");
 const shared_options_1 = require("../yargs-utils/shared-options");
+const cli_args_1 = require("./agentic/cli-args");
 exports.yargsMigrateCommand = {
     command: 'migrate [packageAndVersion]',
     describe: `Creates a migrations file or runs migrations from the migrations file.
@@ -18,8 +19,8 @@ exports.yargsInternalMigrateCommand = {
     builder: (yargs) => withMigrationOptions(yargs),
     handler: async (args) => process.exit(await (await (0, handle_import_1.handleImport)('./migrate.js', __dirname)).migrate(process.cwd(), args, process.argv.slice(3))),
 };
+exports.DEFAULT_MIGRATION_COMMIT_PREFIX = 'chore: [nx migration] ';
 function withMigrationOptions(yargs) {
-    const defaultCommitPrefix = 'chore: [nx migration] ';
     return (0, shared_options_1.withVerbose)(yargs)
         .positional('packageAndVersion', {
         describe: `The target package and version (e.g, @nx/workspace@16.0.0).`,
@@ -46,12 +47,11 @@ function withMigrationOptions(yargs) {
         describe: 'Automatically create a git commit after each migration runs.',
         type: 'boolean',
         alias: ['C'],
-        default: false,
     })
         .option('commitPrefix', {
         describe: 'Commit prefix to apply to the commit for each migration, when --create-commits is enabled.',
         type: 'string',
-        default: defaultCommitPrefix,
+        default: exports.DEFAULT_MIGRATION_COMMIT_PREFIX,
     })
         .option('interactive', {
         describe: 'Enable prompts to confirm whether to collect optional package updates and migrations.',
@@ -67,13 +67,38 @@ function withMigrationOptions(yargs) {
         type: 'boolean',
         default: false,
     })
-        .check(({ createCommits, commitPrefix, from, excludeAppliedMigrations }) => {
-        if (!createCommits && commitPrefix !== defaultCommitPrefix) {
+        .option('mode', {
+        describe: "Restrict which packages to migrate. Only applies when migrating Nx itself. 'first-party' processes only Nx and its plugins (the target package plus its nx.packageGroup); 'third-party' processes only the third-party dependencies referenced by Nx packageJsonUpdates entries, catching up on any updates that may have been skipped previously; 'all' processes everything. When targeting Nx in an interactive terminal, prompts for the value if not provided; otherwise defaults to 'all'.",
+        type: 'string',
+        choices: ['first-party', 'third-party', 'all'],
+    })
+        .option('multiMajorMode', {
+        describe: "Skip the multi-major migration prompt/warning and pick how to handle the jump. 'direct' migrates straight to the requested target. 'gradual' migrates to the smallest recommended step (re-run `nx migrate` to continue toward the original target). Equivalent env var: NX_MULTI_MAJOR_MODE=direct|gradual.",
+        type: 'string',
+        choices: ['direct', 'gradual'],
+    })
+        .option('agentic', {
+        describe: 'Enable the agentic flow for prompt-based migrations and AI-driven review. Pass `--agentic=<agent>` to pin a specific agent (claude-code, codex, or opencode). Pass `--agentic=false` or `--no-agentic` to disable.',
+        coerce: cli_args_1.coerceAgenticArg,
+    })
+        .option('validate', {
+        describe: 'When `--agentic` resolves to an enabled agent, run agent-driven validation after generator-only migrations that have no `prompt:` field. Defaults to on; pass `--no-validate` to opt out. Has no effect when `--agentic` is disabled, when running inside an outer agent, or when running non-interactively without an explicit agent.',
+        type: 'boolean',
+    })
+        .check(({ createCommits, commitPrefix, from, excludeAppliedMigrations, mode, agentic, }) => {
+        const agenticMayEnableCommits = agentic !== undefined && agentic !== false && createCommits !== false;
+        if (createCommits !== true &&
+            !agenticMayEnableCommits &&
+            commitPrefix !== exports.DEFAULT_MIGRATION_COMMIT_PREFIX) {
             throw new Error('Error: Providing a custom commit prefix requires --create-commits to be enabled');
         }
-        if (excludeAppliedMigrations && !from) {
+        if (excludeAppliedMigrations && !from && mode !== 'third-party') {
             throw new Error('Error: Excluding migrations that should have been previously applied requires --from to be set');
         }
+        if (typeof agentic === 'string' &&
+            !cli_args_1.AGENT_IDS.includes(agentic)) {
+            throw new Error(`Error: Invalid --agentic value "${agentic}". Allowed: ${cli_args_1.AGENT_IDS.join(', ')}, true, false.`);
+        }
         return true;
     });
 }

package/dist/src/command-line/migrate/migrate-commits.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Discriminated result for `commitMigrationIfRequested`. Distinguishes the
+ * shapes the executor needs to react to:
+ *
+ * - `committed`: a commit landed. `sha` is `null` only when `git rev-parse
+ *   HEAD` failed transiently — by contract the diff is no longer in the
+ *   working tree.
+ * - `no-changes`: commits were requested but there was nothing to commit.
+ * - `failed`: the commit attempt itself errored. The diff remains in the
+ *   working tree; the executor uses this signal to track pending migrations
+ *   so the next successful commit can annotate its body.
+ * - `disabled`: commits are off for this run.
+ */
+export type CommitResult = {
+    status: 'committed';
+    sha: string | null;
+} | {
+    status: 'no-changes';
+} | {
+    status: 'failed';
+    reason: string;
+} | {
+    status: 'disabled';
+};
+/**
+ * Creates a per-migration commit when `shouldCreateCommits` is true.
+ *
+ * When `pendingMigrations` is non-empty, the commit message body lists
+ * those entries so a reader of `git log -p` can see which prior migrations'
+ * diffs were absorbed into this commit (because their own commits failed and
+ * `git add -A` here captured their working-tree state too). Each entry is
+ * rendered as `<package>: <name>` for unambiguous attribution across
+ * packages.
+ */
+export declare function commitMigrationIfRequested(root: string, migration: {
+    name: string;
+}, shouldCreateCommits: boolean, commitPrefix: string, installDepsIfChanged: () => Promise<void>, pendingMigrations?: ReadonlyArray<{
+    package: string;
+    name: string;
+}>): Promise<CommitResult>;
+/**
+ * Commits any pre-existing working-tree state into a dedicated "checkpoint"
+ * commit before the first migration runs. Without this, the first migration's
+ * commit would absorb whatever was already pending — most commonly the
+ * package.json edit `nx migrate latest` produces and the lockfile churn from
+ * the orchestrator's `npm install --ignore-scripts` step — and migration 1's
+ * validation would see that mixed in with the generator output. No-op when
+ * the working tree is already clean.
+ */
+export declare function commitCheckpointBeforeMigrations(root: string, commitPrefix: string): void;

package/dist/src/command-line/migrate/migrate-commits.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commitMigrationIfRequested = commitMigrationIfRequested;
+exports.commitCheckpointBeforeMigrations = commitCheckpointBeforeMigrations;
+const tslib_1 = require("tslib");
+const pc = tslib_1.__importStar(require("picocolors"));
+const git_utils_1 = require("../../utils/git-utils");
+const logger_1 = require("../../utils/logger");
+const output_1 = require("../../utils/output");
+/**
+ * Creates a per-migration commit when `shouldCreateCommits` is true.
+ *
+ * When `pendingMigrations` is non-empty, the commit message body lists
+ * those entries so a reader of `git log -p` can see which prior migrations'
+ * diffs were absorbed into this commit (because their own commits failed and
+ * `git add -A` here captured their working-tree state too). Each entry is
+ * rendered as `<package>: <name>` for unambiguous attribution across
+ * packages.
+ */
+async function commitMigrationIfRequested(root, migration, shouldCreateCommits, commitPrefix, installDepsIfChanged, pendingMigrations = []) {
+    if (!shouldCreateCommits)
+        return { status: 'disabled' };
+    await installDepsIfChanged();
+    // Generator may have only touched gitignored paths, or the prompt half
+    // made no change — log neutrally instead of as an error.
+    if (!(0, git_utils_1.hasUncommittedChanges)(root)) {
+        logger_1.logger.info(pc.dim(`- No changes to commit for ${migration.name}.`));
+        return { status: 'no-changes' };
+    }
+    const commitMessage = buildCommitMessage(`${commitPrefix}${migration.name}`, pendingMigrations);
+    try {
+        const sha = (0, git_utils_1.tryCommitChanges)(commitMessage, root);
+        if (sha)
+            return { status: 'committed', sha };
+        // null = commit landed but `git rev-parse HEAD` failed (see
+        // `tryCommitChanges`). Degraded-but-correct — log yellow, not red.
+        logger_1.logger.info(pc.yellow(`The commit for ${migration.name} was created, but its sha could not be resolved (\`git rev-parse HEAD\` failed transiently). Continuing without recording the sha for this step.`));
+        return { status: 'committed', sha: null };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        logger_1.logger.info(pc.red(`Could not create a commit for ${migration.name}:\n${reason}\nThe migration's diff remains in the working tree; inspect with \`git status\` / \`git diff\` to review. The next successful commit will absorb it and reference this migration in its body; if no later commit lands, the end-of-run output will list this migration so you can commit or revert manually.`));
+        return { status: 'failed', reason };
+    }
+}
+// Migration names come from migrations.json (third-party plugin authored);
+// they cannot be trusted to be single-line. Strip CR/LF so a hostile name
+// cannot inject body lines or fake `Co-Authored-By:` / similar trailers.
+function sanitizeMigrationLine(value) {
+    return value.replace(/[\r\n]+/g, ' ').trim();
+}
+function buildCommitMessage(subject, pendingMigrations) {
+    if (pendingMigrations.length === 0)
+        return subject;
+    // Two newlines separate the subject from the body per the
+    // conventional-commits convention.
+    const lines = [
+        subject,
+        '',
+        'Includes changes from prior migrations whose own commits failed:',
+        ...pendingMigrations.map((p) => `  - ${sanitizeMigrationLine(p.package)}: ${sanitizeMigrationLine(p.name)}`),
+    ];
+    return lines.join('\n');
+}
+/**
+ * Commits any pre-existing working-tree state into a dedicated "checkpoint"
+ * commit before the first migration runs. Without this, the first migration's
+ * commit would absorb whatever was already pending — most commonly the
+ * package.json edit `nx migrate latest` produces and the lockfile churn from
+ * the orchestrator's `npm install --ignore-scripts` step — and migration 1's
+ * validation would see that mixed in with the generator output. No-op when
+ * the working tree is already clean.
+ */
+function commitCheckpointBeforeMigrations(root, commitPrefix) {
+    if (!(0, git_utils_1.hasUncommittedChanges)(root))
+        return;
+    try {
+        const sha = (0, git_utils_1.tryCommitChanges)(`${commitPrefix}checkpoint before running migrations`, root);
+        if (sha) {
+            logger_1.logger.info(pc.dim(`- Checkpoint commit created: ${sha}`));
+            return;
+        }
+        // null = commit landed but `git rev-parse HEAD` failed (see
+        // `tryCommitChanges`). State is captured, just unanchored.
+        output_1.output.warn({
+            title: 'Could not resolve checkpoint commit sha',
+            bodyLines: [
+                'The checkpoint commit was created, but its sha could not be resolved (`git rev-parse HEAD` failed transiently).',
+            ],
+        });
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        output_1.output.warn({
+            title: 'Could not create checkpoint commit before migrations',
+            bodyLines: [
+                reason,
+                `Migration 1's commit will absorb any pre-existing working-tree state.`,
+            ],
+        });
+    }
+}

package/dist/src/command-line/migrate/migrate-output.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Presentation layer for `nx migrate --run-migrations`. Pure helpers — every
+ * function maps (state) → (terminal output or string lines). Shared visual
+ * vocabulary across the migrate run:
+ *   `→` start  ·  `✓` success  ·  `✗` failure  ·  `↷` skipped  ·  `ℹ` info  ·  `─` boundary
+ *
+ * Inputs are typed structurally (e.g. `{ name: string }[]`) so this module
+ * stays decoupled from `ExecutableMigration` and the executor in migrate.ts.
+ */
+/**
+ * Some agent TUIs (codex, opencode) don't fully reset their cursor / SGR state
+ * when they exit, which corrupts subsequent orchestrator output. Emit an SGR
+ * reset + newline so our log lines land on a clean row instead of being
+ * overlaid by leftover status bars.
+ */
+export declare function resetSgrAfterAgent(): void;
+/**
+ * Per-migration boundary header. Anchors the orchestrator log at the start of
+ * each migration with the migration index and identity.
+ */
+export declare function logMigrationBoundary(index: number, total: number, pkg: string, name: string): void;
+/**
+ * Logs the outcome line that closes an agentic phase. Vocabulary:
+ *   ✓ <label>[ (<sha>)]: <summary>
+ */
+export declare function logAgenticSuccessOutcome(label: string, sha: string | null, summary: string): void;
+/**
+ * Per-migration outcome record consumed by the failure recap. One entry is
+ * appended per iteration that returned without throwing; the failing migration
+ * has no record.
+ *
+ * - `applied`: ran fully to completion, including any agentic step.
+ * - `no-changes`: generator ran but produced no diff (counts as applied work).
+ * - `deferred`: prompt half was not applied (agent disabled or inside-agent
+ *   mode hands it off). For hybrid migrations the deterministic half still ran.
+ *
+ * `committedAsPartOf` is set when this migration's own commit attempt failed
+ * but its diff was later absorbed into a successor migration's commit (which
+ * stages the working tree's accumulated state via `git add -A`). The recap
+ * uses this to anchor "last applied" honestly when the last-named commit
+ * landed multiple migrations' contributions.
+ */
+export type MigrationOutcomeKind = 'applied' | 'no-changes' | 'deferred';
+/**
+ * The state of a migration's commit attempt. Tagged union so consumers don't
+ * have to re-derive legal combinations from nullable fields.
+ *
+ * - `none`     — no commit was attempted (`--no-create-commits` or no diff to
+ *                commit).
+ * - `landed`   — a commit was actually created. `sha: null` only when
+ *                `git rev-parse HEAD` failed transiently right after the
+ *                commit landed; by contract the diff did clear.
+ * - `failed`   — commit was attempted and errored (signing, hook rejection,
+ *                lock, install error mid-attempt, etc.). The diff stays in
+ *                the working tree until a later migration's commit absorbs
+ *                it (then transitions to `absorbed`) or until the run ends
+ *                (then surfaces as retained state).
+ * - `absorbed` — own commit failed but a later migration's commit absorbed
+ *                this diff via `git add -A`. `into.sha: null` means that
+ *                absorbing commit itself hit a HEAD-resolve race; the recap
+ *                renders an anchor without a sha.
+ */
+export type CommitState = {
+    kind: 'none';
+} | {
+    kind: 'landed';
+    sha: string | null;
+} | {
+    kind: 'failed';
+} | {
+    kind: 'absorbed';
+    into: {
+        name: string;
+        sha: string | null;
+    };
+};
+/**
+ * Per-migration record produced by the executor loop. `status: 'completed'`
+ * carries the kind (applied / no-changes / deferred); `status: 'aborted'`
+ * means the migration threw before completing — the executor's catch block
+ * records it so the recap can list it under retained-state alongside any
+ * other migrations whose commits never landed.
+ */
+export type MigrationOutcome = {
+    migration: {
+        package: string;
+        name: string;
+    };
+    status: 'completed';
+    kind: MigrationOutcomeKind;
+    commit: CommitState;
+} | {
+    migration: {
+        package: string;
+        name: string;
+    };
+    status: 'aborted';
+    commit: CommitState;
+};
+/**
+ * Counts the migrations whose own commit actually landed — including the
+ * HEAD-resolve-race case (`commit: { kind: 'landed', sha: null }`). Used by
+ * the end-of-run "<K> commits created" tally and by the success-path
+ * accounting in `executeMigrations`. Counts landed-commit *records* rather
+ * than distinct shas; absorbed predecessors (`kind: 'absorbed'`) are not
+ * counted because the absorbing commit's record already contributes one.
+ */
+export declare function countLandedCommits(outcomes: ReadonlyArray<MigrationOutcome>): number;
+/**
+ * Migrations whose own commit attempt failed and whose diff was never
+ * absorbed by a later commit. Surfaces what the user has to commit or
+ * revert after the run. Filters on `commit.kind === 'failed'` exactly —
+ * `'absorbed'` means the diff cleared into a later commit, `'none'` means
+ * no commit was attempted (intentional `--no-create-commits` or no-op).
+ */
+export declare function retainedMigrations(outcomes: ReadonlyArray<MigrationOutcome>): Array<{
+    package: string;
+    name: string;
+}>;
+/**
+ * Logs a structured recap when a migration throws mid-loop. Inserted between
+ * the "Failed to run X" error block and the re-throw so the user (or AI agent
+ * driving the run) can see what completed before the failure without scrolling
+ * back through the per-migration log to count shas.
+ *
+ * Counts-based rather than full migration lists so a 24-migration run that
+ * fails at #12 doesn't dump 24 names into the recap — readers scroll up to
+ * see specifics in the per-migration log. The "last applied" anchor pairs the
+ * most recent fully-applied migration with the sha its commit actually
+ * produced, so a skipped/deferred step trailing an applied one can't borrow
+ * the earlier sha.
+ */
+export declare function logFailureRecap(opts: {
+    migrationIndex: number;
+    totalMigrations: number;
+    outcomes: ReadonlyArray<MigrationOutcome>;
+    migrationEmittedNextSteps: string[];
+    insideAgent: boolean;
+}): void;
+/**
+ * Builds the tally body line shown under the top end-of-run NX block. Returns
+ * `null` when there is nothing meaningful to tally (e.g. an empty
+ * migrations.json), so the caller can omit the body entirely instead of
+ * emitting a misleading `0 prompt migrations skipped.` line.
+ *
+ * Rule (kept coherent across every scenario):
+ * - When at least one migration was applied: `<N> migrations applied, <K> commits created[, <D> prompt migrations <skipped|deferred>]`.
+ *   The `<K> commits created` part stays even at 0 — it tells the reader work
+ *   was applied but not committed (the J4/J8 information made explicit).
+ * - When zero migrations were applied but some prompt halves were
+ *   skipped/deferred: `<D> prompt migrations <skipped|deferred>` only.
+ * - When zero of either: no body line.
+ */
+export declare function buildTallyBodyLine(opts: {
+    appliedCount: number;
+    committedShasCount: number;
+    skippedPromptsCount: number;
+    insideAgent: boolean;
+}): string | null;
+/**
+ * Body lines for the end-of-run retained-state warning. Fires on the success
+ * path — the run completed but one or more migrations' own commits failed
+ * and were never absorbed.
+ */
+export declare function buildRetainedAtSuccessBody(retainedNames: ReadonlyArray<string>): string[];
+/**
+ * Builds the body lines for the inside-agent directive block. Sub-sections
+ * drop independently when empty. Returns an empty array when the block has
+ * nothing actionable (no deferred prompts AND no migration-emitted notes) —
+ * the caller skips emitting the block entirely in that case.
+ */
+export declare function buildDirectiveBlockBodyLines(opts: {
+    skippedPrompts: ReadonlyArray<{
+        prompt?: string;
+        name: string;
+        implementation?: string;
+        factory?: string;
+    }>;
+    migrationEmittedNextSteps: string[];
+}): string[];