nx 23.3.0-beta.0 → 23.3.0-pr.36841.f66e88b

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

@@ -14,6 +14,8 @@ const affected_project_graph_1 = require("../../project-graph/affected/affected-
 const configuration_1 = require("../../config/configuration");
 const find_matching_projects_1 = require("../../utils/find-matching-projects");
 const graph_1 = require("../graph/graph");
+const affected_tasks_1 = require("../../project-graph/affected/affected-tasks");
+const granularity_1 = require("../../project-graph/affected/granularity");
 async function affected(command, args, extraTargetDependencies = {}, extraOptions = {
     excludeTaskDependencies: args.excludeTaskDependencies,
     loadDotEnvFiles: process.env.NX_LOAD_DOT_ENV_FILES !== 'false',
@@ -28,7 +30,44 @@ async function affected(command, args, extraTargetDependencies = {}, extraOption
     const projectGraph = await (0, project_graph_1.createProjectGraphAsync)({
         exitOnError: true,
     });
-    const projects = await getAffectedGraphNodes(nxArgs, projectGraph);
+    const granularity = (0, granularity_1.resolveAffectedGranularity)();
+    // Task granularity needs a target to select against, so `nx graph --affected`
+    // and the deprecated print-affected stay project-grained.
+    const useTasks = granularity === 'task' &&
+        command === 'affected' &&
+        !!nxArgs.targets?.length;
+    let taskSelection;
+    let projects;
+    if (useTasks) {
+        const affectedTasks = await (0, affected_tasks_1.computeAffectedTasks)({
+            projectGraph,
+            nxJson,
+            targets: nxArgs.targets,
+            touchedFiles: (0, file_utils_1.calculateFileChanges)((0, command_line_utils_1.parseFiles)(nxArgs).files, nxArgs),
+            configuration: nxArgs.configuration,
+            overrides,
+            extraTargetDependencies,
+            excludeTaskDependencies: extraOptions.excludeTaskDependencies,
+        });
+        taskSelection = {
+            taskIds: [...affectedTasks.affectedTaskIds],
+            planningContext: affectedTasks.planningContext,
+        };
+        // --exclude is honoured in getAffectedGraphNodes, which this branch does
+        // not call. Dropping it would restart a project someone deliberately took
+        // out of the pipeline.
+        if (nxArgs.exclude?.length) {
+            const excluded = new Set((0, find_matching_projects_1.findMatchingProjects)(nxArgs.exclude, projectGraph.nodes));
+            taskSelection.taskIds = taskSelection.taskIds.filter((id) => !excluded.has(affectedTasks.taskGraph.tasks[id].target.project));
+        }
+        // runCommand still seeds the graph from projects; the prune is what narrows
+        // it back down to the selected tasks and their dependencies.
+        const owning = new Set(taskSelection.taskIds.map((id) => affectedTasks.taskGraph.tasks[id].target.project));
+        projects = [...owning].map((name) => projectGraph.nodes[name]);
+    }
+    else {
+        projects = await getAffectedGraphNodes(nxArgs, projectGraph);
+    }
     try {
         switch (command) {
             case 'affected': {
@@ -48,7 +87,7 @@ async function affected(command, args, extraTargetDependencies = {}, extraOption
                     }, projectNames);
                 }
                 else {
-                    const status = await (0, run_command_1.runCommand)(projectsWithTarget, projectGraph, { nxJson }, nxArgs, overrides, null, extraTargetDependencies, extraOptions);
+                    const status = await (0, run_command_1.runCommand)(projectsWithTarget, projectGraph, { nxJson }, nxArgs, overrides, null, extraTargetDependencies, extraOptions, taskSelection);
                     await output_1.output.drain();
                     process.exit(status);
                 }

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

@@ -18,15 +18,6 @@ const ignore_1 = require("../../utils/ignore");
 const object_sort_1 = require("../../utils/object-sort");
 const output_1 = require("../../utils/output");
 const workspace_root_1 = require("../../utils/workspace-root");
-/**
- * A table, not a `switch`: this lookup sits inside a `try` whose `catch`
- * reports "configured but not installed", and a `never` arm would throw into
- * that catch and be misreported. A missing member is a compile error here.
- */
-const resolveFormatterBin = {
-    oxfmt: oxfmt_1.getOxfmtBinPath,
-    prettier: prettier_1.getPrettierPath,
-};
 async function format(command, args) {
     const formatterType = (0, formatters_1.detectFormatter)(workspace_root_1.workspaceRoot);
     if (!formatterType) {
@@ -41,7 +32,7 @@ async function format(command, args) {
     // node_modules. Resolving now turns a raw MODULE_NOT_FOUND into something
     // actionable.
     try {
-        resolveFormatterBin[formatterType]();
+        formatters_1.resolveFormatterBin[formatterType]();
     }
     catch {
         output_1.output.error({

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

@@ -25,6 +25,7 @@ const create_task_graph_1 = require("../../tasks-runner/create-task-graph");
 const all_file_data_1 = require("../../utils/all-file-data");
 const command_line_utils_1 = require("../../utils/command-line-utils");
 const native_1 = require("../../native");
+const overrides_1 = require("../../io-snapshots/overrides");
 const transform_objects_1 = require("../../native/transform-objects");
 const affected_1 = require("../affected/affected");
 const nx_deps_cache_1 = require("../../project-graph/nx-deps-cache");
@@ -729,7 +730,9 @@ async function createTaskGraphClientResponse(pruneExternal = false) {
         const planner = new native_1.HashPlanner(nxJson, (0, native_1.transferProjectGraph)((0, transform_objects_1.transformProjectGraphForRust)(graph)));
         node_perf_hooks_1.performance.mark('task hash plan generation:start');
         const taskIds = Object.keys(taskGraph.tasks);
-        const plans = taskIds.length > 0 ? planner.getPlans(taskIds, taskGraph) : {};
+        const plans = taskIds.length > 0
+            ? getPlansWithIoSnapshots(planner, graph, nxJson, taskIds, taskGraph)
+            : {};
         node_perf_hooks_1.performance.mark('task hash plan generation:end');
         node_perf_hooks_1.performance.measure('task graph generation', 'task graph generation:start', 'task graph generation:end');
         node_perf_hooks_1.performance.measure('task hash plan generation', 'task hash plan generation:start', 'task hash plan generation:end');
@@ -807,7 +810,9 @@ async function createTaskGraphForTargetsAndProjects(targetNames, projectNames, c
         const planner = new native_1.HashPlanner(nxJson, (0, native_1.transferProjectGraph)((0, transform_objects_1.transformProjectGraphForRust)(graph)));
         node_perf_hooks_1.performance.mark('task hash plan generation:start');
         const taskIds = Object.keys(taskGraph.tasks);
-        const plans = taskIds.length > 0 ? planner.getPlans(taskIds, taskGraph) : {};
+        const plans = taskIds.length > 0
+            ? getPlansWithIoSnapshots(planner, graph, nxJson, taskIds, taskGraph)
+            : {};
         node_perf_hooks_1.performance.mark('task hash plan generation:end');
         node_perf_hooks_1.performance.measure(`task graph generation for ${targetNames.join(', ')}`, `task graph generation:start`, `task graph generation:end`);
         node_perf_hooks_1.performance.measure('task hash plan generation', 'task hash plan generation:start', 'task hash plan generation:end');
@@ -850,19 +855,40 @@ async function getExpandedTaskInputs(depGraphClientResponse, expandedTaskInputsC
     expandedTaskInputsCache.set(taskId, result);
     return result;
 }
+/** Plans with the HEAD bundle (never fetching); custom-hasher tasks are excluded like at hash time. */
+function getPlansWithIoSnapshots(planner, graph, nxJson, taskIds, taskGraph) {
+    const snapshots = (0, overrides_1.loadIoSnapshotsForHead)(nxJson) ?? undefined;
+    return planner.getPlans(taskIds, taskGraph, snapshots, snapshots ? (0, overrides_1.customHasherTaskIds)(graph, taskGraph) : undefined);
+}
 function expandInputs(inputs, project, allWorkspaceFiles, depGraphClientResponse) {
     const projectNames = depGraphClientResponse.projects.map((p) => p.name);
     const workspaceRootInputs = [];
     const projectRootInputs = [];
     const externalInputs = [];
     const otherInputs = [];
+    const filesInputs = [];
+    let snapshotBacked = false;
     inputs.forEach((input) => {
+        // Domain markers are not inputs, but they mean the `files` groups below
+        // are observed reads rather than user-declared inputs.
+        if (input.startsWith('io-snapshot:')) {
+            snapshotBacked = true;
+            return;
+        }
         // grouped workspace inputs look like workspace:[pattern,otherPattern]
         if (input.startsWith('workspace:[')) {
             const inputs = input.substring(11, input.length - 1).split(',');
             workspaceRootInputs.push(...inputs);
             return;
         }
+        // Disk-backed groups look like files:{project}:[glob,!otherGlob]. They
+        // expand on disk, so they must be matched before the `:` catch-all below
+        // classifies them as external dependencies.
+        const diskBacked = /^files:.*?:\[(.*)\]$/.exec(input);
+        if (diskBacked) {
+            filesInputs.push(diskBacked[1].split(','));
+            return;
+        }
         const maybeProjectName = input.split(':')[0];
         if (projectNames.includes(maybeProjectName)) {
             projectRootInputs.push(input);
@@ -881,6 +907,7 @@ function expandInputs(inputs, project, allWorkspaceFiles, depGraphClientResponse
         }
     });
     const workspaceRootsExpanded = getExpandedWorkspaceRoots(workspaceRootInputs, allWorkspaceFiles);
+    const filesExpanded = filesInputs.flatMap((globs) => (0, native_1.expandFilesInput)(workspace_root_1.workspaceRoot, globs));
     const otherInputsExpanded = otherInputs.map((input) => {
         if (input === 'TsConfig') {
             return (0, node_path_1.relative)(workspace_root_1.workspaceRoot, (0, typescript_1.getRootTsConfigPath)());
@@ -908,7 +935,14 @@ function expandInputs(inputs, project, allWorkspaceFiles, depGraphClientResponse
         return acc;
     }, {});
     return {
-        general: [...workspaceRootsExpanded, ...otherInputsExpanded],
+        general: [
+            ...workspaceRootsExpanded,
+            ...filesExpanded,
+            ...otherInputsExpanded,
+        ],
+        // The published panel only renders `general`/`external`, so observed
+        // files stay in `general` and are additionally labelled here.
+        ...(snapshotBacked ? { observed: filesExpanded } : {}),
         ...projectRootsExpanded,
         external: externalInputs,
     };

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

@@ -0,0 +1,14 @@
+import { FormatterType } from '../../../utils/formatters';
+/**
+ * The command the agent runs over the files it changed, with a `<paths>`
+ * placeholder. `--` keeps a path that starts with `-` from being read as an
+ * option.
+ */
+export declare function formatCommandFor(formatter: FormatterType, pmExec: string): string;
+/**
+ * Resolved per dispense so a migration's formatter change takes effect; the
+ * scope rules name the replacement commands for the step that made it. `null`
+ * when no formatter is configured or its binary cannot be resolved: under npm
+ * the command would otherwise make `npx` download it.
+ */
+export declare function resolveFormatCommand(root: string, pmExec: string): string | null;

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

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatCommandFor = formatCommandFor;
+exports.resolveFormatCommand = resolveFormatCommand;
+const formatters_1 = require("../../../utils/formatters");
+/**
+ * The command the agent runs over the files it changed, with a `<paths>`
+ * placeholder. `--` keeps a path that starts with `-` from being read as an
+ * option.
+ */
+function formatCommandFor(formatter, pmExec) {
+    switch (formatter) {
+        case 'prettier':
+            // --ignore-unknown skips files prettier has no parser for.
+            return `${pmExec} prettier --write --ignore-unknown -- <paths>`;
+        case 'oxfmt':
+            // oxfmt exits 2 when every path was skipped; the flag makes that
+            // success. Unlike prettier it skips unparseable files on its own.
+            return `${pmExec} oxfmt --no-error-on-unmatched-pattern -- <paths>`;
+        default: {
+            const unhandled = formatter;
+            throw new Error(`Unhandled formatter: ${unhandled}`);
+        }
+    }
+}
+/**
+ * Resolved per dispense so a migration's formatter change takes effect; the
+ * scope rules name the replacement commands for the step that made it. `null`
+ * when no formatter is configured or its binary cannot be resolved: under npm
+ * the command would otherwise make `npx` download it.
+ */
+function resolveFormatCommand(root, pmExec) {
+    const formatter = (0, formatters_1.detectFormatter)(root);
+    if (formatter === null) {
+        return null;
+    }
+    try {
+        formatters_1.resolveFormatterBin[formatter]();
+    }
+    catch {
+        return null;
+    }
+    return formatCommandFor(formatter, pmExec);
+}

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

@@ -1,3 +1,4 @@
+import { type BigIntStats } from 'fs';
 import { HandoffFile } from './types';
 /** Returns the run directory for a given workspace + run id (target version). */
 export declare function runDirPath(workspaceRoot: string, runId: string): string;
@@ -20,18 +21,16 @@ export declare function mkdirSafely(dir: string, purpose: string): void;
  */
 export declare function initRunDir(workspaceRoot: string, runId: string): string;
 /**
- * Absolute path of the handoff file for a migration step within a run, under
- * the run directory's `handoffs/` subtree: the pre-authorized write scope
- * stops there, so a handoff placed anywhere else costs an approval prompt.
- * The package's scope (if any) becomes a real subdirectory so the package name
- * stays readable; two packages can ship a migration with the same name without
- * colliding because they land in different package subdirectories. Each
- * segment is sanitized so the path is always writable on every platform.
+ * Sanitizing folds many characters to `_`, so distinct migrations can share a
+ * prefix. The SHA-256 of the raw package and name is what keeps their handoffs
+ * collision-resistant.
  */
 export declare function stepHandoffPath(runDir: string, migration: {
     package: string;
     name: string;
 }): string;
+/** Handoff path for a run step. No hash needed: step ids are unique within the run. */
+export declare function runStepHandoffPath(runDir: string, stepId: string): string;
 export type HandoffReadFailureReason = 'missing' | 'read-error' | 'parse-error' | 'shape-mismatch';
 export type HandoffReadResult = {
     ok: true;
@@ -42,19 +41,31 @@ export type HandoffReadResult = {
     detail?: string;
 };
 /**
- * Reads and validates a handoff file written by an agent. Returns a tagged
- * result so callers (the in-loop poller and the post-exit resolver) can
- * distinguish "file not yet written" from "file written but garbage" — the
- * latter is surfaced to the user instead of being collapsed into the same
- * generic ambiguous-outcome prompt.
+ * `lstat`, not `stat`: a symlink in the handoffs dir's place would send every
+ * handoff read and removal wherever it points.
  */
-export declare function readHandoffWithReason(filePath: string): HandoffReadResult;
+export declare function handoffsDirState(handoffsDir: string): 'directory' | 'missing' | 'other';
+/**
+ * Reads the file `stat` describes, refusing a symlink swapped in after the
+ * caller's lstat: O_NOFOLLOW fails the open with ELOOP, and O_NONBLOCK keeps a
+ * planted FIFO from blocking it. Windows has neither flag, so there the inode
+ * comparison is what catches a followed symlink. It does not guard against an
+ * unlink and recreate reusing the inode number. Read errors propagate: a file
+ * the agent cannot read must not pass.
+ */
+export declare function readInspectedFile(filePath: string, stat: BigIntStats, replacedMessage: string): string;
+/**
+ * Splits "not written yet" from "written but garbage" so callers can surface a
+ * malformed handoff instead of collapsing it into the generic
+ * ambiguous-outcome prompt.
+ */
+export declare function readHandoffWithReason(filePath: string, handoffsDir: string): HandoffReadResult;
 /**
  * Convenience wrapper preserving the original null-on-any-failure contract.
  * Used by the polling loop (`waitForValidHandoff`) where every failure mode
  * is "keep waiting" — the file may be missing, mid-write, or being rewritten.
  */
-export declare function readHandoff(filePath: string): HandoffFile | null;
+export declare function readHandoff(filePath: string, handoffsDir: string): HandoffFile | null;
 /**
  * Polls for a valid handoff file. Resolves once `readHandoff` accepts the
  * file's contents. Used to detect when the agent has finished its work so the
@@ -63,7 +74,7 @@ export declare function readHandoff(filePath: string): HandoffFile | null;
  *
  * Rejects with the abort reason when `options.signal` is aborted.
  */
-export declare function waitForValidHandoff(handoffFilePath: string, options?: {
+export declare function waitForValidHandoff(handoffFilePath: string, handoffsDir: string, options?: {
     intervalMs?: number;
     signal?: AbortSignal;
 }): Promise<void>;

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

@@ -5,9 +5,13 @@ exports.resolveAgenticRunId = resolveAgenticRunId;
 exports.mkdirSafely = mkdirSafely;
 exports.initRunDir = initRunDir;
 exports.stepHandoffPath = stepHandoffPath;
+exports.runStepHandoffPath = runStepHandoffPath;
+exports.handoffsDirState = handoffsDirState;
+exports.readInspectedFile = readInspectedFile;
 exports.readHandoffWithReason = readHandoffWithReason;
 exports.readHandoff = readHandoff;
 exports.waitForValidHandoff = waitForValidHandoff;
+const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const semver_1 = require("semver");
@@ -63,7 +67,7 @@ const WINDOWS_RESERVED_NAMES = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
 function sanitizeSegment(value) {
     if (value === '.' || value === '..')
         return '_';
-    let sanitized = value.replace(/[\x00-\x1f<>:"/\\|?*]/g, '_');
+    let sanitized = value.replace(/[\x00-\x1f<>:"/\\|?*+]/g, '_');
     // Windows forbids trailing dots/spaces on file/directory names.
     sanitized = sanitized.replace(/[. ]+$/, '');
     if (WINDOWS_RESERVED_NAMES.test(sanitized)) {
@@ -71,29 +75,105 @@ function sanitizeSegment(value) {
     }
     return sanitized || '_';
 }
+const HANDOFF_NAME_PREFIX_MAX_BYTES = 64;
+// Cuts on code points so a multibyte character is never split, and counts
+// UTF-8 bytes because the filesystem limit is per byte, not per character.
+function truncateUtf8(value, maxBytes) {
+    let out = '';
+    let used = 0;
+    for (const ch of value) {
+        const bytes = Buffer.byteLength(ch);
+        if (used + bytes > maxBytes)
+            break;
+        out += ch;
+        used += bytes;
+    }
+    return out;
+}
 /**
- * Absolute path of the handoff file for a migration step within a run, under
- * the run directory's `handoffs/` subtree: the pre-authorized write scope
- * stops there, so a handoff placed anywhere else costs an approval prompt.
- * The package's scope (if any) becomes a real subdirectory so the package name
- * stays readable; two packages can ship a migration with the same name without
- * colliding because they land in different package subdirectories. Each
- * segment is sanitized so the path is always writable on every platform.
+ * Sanitizing folds many characters to `_`, so distinct migrations can share a
+ * prefix. The SHA-256 of the raw package and name is what keeps their handoffs
+ * collision-resistant.
  */
 function stepHandoffPath(runDir, migration) {
-    return (0, path_1.join)(runDir, types_1.HANDOFFS_DIR_NAME, ...migration.package.split('/').map(sanitizeSegment), `${sanitizeSegment(migration.name)}.json`);
+    const prefix = truncateUtf8([...migration.package.split('/'), migration.name]
+        .map(sanitizeSegment)
+        .join('+'), HANDOFF_NAME_PREFIX_MAX_BYTES);
+    const hash = (0, crypto_1.createHash)('sha256')
+        .update(JSON.stringify([migration.package, migration.name]))
+        .digest('hex');
+    return (0, path_1.join)(runDir, types_1.HANDOFFS_DIR_NAME, `${prefix}-${hash}.json`);
+}
+/** Handoff path for a run step. No hash needed: step ids are unique within the run. */
+function runStepHandoffPath(runDir, stepId) {
+    return (0, path_1.join)(runDir, types_1.HANDOFFS_DIR_NAME, `${sanitizeSegment(stepId)}.json`);
+}
+/**
+ * `lstat`, not `stat`: a symlink in the handoffs dir's place would send every
+ * handoff read and removal wherever it points.
+ */
+function handoffsDirState(handoffsDir) {
+    try {
+        return (0, fs_1.lstatSync)(handoffsDir).isDirectory() ? 'directory' : 'other';
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return 'missing';
+        throw err;
+    }
 }
 /**
- * Reads and validates a handoff file written by an agent. Returns a tagged
- * result so callers (the in-loop poller and the post-exit resolver) can
- * distinguish "file not yet written" from "file written but garbage" — the
- * latter is surfaced to the user instead of being collapsed into the same
- * generic ambiguous-outcome prompt.
+ * Reads the file `stat` describes, refusing a symlink swapped in after the
+ * caller's lstat: O_NOFOLLOW fails the open with ELOOP, and O_NONBLOCK keeps a
+ * planted FIFO from blocking it. Windows has neither flag, so there the inode
+ * comparison is what catches a followed symlink. It does not guard against an
+ * unlink and recreate reusing the inode number. Read errors propagate: a file
+ * the agent cannot read must not pass.
  */
-function readHandoffWithReason(filePath) {
+function readInspectedFile(filePath, stat, replacedMessage) {
+    const fd = (0, fs_1.openSync)(filePath, fs_1.constants.O_RDONLY |
+        (fs_1.constants.O_NOFOLLOW ?? 0) |
+        (fs_1.constants.O_NONBLOCK ?? 0));
+    try {
+        const fdStat = (0, fs_1.fstatSync)(fd, { bigint: true });
+        if (!fdStat.isFile() ||
+            fdStat.dev !== stat.dev ||
+            fdStat.ino !== stat.ino) {
+            throw new Error(replacedMessage);
+        }
+        return (0, fs_1.readFileSync)(fd, 'utf-8');
+    }
+    finally {
+        (0, fs_1.closeSync)(fd);
+    }
+}
+/**
+ * Splits "not written yet" from "written but garbage" so callers can surface a
+ * malformed handoff instead of collapsing it into the generic
+ * ambiguous-outcome prompt.
+ */
+function readHandoffWithReason(filePath, handoffsDir) {
     let raw;
     try {
-        raw = (0, fs_1.readFileSync)(filePath, 'utf-8');
+        switch (handoffsDirState(handoffsDir)) {
+            case 'missing':
+                return { ok: false, reason: 'missing' };
+            case 'other':
+                return {
+                    ok: false,
+                    reason: 'read-error',
+                    detail: `${handoffsDir} is not a directory`,
+                };
+        }
+        const stat = (0, fs_1.lstatSync)(filePath, { bigint: true });
+        if (!stat.isFile()) {
+            return {
+                ok: false,
+                reason: 'read-error',
+                detail: `${filePath} is not a regular file`,
+            };
+        }
+        raw = readInspectedFile(filePath, stat, `${filePath} was replaced while being read`);
     }
     catch (err) {
         const code = err?.code;
@@ -148,8 +228,8 @@ function readHandoffWithReason(filePath) {
  * Used by the polling loop (`waitForValidHandoff`) where every failure mode
  * is "keep waiting" — the file may be missing, mid-write, or being rewritten.
  */
-function readHandoff(filePath) {
-    const result = readHandoffWithReason(filePath);
+function readHandoff(filePath, handoffsDir) {
+    const result = readHandoffWithReason(filePath, handoffsDir);
     return result.ok ? result.handoff : null;
 }
 /**
@@ -160,7 +240,7 @@ function readHandoff(filePath) {
  *
  * Rejects with the abort reason when `options.signal` is aborted.
  */
-function waitForValidHandoff(handoffFilePath, options = {}) {
+function waitForValidHandoff(handoffFilePath, handoffsDir, options = {}) {
     const intervalMs = options.intervalMs ?? 500;
     const { signal } = options;
     return new Promise((resolve, reject) => {
@@ -180,7 +260,7 @@ function waitForValidHandoff(handoffFilePath, options = {}) {
                 onAbort();
                 return;
             }
-            if (readHandoff(handoffFilePath) !== null) {
+            if (readHandoff(handoffFilePath, handoffsDir) !== null) {
                 signal?.removeEventListener('abort', onAbort);
                 resolve();
                 return;

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

@@ -0,0 +1,16 @@
+export declare function renderNxInvocationNote(packageManager: string, nxInvocation: string): string;
+export declare function renderHandoffShapeInline(summaryHint: string): string;
+export declare function renderHandoffShapeLines(): string[];
+/**
+ * Where the formatter command comes from. A prompt built right before the
+ * agent runs carries the resolved command; the runbook outlives many steps,
+ * so it points at the `Format command:` line each dispensed step resolves.
+ */
+export type FormatInstruction = {
+    source: 'command';
+    command: string | null;
+} | {
+    source: 'dispensed-step';
+};
+export declare function renderAuthorScopeRuleLines(pmExec: string, format: FormatInstruction): string[];
+export declare function renderValidationScopeRuleLines(): string[];

package/dist/src/command-line/migrate/agentic/prompts/fragments.js

@@ -0,0 +1,70 @@
+"use strict";
+// Wording the agent system prompt (system-prompt.ts) and the orchestrated
+// run's runbook (run/runbook.ts) must state identically.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderNxInvocationNote = renderNxInvocationNote;
+exports.renderHandoffShapeInline = renderHandoffShapeInline;
+exports.renderHandoffShapeLines = renderHandoffShapeLines;
+exports.renderAuthorScopeRuleLines = renderAuthorScopeRuleLines;
+exports.renderValidationScopeRuleLines = renderValidationScopeRuleLines;
+const format_command_1 = require("../format-command");
+function renderNxInvocationNote(packageManager, nxInvocation) {
+    return `Use \`${packageManager}\` for any package-manager invocation in this workspace. To invoke nx, use \`${nxInvocation} ...\`. Do not default to a different package manager based on your own preference.`;
+}
+// One-line form for a dispensed step; the block form is the contract itself.
+function renderHandoffShapeInline(summaryHint) {
+    return `{ "status": "success" | "failed", "summary": "<${summaryHint}>" }`;
+}
+function renderHandoffShapeLines() {
+    return [
+        `{`,
+        `  "status": "success" | "failed",`,
+        `  "summary": "[one to three sentences: what was done, or why it failed]"`,
+        `}`,
+    ];
+}
+function renderAuthorScopeRuleLines(pmExec, format) {
+    return [
+        `- Apply only the changes the migration prompt asks for.`,
+        `- Do not refactor or update dependencies beyond what the migration prompt directs, and do not reformat files you did not change.`,
+        renderFormatRule(pmExec, format),
+        `- Do not modify files outside the workspace root.`,
+        `- Do not run \`nx\` commands that mutate workspace state (\`nx migrate\`, \`nx reset\`, \`nx format:write\`, \`nx run-many\`, generators, etc.). Read-only inspection (\`nx show\`, \`nx graph --file\`, reading files) is fine.`,
+        `- If the migration instructions are unclear, internally inconsistent, or conflict with the current workspace state, ask the user for direction (see the handoff contract). Do not guess.`,
+    ];
+}
+const FORMAT_SCOPE = `over exactly the files you created or modified`;
+// oxfmt with no paths formats every file under cwd (its no-target default,
+// with or without the flag), so the no-files case must be said explicitly.
+const NO_FILES = `If you created or modified no files, do not run it.`;
+const NO_NX_FORMAT = `Do not use \`nx format:write\` for this: it also selects files changed earlier on the branch and always reformats the root config files.`;
+function renderFormatRule(pmExec, format) {
+    // The command is resolved before the step runs, so the step that adds or
+    // replaces the formatter is the one case it cannot cover; name the exact
+    // replacements so the agent does not have to guess flags.
+    const replacement = `If this migration itself added or replaced the workspace formatter, run the new one ${FORMAT_SCOPE} instead: \`${(0, format_command_1.formatCommandFor)('prettier', pmExec)}\` for Prettier, \`${(0, format_command_1.formatCommandFor)('oxfmt', pmExec)}\` for oxfmt, but only if it is installed under node_modules; if it is not, do not install or run it. ${NO_FILES}`;
+    switch (format.source) {
+        case 'command':
+            return format.command === null
+                ? `- No configured formatter is installed in this workspace; do not install or run one over your changes. ${replacement}`
+                : `- After applying your changes and before writing the handoff, run \`${format.command}\` ${FORMAT_SCOPE} (the flag keeps the command from failing when some or all of those paths are files the formatter does not handle). ${replacement} ${NO_NX_FORMAT}`;
+        case 'dispensed-step':
+            return `- After applying your changes and before writing the handoff, run the command on the dispensed step's \`Format command:\` line ${FORMAT_SCOPE}; when that line says none, do not run a formatter. ${replacement} ${NO_NX_FORMAT}`;
+        default: {
+            const unhandled = format;
+            throw new Error(`Unhandled format instruction: ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+function renderValidationScopeRuleLines() {
+    return [
+        `- Your job is to validate the generator's changes. Inspect the listed changes, run the smallest relevant set of verification tasks, and report findings.`,
+        `- Discover what targets exist before running tasks: \`nx show project <name> --json\` is authoritative, since it includes targets inferred by plugins. Reading a project's \`project.json\` / \`package.json\` misses inferred targets; treat it as an incomplete fallback for when the project graph cannot be built. Do not assume specific target names (\`typecheck\`, \`test\`, \`lint\`) are available, since workspaces vary. Run what the project actually has; if no typecheck-equivalent exists, \`build\` is an acceptable substitute.`,
+        `- You may run nx tasks for verification, scoped to this migration's changes: \`nx affected --files=<comma-separated changed paths> -t <target>\` (\`--files\` splits on every comma, so pipe paths one per line into \`nx affected --stdin -t <target>\` when a changed path contains one), \`nx run <project>:<target>\`, or \`nx run-many -t <target> -p <project1>,<project2>\` where the project list is derived from the changed files. Bare \`nx affected\` (no \`--files\`) selects the branch delta plus everything uncommitted, and unscoped \`nx run-many\` (no \`-p\`) is forbidden.`,
+        `- Read-only and artifact-writing inspection commands are permitted: \`nx show project\`, \`nx graph --file <path>\`, reading files. These do not mutate workspace source.`,
+        `- You may apply minor fixes only when the issue lies within the scope of what this migration intended to accomplish (e.g. a missing import the generator's template should have produced, a type annotation the template missed). Do not refactor, do not modify unrelated functionality, do not extend the migration's scope, do not touch code the migration was not concerned with. If you are unsure whether a fix is in scope, report it in \`summary\` instead of applying.`,
+        `- Do not run other \`nx\` commands that mutate workspace state (\`nx migrate\`, \`nx reset\`, generators, etc.).`,
+        `- Do not modify files outside the workspace root.`,
+        `- If validation finds blocking issues you cannot resolve within scope: apply every fix you can within scope, then report the unresolved findings to the user and ask how to proceed (see the handoff contract). Do not guess.`,
+    ];
+}

package/dist/src/command-line/migrate/agentic/prompts/generic-validation.js

@@ -39,10 +39,11 @@ function buildGenericValidationUserPrompt(ctx) {
     if (agentContext.length > 0) {
         lines.push(...(0, shared_rendering_1.renderAdvisoryContext)('hints emitted by the generator; treat as supplementary context, not separate tasks', agentContext));
     }
+    const targetDiscovery = `discover each project's targets with \`nx show project <name> --json\`, which includes targets inferred by plugins (reading \`project.json\` / \`package.json\` misses those; fall back to it only if the project graph cannot be built). Do not assume \`typecheck\` / \`test\` / \`lint\` exist. If no typecheck-equivalent exists, \`build\` is an acceptable substitute.`;
     const firstStep = ctx.impl.hasDiffContext
-        ? `1. Inspect this migration's changes. ${(0, shared_rendering_1.renderGitInspectInstruction)()} Resolve each affected path to its owning Nx project via \`nx show project <name>\` (or by reading the project's \`project.json\` / \`package.json\`) to discover which targets each project actually defines — do not assume \`typecheck\` / \`test\` / \`lint\` exist. If no typecheck-equivalent exists, \`build\` is an acceptable substitute.`
-        : `1. Resolve each path in <files_changed> to its owning Nx project. Use \`nx show project <name>\` (or read the project's \`project.json\` / \`package.json\`) to discover which targets each project actually defines — do not assume \`typecheck\` / \`test\` / \`lint\` exist. If no typecheck-equivalent exists, \`build\` is an acceptable substitute.`;
-    lines.push(``, `<validation_instructions>`, firstStep, `2. Pick the smallest relevant subset of available targets to verify the change. Prefer \`nx affected -t <target>\` (or \`nx run <project>:<target>\` for a single project). When many small projects are affected, you may use \`nx run-many -t <target> -p <project1>,<project2>\` with the project list derived from the changed files. Unscoped \`nx run-many\` (no \`-p\`) is forbidden.`, `3. If a verification surfaces an issue the migration should have produced cleanly (e.g. a missing import, a type annotation the generator's template missed), you may apply a minor in-scope fix. The boundary is "what this migration intended to accomplish" — do not refactor, do not modify functionality unrelated to the migration, do not extend the migration's scope, do not touch code the migration was not concerned with. If you are unsure whether a fix is in scope, report it in \`summary\` instead of applying.`, `4. Apply every fix you can within scope, then end the step per the handoff contract. If everything is resolved, write your handoff with \`status: "success"\`, summarizing what you verified and any fixes you applied. If unresolved findings remain, report them to the user and ask how to proceed before writing any handoff; on a \`status: "failed"\` handoff, enumerate the findings in \`summary\` so the user can address them — no commit will be created from a failed run, so the generator's changes and your partial fixes will sit uncommitted in the working tree for the user to review.`, `</validation_instructions>`, ``, `When you end the step per the handoff contract, your handoff path is:`, ...(0, shared_rendering_1.renderHandoffPathFooter)(ctx.handoffFileAbsolutePath));
+        ? `1. Inspect this migration's changes. ${(0, shared_rendering_1.renderGitInspectInstruction)()} Resolve each affected path to its owning Nx project, then ${targetDiscovery}`
+        : `1. Resolve each path in <files_changed> to its owning Nx project, then ${targetDiscovery}`;
+    lines.push(``, `<validation_instructions>`, firstStep, `2. Pick the smallest relevant subset of available targets to verify the change. Prefer \`nx affected --files=<comma-separated changed paths> -t <target>\` with the changed file list (bare \`nx affected\` also selects the branch delta and unrelated uncommitted changes). \`--files\` splits on every comma, so when a changed path contains one, pipe the paths one per line into \`nx affected --stdin -t <target>\` instead (POSIX shells: \`printf '%s\\n' <paths> | nx affected --stdin -t <target>\`). Alternatively, use \`nx run <project>:<target>\` for a single project. When many small projects are affected, you may use \`nx run-many -t <target> -p <project1>,<project2>\` with the project list derived from the changed files. Unscoped \`nx run-many\` (no \`-p\`) is forbidden.`, `3. If a verification surfaces an issue the migration should have produced cleanly (e.g. a missing import, a type annotation the generator's template missed), you may apply a minor in-scope fix. The boundary is "what this migration intended to accomplish" — do not refactor, do not modify functionality unrelated to the migration, do not extend the migration's scope, do not touch code the migration was not concerned with. If you are unsure whether a fix is in scope, report it in \`summary\` instead of applying.`, `4. Apply every fix you can within scope, then end the step per the handoff contract. If everything is resolved, write your handoff with \`status: "success"\`, summarizing what you verified and any fixes you applied. If unresolved findings remain, report them to the user and ask how to proceed before writing any handoff; on a \`status: "failed"\` handoff, enumerate the findings in \`summary\` so the user can address them — no commit will be created from a failed run, so the generator's changes and your partial fixes will sit uncommitted in the working tree for the user to review.`, `</validation_instructions>`, ``, `When you end the step per the handoff contract, your handoff path is:`, ...(0, shared_rendering_1.renderHandoffPathFooter)(ctx.handoffFileAbsolutePath));
     return lines.join('\n');
 }
 function renderFileListBody(changes) {

package/dist/src/command-line/migrate/agentic/prompts/system-prompt.d.ts

@@ -25,9 +25,17 @@ export interface SystemPromptContext {
      *   a generator's output. Constraints allow scoped task execution and minor
      *   in-scope fixes.
      *
-     * Defaults to `author` so existing call sites remain unchanged.
+     * Defaults to `author`.
      */
     mode?: AgenticPromptMode;
+    /**
+     * Exact formatter command for the files the agent changed (see
+     * `resolveFormatCommand`), or `null` when none can be resolved. Ignored for
+     * `generic-validation` prompts; pass `null` there without probing, since
+     * formatter detection can warn.
+     */
+    formatCommand: string | null;
+    pmExec: string;
 }
 /**
  * Builds the agent-agnostic system prompt used for all prompt-migration steps.