nx 24.0.0-beta.1 → 24.0.0-beta.2

package/dist/src/command-line/migrate/run/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.treeOperationLabel = exports.commitsStep = exports.MigrateCommitBroker = exports.formatElapsed = exports.COMMIT_INSTALLS_FIRST = exports.BROKER_ENV_VAR = exports.renderExistingRunReport = exports.renderExistingRunCommands = exports.renderContinueCommand = exports.runOrchestratorResume = exports.runOrchestratorReconcile = exports.runOrchestratorInit = exports.releaseRunToHandOff = exports.holdRunToContinue = exports.completionWarnings = exports.activeRunToReplace = exports.runSingleMigrationWorker = exports.pmInstallCommand = exports.createRunId = exports.hasUnresolvedIssues = exports.tallySteps = exports.stepLabel = exports.runTallies = exports.latestRound = exports.hasPendingCommitDebt = exports.completionSummaryLines = exports.applyStepEvent = exports.TERMINAL_STEP_STATUSES = exports.createRun = exports.findActiveRun = exports.writeRunState = exports.readRunState = exports.runHandoffsDir = exports.runDir = exports.migrateRunsDir = exports.NewerRunStateFormatError = exports.CURRENT_RUN_STATE_FORMAT_VERSION = void 0;
+exports.treeOperationLabel = exports.commitsStep = exports.MigrateCommitBroker = exports.formatElapsed = exports.COMMIT_INSTALLS_FIRST = exports.BROKER_ENV_VAR = exports.renderExistingRunReport = exports.renderExistingRunCommands = exports.renderContinueCommand = exports.runOrchestratorResume = exports.runOrchestratorReconcile = exports.runOrchestratorInit = exports.releaseRunToHandOff = exports.holdRunToContinue = exports.deleteRunForStartFresh = exports.completionWarnings = exports.checkRunForStartFresh = exports.activeRunToReplace = exports.activeRunForClassic = exports.runSingleMigrationWorker = exports.pmInstallCommand = exports.createRunId = exports.hasUnresolvedIssues = exports.tallySteps = exports.stepLabel = exports.runTallies = exports.latestRound = exports.hasPendingCommitDebt = exports.completionSummaryLines = exports.applyStepEvent = exports.migrationIdProblems = exports.TERMINAL_STEP_STATUSES = exports.createRun = exports.findActiveRun = exports.writeRunState = exports.readRunState = exports.runHandoffsDir = exports.runDir = exports.migrateRunsDir = exports.NewerRunStateFormatError = exports.CURRENT_RUN_STATE_FORMAT_VERSION = void 0;
 var run_state_1 = require("./run-state");
 Object.defineProperty(exports, "CURRENT_RUN_STATE_FORMAT_VERSION", { enumerable: true, get: function () { return run_state_1.CURRENT_RUN_STATE_FORMAT_VERSION; } });
 Object.defineProperty(exports, "NewerRunStateFormatError", { enumerable: true, get: function () { return run_state_1.NewerRunStateFormatError; } });
