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

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

@@ -0,0 +1,258 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetSgrAfterAgent = resetSgrAfterAgent;
+exports.logMigrationBoundary = logMigrationBoundary;
+exports.logAgenticSuccessOutcome = logAgenticSuccessOutcome;
+exports.countLandedCommits = countLandedCommits;
+exports.retainedMigrations = retainedMigrations;
+exports.logFailureRecap = logFailureRecap;
+exports.buildTallyBodyLine = buildTallyBodyLine;
+exports.buildRetainedAtSuccessBody = buildRetainedAtSuccessBody;
+exports.buildDirectiveBlockBodyLines = buildDirectiveBlockBodyLines;
+const tslib_1 = require("tslib");
+const pc = tslib_1.__importStar(require("picocolors"));
+const logger_1 = require("../../utils/logger");
+const migration_shape_1 = require("./migration-shape");
+/**
+ * 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.
+ */
+function resetSgrAfterAgent() {
+    process.stdout.write('\x1b[0m\n');
+}
+/**
+ * Per-migration boundary header. Anchors the orchestrator log at the start of
+ * each migration with the migration index and identity.
+ */
+function logMigrationBoundary(index, total, pkg, name) {
+    const label = `── Migration ${index} of ${total} · ${pkg}:${name} `;
+    const targetWidth = 73;
+    const dashes = Math.max(3, targetWidth - label.length);
+    logger_1.logger.info(`${label}${'─'.repeat(dashes)}`);
+}
+/**
+ * Logs the outcome line that closes an agentic phase. Vocabulary:
+ *   ✓ <label>[ (<sha>)]: <summary>
+ */
+function logAgenticSuccessOutcome(label, sha, summary) {
+    const shaPart = sha ? ` (${sha})` : '';
+    logger_1.logger.info(`${pc.green('✓')} ${label}${shaPart}: ${summary}`);
+}
+/**
+ * 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.
+ */
+function countLandedCommits(outcomes) {
+    return outcomes.filter((o) => o.commit.kind === 'landed').length;
+}
+/**
+ * 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).
+ */
+function retainedMigrations(outcomes) {
+    return outcomes
+        .filter((o) => o.commit.kind === 'failed')
+        .map((o) => ({ package: o.migration.package, name: o.migration.name }));
+}
+/**
+ * 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.
+ */
+function logFailureRecap(opts) {
+    const { migrationIndex, totalMigrations, outcomes, migrationEmittedNextSteps, insideAgent, } = opts;
+    const appliedCount = outcomes.filter((o) => o.status === 'completed' &&
+        (o.kind === 'applied' || o.kind === 'no-changes')).length;
+    const deferredCount = outcomes.filter((o) => o.status === 'completed' && o.kind === 'deferred').length;
+    const notAttempted = totalMigrations - migrationIndex;
+    // Walk back to the most recent completed record whose work is anchored to
+    // a sha — either its own commit (`landed`), or a later commit that
+    // absorbed it (`absorbed`). Both `applied` AND `deferred` outcomes can
+    // carry a successful commit (hybrid-without-agentic produces `deferred`
+    // with a sha from its deterministic half). Skipped and uncommitted
+    // records don't anchor.
+    let lastApplied;
+    for (let i = outcomes.length - 1; i >= 0; i--) {
+        const o = outcomes[i];
+        if (o.status !== 'completed')
+            continue;
+        if ((o.kind === 'applied' || o.kind === 'deferred') &&
+            (o.commit.kind === 'landed' || o.commit.kind === 'absorbed')) {
+            lastApplied = o;
+            break;
+        }
+    }
+    // Migrations whose own commit attempt errored AND whose diff was never
+    // absorbed by a later commit. Surfaces what the user has to inspect or
+    // clean up in the working tree. Single iteration over `outcomes` —
+    // `outcomes` is the sole source of truth (including the in-flight
+    // migration recorded by the executor's catch block), so no dedupe is
+    // needed. `kind: 'failed'` excludes `kind: 'none'` (intentional no-commit:
+    // `--no-create-commits` runs and no-op steps).
+    const uncommittedAtFailure = [];
+    for (const o of outcomes) {
+        if (o.commit.kind !== 'failed')
+            continue;
+        uncommittedAtFailure.push({ migration: o.migration });
+    }
+    logger_1.logger.info('');
+    logger_1.logger.info(`Run halted at migration ${migrationIndex} of ${totalMigrations}.`);
+    if (appliedCount === 0 && deferredCount === 0) {
+        logger_1.logger.info(`0 migrations completed. ${notAttempted} not attempted.`);
+    }
+    else {
+        const anchorSha = lastApplied === undefined
+            ? undefined
+            : lastApplied.commit.kind === 'landed'
+                ? lastApplied.commit.sha
+                : lastApplied.commit.kind === 'absorbed'
+                    ? lastApplied.commit.into.sha
+                    : undefined;
+        // When the anchoring commit hit a HEAD-resolve race, the sha is null;
+        // render the migration name alone (without "→ null") so the recap
+        // never displays the literal word "null" to the user.
+        const anchor = lastApplied
+            ? anchorSha
+                ? ` (last: ${lastApplied.migration.name} → ${anchorSha})`
+                : ` (last: ${lastApplied.migration.name})`
+            : '';
+        const parts = [`${appliedCount} applied${anchor}`];
+        if (deferredCount > 0) {
+            parts.push(`${deferredCount} deferred`);
+        }
+        logger_1.logger.info(`${parts.join(', ')}. ${notAttempted} not attempted.`);
+        logger_1.logger.info(`See the per-migration log above for full details.`);
+    }
+    if (uncommittedAtFailure.length > 0) {
+        logger_1.logger.info('');
+        logger_1.logger.info(`Working-tree state retained from ${uncommittedAtFailure.length} migration${uncommittedAtFailure.length === 1 ? '' : 's'} whose commits could not be created:`);
+        for (const o of uncommittedAtFailure) {
+            logger_1.logger.info(`  - ${o.migration.package}: ${o.migration.name}`);
+        }
+        logger_1.logger.info('');
+        logger_1.logger.info('Inspect with `git status` / `git diff` and either commit them manually or revert before re-running.');
+    }
+    if (migrationEmittedNextSteps.length > 0) {
+        logger_1.logger.info('');
+        logger_1.logger.info(`Notes from migrations that completed before the failure:`);
+        for (const step of migrationEmittedNextSteps) {
+            logger_1.logger.info(`  - ${step}`);
+        }
+    }
+    logger_1.logger.info('');
+    if (insideAgent) {
+        logger_1.logger.info(`Report the failure and the recap above to the user. They'll need to fix the failing migration and re-run \`nx migrate --run-migrations\` themselves.`);
+    }
+    else {
+        logger_1.logger.info(`Fix the failing migration and re-run \`nx migrate --run-migrations\` to resume.`);
+    }
+    logger_1.logger.info('');
+}
+/**
+ * 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.
+ */
+function buildTallyBodyLine(opts) {
+    const { appliedCount, committedShasCount, skippedPromptsCount, insideAgent } = opts;
+    const skipVerb = insideAgent ? 'deferred' : 'skipped';
+    if (appliedCount === 0) {
+        if (skippedPromptsCount === 0)
+            return null;
+        return `${skippedPromptsCount} prompt migration${skippedPromptsCount === 1 ? '' : 's'} ${skipVerb}.`;
+    }
+    const parts = [
+        `${appliedCount} migration${appliedCount === 1 ? '' : 's'} applied`,
+        `${committedShasCount} commit${committedShasCount === 1 ? '' : 's'} created`,
+    ];
+    if (skippedPromptsCount > 0) {
+        parts.push(`${skippedPromptsCount} prompt migration${skippedPromptsCount === 1 ? '' : 's'} ${skipVerb}`);
+    }
+    return `${parts.join(', ')}.`;
+}
+/**
+ * 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.
+ */
+function buildRetainedAtSuccessBody(retainedNames) {
+    return [
+        ...retainedNames.map((name) => `  - ${name}`),
+        '',
+        'Their changes are in the working tree. Inspect with `git status` / `git diff` and either commit them manually or revert.',
+    ];
+}
+/**
+ * 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.
+ */
+function buildDirectiveBlockBodyLines(opts) {
+    const { skippedPrompts, migrationEmittedNextSteps } = opts;
+    const hasDeferred = skippedPrompts.length > 0;
+    const hasNotes = migrationEmittedNextSteps.length > 0;
+    if (!hasDeferred && !hasNotes)
+        return [];
+    const lines = [];
+    if (hasDeferred) {
+        lines.push('Apply the deferred prompts below, in order:');
+        skippedPrompts.forEach((m, i) => {
+            const kindHint = (0, migration_shape_1.isHybridMigration)(m)
+                ? ' — hybrid prompt phase'
+                : ' — prompt-only migration';
+            lines.push(`  ${i + 1}. ${m.prompt}`);
+            lines.push(`       (${m.name}${kindHint})`);
+        });
+    }
+    if (hasNotes) {
+        if (hasDeferred)
+            lines.push('');
+        lines.push(hasDeferred
+            ? 'Then relay these migration-emitted notes to the user:'
+            : 'Relay these migration-emitted notes to the user:');
+        for (const step of migrationEmittedNextSteps) {
+            lines.push(`  - ${step}`);
+        }
+    }
+    lines.push('');
+    lines.push(hasDeferred && hasNotes
+        ? 'Finally, summarize what was done across the run and commit the changes per workspace conventions.'
+        : 'Then summarize what was done across the run and commit the changes per workspace conventions.');
+    return lines;
+}

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