@@ -12,6 +12,7 @@ Object.defineProperty(exports, "writeRunState", { enumerable: true, get: functio
 Object.defineProperty(exports, "findActiveRun", { enumerable: true, get: function () { return run_state_1.findActiveRun; } });
 Object.defineProperty(exports, "createRun", { enumerable: true, get: function () { return run_state_1.createRun; } });
 Object.defineProperty(exports, "TERMINAL_STEP_STATUSES", { enumerable: true, get: function () { return run_state_1.TERMINAL_STEP_STATUSES; } });
+Object.defineProperty(exports, "migrationIdProblems", { enumerable: true, get: function () { return run_state_1.migrationIdProblems; } });
 var state_machine_1 = require("./state-machine");
 Object.defineProperty(exports, "applyStepEvent", { enumerable: true, get: function () { return state_machine_1.applyStepEvent; } });
 Object.defineProperty(exports, "completionSummaryLines", { enumerable: true, get: function () { return state_machine_1.completionSummaryLines; } });
@@ -29,8 +30,11 @@ Object.defineProperty(exports, "pmInstallCommand", { enumerable: true, get: func
 var worker_1 = require("./worker");
 Object.defineProperty(exports, "runSingleMigrationWorker", { enumerable: true, get: function () { return worker_1.runSingleMigrationWorker; } });
 var orchestrator_1 = require("./orchestrator");
+Object.defineProperty(exports, "activeRunForClassic", { enumerable: true, get: function () { return orchestrator_1.activeRunForClassic; } });
 Object.defineProperty(exports, "activeRunToReplace", { enumerable: true, get: function () { return orchestrator_1.activeRunToReplace; } });
+Object.defineProperty(exports, "checkRunForStartFresh", { enumerable: true, get: function () { return orchestrator_1.checkRunForStartFresh; } });
 Object.defineProperty(exports, "completionWarnings", { enumerable: true, get: function () { return orchestrator_1.completionWarnings; } });
+Object.defineProperty(exports, "deleteRunForStartFresh", { enumerable: true, get: function () { return orchestrator_1.deleteRunForStartFresh; } });
 Object.defineProperty(exports, "holdRunToContinue", { enumerable: true, get: function () { return orchestrator_1.holdRunToContinue; } });
 Object.defineProperty(exports, "releaseRunToHandOff", { enumerable: true, get: function () { return orchestrator_1.releaseRunToHandOff; } });
 Object.defineProperty(exports, "runOrchestratorInit", { enumerable: true, get: function () { return orchestrator_1.runOrchestratorInit; } });

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

@@ -69,6 +69,27 @@ export declare function activeRunToReplace(root: string, runId: string | undefin
  * exclusive one refuses while this process still holds.
  */
 export declare function releaseRunToHandOff(root: string, runId: string): void;
+/**
+ * The active run a classic `--run-migrations` must not run over, held while
+ * the caller reports it or asks what to do; null when no run is active. Run
+ * directories that cannot be read refuse as they do for init.
+ */
+export declare function activeRunForClassic(root: string, plannedIds: readonly string[]): {
+    runId: string;
+    facts: ExistingRunFacts;
+} | null;
+/**
+ * Throws when a classic start fresh could not delete the active run `runId`.
+ * Run before the commit prompt, as init does, so the user is not asked for a
+ * run that is then refused; deleteRunForStartFresh repeats the checks.
+ */
+export declare function checkRunForStartFresh(root: string, runId: string): void;
+/**
+ * Deletes the record of the active run `runId` for a classic start fresh,
+ * under the refusals init applies before it replaces a run. The classic loop
+ * records no run of its own afterwards.
+ */
+export declare function deleteRunForStartFresh(root: string, runId: string): void;
 export declare function runOrchestratorReconcile(input: RunOrchestratorReconcileInput): Promise<void>;
 /**
  * What a completed run leaves behind for whoever reads its summary, one line

package/dist/src/command-line/migrate/run/orchestrator.js

@@ -5,6 +5,9 @@ exports.runOrchestratorResume = runOrchestratorResume;
 exports.holdRunToContinue = holdRunToContinue;
 exports.activeRunToReplace = activeRunToReplace;
 exports.releaseRunToHandOff = releaseRunToHandOff;
+exports.activeRunForClassic = activeRunForClassic;
+exports.checkRunForStartFresh = checkRunForStartFresh;
+exports.deleteRunForStartFresh = deleteRunForStartFresh;
 exports.runOrchestratorReconcile = runOrchestratorReconcile;
 exports.completionWarnings = completionWarnings;
 const child_process_1 = require("child_process");
@@ -42,7 +45,7 @@ const issues_1 = require("./issues");
 const runbook_1 = require("./runbook");
 const existing_run_report_1 = require("./existing-run-report");
 const package_manager_1 = require("../../../utils/package-manager");
-// The dark migrate orchestrator: drives a durable run one dispense at a time.
+// The migrate orchestrator: drives a durable run one dispense at a time.
 // An outer AI agent runs each dispensed command and re-invokes `nx migrate
 // --run-id=<id>` to reconcile; there is no long-lived process.
 const PLAN_SNAPSHOT_0 = 'plan-0.json';
@@ -55,7 +58,11 @@ const HANG_THRESHOLD_MS = 15 * 60 * 1000;
 const NO_PROGRESS_THRESHOLD = 3;
 // Two rearms per step: one for the diagnosed fix and one for its correction.
 const REARM_ESCALATION_CAP = 2;
-const INIT_CONTINUE_HINT = 're-run the command, or unset NX_MIGRATE_ORCHESTRATOR to use the standard migrate flow.';
+const INIT_CONTINUE_HINT = 're-run the command, or re-run it with --agentic=false to use the standard migrate flow.';
+const ID_PROBLEM_REFUSALS = {
+    'not-shell-safe': 'contains characters that are not shell-safe. Orchestrated runs require shell-safe migration ids.',
+    duplicate: 'is listed more than once in the plan. Orchestrated runs require each migration id once.',
+};
 function continueRunHint(runId) {
     return `re-run the command to continue run '${runId}'.`;
 }
@@ -92,9 +99,7 @@ function refuseUnsafeScratchExposure(exposure, thenWhat) {
 async function runOrchestratorInit(input) {
     const { root, migrationsJson, migrationsPath, createCommits, commitPrefix, skipInstall, installedNxVersion, validate, finalValidation, emitAgentInstructions = true, onExistingRun = 'report', replaceRunId, confirmStart, } = input;
     const migrations = (migrationsJson.migrations ?? []);
-    const sorted = (0, sort_migrations_1.sortMigrations)(migrations.slice(), {
-        hoistHandoffGitignore: true,
-    });
+    const sorted = (0, sort_migrations_1.sortMigrations)(migrations.slice());
     const plannedIds = sorted.map((m) => `${m.package}:${m.name}`);
     // An active run means a prior init already happened (e.g. it crashed before
     // the agent's first reconcile); starting a second run would compete with it,
@@ -124,13 +129,13 @@ async function runOrchestratorInit(input) {
             }
         });
     }
-    // Dispensed commands interpolate migration ids verbatim, so every init
-    // validates the incoming plan's ids. Before the delete below: a run must
-    // not be thrown away for a plan that cannot start.
-    for (const id of plannedIds) {
-        if (!run_state_1.SHELL_SAFE_VALUE.test(id)) {
-            throw new Error(`The migration id '${id}' contains characters that are not shell-safe. Orchestrated runs require shell-safe migration ids.`);
-        }
+    // Dispensed commands interpolate migration ids verbatim and a worker finds
+    // its step by id, so every init validates the incoming plan's ids. Before
+    // the delete below: a run must not be thrown away for a plan that cannot
+    // start.
+    const [idProblem] = (0, run_state_1.migrationIdProblems)(sorted);
+    if (idProblem !== undefined) {
+        throw new Error(`The migration id '${idProblem.id}' ${ID_PROBLEM_REFUSALS[idProblem.problem]} To run the plan without orchestration, re-run with --agentic=false.`);
     }
     if (confirmStart && !(await confirmStart())) {
         return { kind: 'refused' };
@@ -152,9 +157,8 @@ async function runOrchestratorInit(input) {
     // Applied before the checkpoint so the entry (when it can be added) already
     // covers older scratch by the time the checkpoint's `git add -A` runs; the
     // fallback's standalone commit is suppressed because that checkpoint
-    // carries the edit. Unlike the classic loop, a planned ignore migration
-    // can't be deferred to: the run dir is created below, before that
-    // migration runs.
+    // carries the edit. A planned ignore migration can't be deferred to: the
+    // run dir is created below, before that migration runs.
     await (0, handoff_gitignore_1.applyAgenticHandoffGitignoreFallback)({
         migrations: sorted,
         installedNxVersion,
@@ -314,11 +318,65 @@ function activeRunToReplace(root, runId) {
 function releaseRunToHandOff(root, runId) {
     (0, state_lock_1.releaseRunActivity)((0, run_state_1.runDir)(root, runId));
 }
+/**
+ * The active run a classic `--run-migrations` must not run over, held while
+ * the caller reports it or asks what to do; null when no run is active. Run
+ * directories that cannot be read refuse as they do for init.
+ */
+function activeRunForClassic(root, plannedIds) {
+    const active = findActiveRunForInit(root);
+    if (!active)
+        return null;
+    // Held before the facts are read, as init's report does.
+    (0, state_lock_1.holdRunActivity)(root, active.runId);
+    return {
+        runId: active.runId,
+        facts: (0, existing_run_report_1.collectExistingRunFacts)(root, active.runId, active.state, plannedIds),
+    };
+}
+/**
+ * Throws when a classic start fresh could not delete the active run `runId`.
+ * Run before the commit prompt, as init does, so the user is not asked for a
+ * run that is then refused; deleteRunForStartFresh repeats the checks.
+ */
+function checkRunForStartFresh(root, runId) {
+    (0, state_lock_1.withRunCreationLock)(root, () => {
+        const active = activeRunToDelete(root, runId);
+        refuseUndeletableRun(root, runId, active.state);
+    });
+}
+/**
+ * Deletes the record of the active run `runId` for a classic start fresh,
+ * under the refusals init applies before it replaces a run. The classic loop
+ * records no run of its own afterwards.
+ */
+function deleteRunForStartFresh(root, runId) {
+    const deleted = (0, state_lock_1.withRunCreationLock)(root, () => {
+        activeRunToDelete(root, runId);
+        return deleteRunRecord(root, runId);
+    });
+    if (deleted) {
+        removeDeletedRunDir(root, runId);
+    }
+}
+// Call under the creation lock. A run that became active since the user chose
+// is refused, never deleted in place of the one they saw.
+function activeRunToDelete(root, runId) {
+    refuseLiveReservation(root);
+    const active = findActiveRunForInit(root, true);
+    if (!active) {
+        throw new Error(noActiveRunToReplace(runId));
+    }
+    if (active.runId !== runId) {
+        throw new Error(`Not starting fresh: migrate run '${active.runId}' became active while this command was starting. Re-run the command to see it.`);
+    }
+    return active;
+}
 // Reads the newest active run; null when no run is active. Uninterpretable
 // run dirs refuse a fresh start (one of them could be an active run this
-// init would compete with) but only warn when a healthy active run is found,
-// unless `refuseUninterpretable`: a start-fresh would delete that run and
-// then find only the unreadable ones. NewerRunStateFormatError propagates
+// invocation would compete with) but only warn when a healthy active run is
+// found, unless `refuseUninterpretable`: a start-fresh would delete that run
+// and then find only the unreadable ones. NewerRunStateFormatError propagates
 // from the read.
 function findActiveRunForInit(root, refuseUninterpretable = false) {
     const { active, uninterpretable } = (0, run_state_1.findActiveRun)(root);
@@ -331,7 +389,7 @@ function findActiveRunForInit(root, refuseUninterpretable = false) {
         const details = uninterpretable.map((u) => `${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${(0, text_1.singleLine)(u.dirName)}: ${(0, text_1.singleLine)(u.reason)}`);
         if (!active || refuseUninterpretable) {
             throw new Error([
-                `Whether a migrate run is still active could not be determined; starting a new run could re-apply migrations an unfinished run already applied.`,
+                `Whether a migrate run is still active could not be determined; running the plan could re-apply migrations an unfinished run already applied.`,
                 ...details,
                 `Fix or remove the listed ${noun}, then re-run the command.`,
             ].join('\n'));

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

@@ -9,6 +9,19 @@ export declare const RUN_STATE_FILE_NAME = "run.json";
  * with fails closed as corrupt instead of being dispensed.
  */
 export declare const SHELL_SAFE_VALUE: RegExp;
+export type MigrationIdProblem = 'not-shell-safe' | 'duplicate';
+/**
+ * The ids of `migrations` that no orchestrated run can take, each once, in the
+ * order found. A worker finds its step by migration id, so an id the plan
+ * lists twice can't name one step.
+ */
+export declare function migrationIdProblems(migrations: ReadonlyArray<{
+    package: string;
+    name: string;
+}>): {
+    id: string;
+    problem: MigrationIdProblem;
+}[];
 export declare const ISSUE_ID: RegExp;
 declare const MIGRATE_RUN_STATUSES: readonly ['active', 'completed'];
 export type MigrateRunStatus = (typeof MIGRATE_RUN_STATUSES)[number];

package/dist/src/command-line/migrate/run/run-state.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NewerRunStateFormatError = exports.TREE_OPERATION_KINDS = exports.MIGRATE_ISSUE_DISPOSITIONS = exports.TERMINAL_STEP_STATUSES = exports.ISSUE_ID = exports.SHELL_SAFE_VALUE = exports.RUN_STATE_FILE_NAME = exports.CURRENT_RUN_STATE_FORMAT_VERSION = void 0;
+exports.migrationIdProblems = migrationIdProblems;
 exports.issueFingerprint = issueFingerprint;
 exports.migrateRunsDir = migrateRunsDir;
 exports.runDir = runDir;
@@ -32,6 +33,26 @@ exports.RUN_STATE_FILE_NAME = 'run.json';
  * with fails closed as corrupt instead of being dispensed.
  */
 exports.SHELL_SAFE_VALUE = /^[A-Za-z0-9@/:._-]+$/;
+/**
+ * The ids of `migrations` that no orchestrated run can take, each once, in the
+ * order found. A worker finds its step by migration id, so an id the plan
+ * lists twice can't name one step.
+ */
+function migrationIdProblems(migrations) {
+    const seen = new Set();
+    const problems = new Map();
+    for (const m of migrations) {
+        const id = `${m.package}:${m.name}`;
+        if (!exports.SHELL_SAFE_VALUE.test(id)) {
+            problems.set(id, 'not-shell-safe');
+        }
+        else if (seen.has(id) && !problems.has(id)) {
+            problems.set(id, 'duplicate');
+        }
+        seen.add(id);
+    }
+    return [...problems].map(([id, problem]) => ({ id, problem }));
+}
 // `new Date().toISOString()`, the only shape Nx writes. Retention and active-run
 // selection compare these lexicographically, and the value is rendered into the
 // stdout the agent scans for blocks, so neither a different notation nor an

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

@@ -5,12 +5,6 @@ interface SortableMigration {
 }
 /**
  * Sorts in place (like `Array.prototype.sort`) and returns the same array.
- *
- * `hoistHandoffGitignore` is set for agentic runs, which write scratch under
- * `.nx/migrate-runs`; see `agentic/handoff-gitignore.ts` for why the v23
- * gitignore migration must run first there.
  */
-export declare function sortMigrations<T extends SortableMigration>(migrations: T[], opts: {
-    hoistHandoffGitignore: boolean;
-}): T[];
+export declare function sortMigrations<T extends SortableMigration>(migrations: T[]): T[];
 export {};

package/dist/src/command-line/migrate/sort-migrations.js

@@ -2,23 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sortMigrations = sortMigrations;
 const semver_1 = require("semver");
-const types_1 = require("./agentic/types");
 const version_utils_1 = require("./version-utils");
 /**
  * Sorts in place (like `Array.prototype.sort`) and returns the same array.
- *
- * `hoistHandoffGitignore` is set for agentic runs, which write scratch under
- * `.nx/migrate-runs`; see `agentic/handoff-gitignore.ts` for why the v23
- * gitignore migration must run first there.
  */
-function sortMigrations(migrations, opts) {
+function sortMigrations(migrations) {
     return migrations.sort((a, b) => {
-        if (opts.hoistHandoffGitignore) {
-            if ((0, types_1.isHandoffGitignoreMigration)(a))
-                return -1;
-            if ((0, types_1.isHandoffGitignoreMigration)(b))
-                return 1;
-        }
         if (a.name === '15-7-0-split-configuration-into-project-json-files') {
             return -1;
         }

package/dist/src/config/nx-json.d.ts

@@ -711,7 +711,9 @@ export interface NxSyncConfiguration {
 export interface NxMigrateConfiguration {
     /**
      * Whether to automatically create a git commit after each migration runs.
-     * Equivalent to the `--create-commits` flag. Defaults to `false`.
+     * Equivalent to the `--create-commits` flag. Defaults to `true` when the
+     * agentic flow runs the migrations in a Git repository, and `false`
+     * otherwise.
      */
     createCommits?: boolean;
     /**
@@ -753,11 +755,18 @@ export interface NxMigrateConfiguration {
      */
     agentic?: boolean | AgentId;
     /**
-     * Whether to run agent-driven validation after generator-only migrations when
-     * the agentic flow is enabled. Equivalent to the `--validate` flag. Defaults
-     * to `true` when the agentic flow is enabled.
+     * Whether the AI agent driving a migrate run reviews the changes of
+     * generator-only migrations. Equivalent to the `--validate` flag. Defaults to
+     * `true`.
      */
     validate?: boolean;
+    /**
+     * Whether a migrate run an AI agent drives ends with a final check, where the
+     * agent makes sure the projects the run touched still lint, build, and pass
+     * their unit tests. Equivalent to the `--final-validation` flag. Defaults to
+     * `true`.
+     */
+    finalValidation?: boolean;
 }
 /**
  * Nx.json configuration

package/dist/src/config/workspace-json-project-json.d.ts

@@ -247,21 +247,33 @@ export interface TargetDependencyConfig {
      */
     waitFor?: 'started' | 'ready';
 }
+/**
+ * `always`: the files the input resolves to stay in the hash even when the task
+ * is hashed from its ultracache recording.
+ * `dependencies` with `projects`: the selected projects' dependencies (as `^input`
+ * resolves for each), not the projects themselves.
+ */
 export type InputDefinition = {
     input: string;
     projects: string | string[];
+    dependencies?: boolean;
+    always?: boolean;
 } | {
     input: string;
     dependencies: true;
+    always?: boolean;
 } | {
     input: string;
+    always?: boolean;
 } | {
     fileset: string;
     includeIgnored?: boolean;
+    always?: boolean;
 } | {
     fileset: string;
     dependencies: true;
     includeIgnored?: boolean;
+    always?: boolean;
 } | {
     runtime: string;
 } | {