@@ -2,8 +2,17 @@ import { MigrationsJson, PackageJsonUpdateForPackage as PackageUpdate } from '..
 import { NxJsonConfiguration } from '../../config/nx-json';
 import { FileChange } from '../../generators/tree';
 import { ArrayPackageGroup, PackageJson } from '../../utils/package-json';
+import { type MultiMajorMode } from './multi-major';
+import type { AgenticArg } from './agentic/select';
+import type { ResolvedAgentic } from './agentic/types';
+import { isHybridMigration, isPromptOnlyMigration } from './migration-shape';
+import { filterDowngradedUpdates } from './update-filters';
+import { normalizeVersion } from './version-utils';
+export { normalizeVersion };
 export interface ResolvedMigrationConfiguration extends MigrationsJson {
     packageGroup?: ArrayPackageGroup;
+    /** Prompt file contents keyed by the `prompt` value as it appears on the migration entry. */
+    resolvedPromptFiles?: Record<string, string>;
 }
 type CommandFailure = {
     message?: string;
@@ -11,7 +20,7 @@ type CommandFailure = {
     stdout?: string | Buffer;
 };
 export declare function formatCommandFailure(command: string, error: CommandFailure): string;
-export declare function normalizeVersion(version: string): string;
+export type MigrateMode = 'first-party' | 'third-party' | 'all';
 export interface MigratorOptions {
     packageJson?: PackageJson;
     nxInstallation?: NxJsonConfiguration['installation'];
@@ -25,6 +34,15 @@ export interface MigratorOptions {
     };
     interactive?: boolean;
     excludeAppliedMigrations?: boolean;
+    /**
+     * Restricts `packageJsonUpdates` filtering based on the value:
+     * - 'first-party' keeps only packages in `firstPartyPackages`
+     * - 'third-party' keeps only packages NOT in `firstPartyPackages`
+     * - 'all' / undefined keeps all packages (no filtering)
+     */
+    mode?: MigrateMode;
+    /** First-party package names used by `mode` for filtering. */
+    firstPartyPackages?: ReadonlySet<string>;
 }
 export declare class Migrator {
     private readonly packageJson?;
@@ -34,6 +52,8 @@ export declare class Migrator {
     private readonly to;
     private readonly interactive;
     private readonly excludeAppliedMigrations;
+    private readonly mode;
+    private readonly firstPartyPackages;
     private readonly packageUpdates;
     private readonly collectedVersions;
     private readonly promptAnswers;
@@ -42,6 +62,8 @@ export declare class Migrator {
     constructor(opts: MigratorOptions);
     private fetchMigrationConfig;
     migrate(targetPackage: string, targetVersion: string): Promise<{
+        minVersionWithSkippedUpdates: string;
+        promptContents?: Record<string, string>;
         packageUpdates: Record<string, PackageUpdate>;
         migrations: {
             package: string;
@@ -50,9 +72,9 @@ export declare class Migrator {
             description?: string;
             implementation?: string;
             factory?: string;
+            prompt?: string;
             requires?: Record<string, string>;
         }[];
-        minVersionWithSkippedUpdates: string;
     }>;
     private createMigrateJson;
     private buildPackageJsonUpdates;
@@ -68,6 +90,8 @@ export declare class Migrator {
      */
     private getPackageJsonUpdatesFromPackageGroup;
     private filterPackageJsonUpdates;
+    private shouldExcludePackage;
+    private applyModeFilter;
     private shouldApplyPackageUpdate;
     private validatePackageUpdateVersion;
     private addPackageUpdate;
@@ -83,6 +107,18 @@ export declare class Migrator {
     private lt;
     private lte;
 }
+/**
+ * The canonical Nx package for a given target version: `@nrwl/workspace` for
+ * legacy (`< 14.0.0-beta.0`), `nx` otherwise. Non-semver inputs (e.g. the
+ * literal `'latest'` sentinel before tag resolution) resolve to modern era.
+ * Used by `--mode=third-party` to silently swap `@nx/workspace` → `nx` when
+ * walking the cascade.
+ */
+export declare function resolveCanonicalNxPackage(targetVersion: string): 'nx' | '@nrwl/workspace';
+export declare function resolveMode(mode: MigrateMode | undefined, targetPackage: string, targetVersion: string, context?: {
+    hasFrom: boolean;
+    hasExcludeAppliedMigrations: boolean;
+}): Promise<MigrateMode>;
 type GenerateMigrations = {
     type: 'generateMigrations';
     targetPackage: string;
@@ -95,15 +131,31 @@ type GenerateMigrations = {
     };
     interactive?: boolean;
     excludeAppliedMigrations?: boolean;
+    mode: MigrateMode;
+    /**
+     * Set when multi-major redirected `targetVersion` to an incremental step
+     * (gradual mode or the interactive prompt picking a smaller jump). Holds
+     * the concrete resolved target so Next Steps can suggest re-running toward
+     * it.
+     */
+    originalTargetVersion?: string;
+    /**
+     * The `--multi-major-mode` value to propagate to a continuation command,
+     * or undefined to omit it. See `MultiMajorResult.gradual` for when it's set.
+     */
+    multiMajorMode?: MultiMajorMode;
 };
 type RunMigrations = {
     type: 'runMigrations';
     runMigrations: string;
     ifExists: boolean;
+    agentic: AgenticArg;
+    validate?: boolean;
 };
 export declare function parseMigrationsOptions(options: {
     [k: string]: any;
 }): Promise<GenerateMigrations | RunMigrations>;
+export { filterDowngradedUpdates };
 /**
  * Detects npm peer-dependency resolution failures. Keyed on the `ERESOLVE`
  * error code, which npm consistently emits for this class of failure across
@@ -112,29 +164,88 @@ export declare function parseMigrationsOptions(options: {
  * captured output.
  */
 export declare function isNpmPeerDepsError(stderr: string): boolean;
-export declare function executeMigrations(root: string, migrations: {
+type ExecutableMigration = {
     package: string;
     name: string;
     description?: string;
     version: string;
-}[], isVerbose: boolean, shouldCreateCommits: boolean, commitPrefix: string, shouldSkipInstall?: boolean): Promise<{
-    migrationsWithNoChanges: {
-        package: string;
-        name: string;
-        description?: string;
-        version: string;
-    }[];
+    implementation?: string;
+    factory?: string;
+    prompt?: string;
+};
+export { isPromptOnlyMigration, isHybridMigration };
+export declare function resolveAgenticRunId(migrations: ExecutableMigration[]): string;
+export declare function formatSkippedPromptsNextStep(skipped: ExecutableMigration[]): string;
+/**
+ * Resolves the effective `--create-commits` state once the agentic flow has
+ * been resolved. The agent's outer prompt only embeds the impl-phase file list
+ * when per-migration commits isolate each migration's diff, so the diff-context
+ * flag returned here gates that section.
+ */
+export declare function resolveCreateCommits(args: {
+    createCommits: boolean | undefined;
+    agenticKind: ResolvedAgentic['kind'];
+    isGitRepo: boolean;
+    /**
+     * Whether `--commit-prefix` was given a non-default value. When commits
+     * end up disabled, the prefix has no effect — the warning copy below
+     * surfaces that so the user isn't silently misled.
+     */
+    commitPrefixIsCustom?: boolean;
+}): {
+    effective: boolean;
+    agenticHasDiffContext: boolean;
+    warning?: string;
+    error?: string;
+};
+/**
+ * Resolves whether the framework-owned generic-validation agent step should run
+ * after generator-only migrations.
+ *
+ * Default-on when the agentic flow resolved to `enabled`; silently ignored
+ * otherwise (no warning emitted) — `--validate` requires an active agent
+ * session by definition. An explicit `--no-validate` (`validate === false`)
+ * opts out even when agentic is enabled.
+ */
+export declare function resolveShouldRunValidation(args: {
+    validate: boolean | undefined;
+    agenticKind: ResolvedAgentic['kind'];
+}): boolean;
+export declare function executeMigrations(root: string, migrations: ExecutableMigration[], isVerbose: boolean, shouldCreateCommits: boolean, commitPrefix: string, shouldSkipInstall?: boolean, agentic?: ResolvedAgentic, agenticHasDiffContext?: boolean, shouldRunValidation?: boolean): Promise<{
+    migrationsWithNoChanges: ExecutableMigration[];
+    skippedPromptsCount: number;
+    notRunMigrationsCount: number;
     nextSteps: string[];
+    skippedPrompts: ExecutableMigration[];
+    migrationEmittedNextSteps: string[];
+    committedShasCount: number;
+    retainedAtSuccess: string[];
 }>;
+export declare class ChangedDepInstaller {
+    private readonly root;
+    private readonly shouldSkipInstall;
+    private initialDeps;
+    private _skippedInstall;
+    constructor(root: string, shouldSkipInstall?: boolean);
+    get skippedInstall(): boolean;
+    installDepsIfChanged(): Promise<void>;
+}
 export declare function runNxOrAngularMigration(root: string, migration: {
     package: string;
     name: string;
     description?: string;
     version: string;
-}, isVerbose: boolean, shouldCreateCommits: boolean, commitPrefix: string, installDepsIfChanged?: () => Promise<void>, handleInstallDeps?: boolean): Promise<{
+}, isVerbose: boolean, captureGeneratorOutput?: boolean): Promise<{
     changes: FileChange[];
     nextSteps: string[];
+    agentContext: string[];
+    logs: string;
+    madeChanges: boolean;
 }>;
+export declare function parseMigrationReturn(value: unknown): {
+    nextSteps: string[];
+    agentContext: string[];
+};
 export declare function migrate(root: string, args: {
     [k: string]: any;
 }, rawArgs: string[]): Promise<number>;
@@ -148,4 +259,3 @@ export declare function getImplementationPath(collection: MigrationsJson, collec
     fnSymbol: string;
 };
 export declare function nxCliPath(nxWorkspaceRoot?: string): Promise<string>;
-export {};