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

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

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDirPath = runDirPath;
+exports.mkdirSafely = mkdirSafely;
+exports.initRunDir = initRunDir;
+exports.stepHandoffPath = stepHandoffPath;
+exports.readHandoffWithReason = readHandoffWithReason;
+exports.readHandoff = readHandoff;
+exports.waitForValidHandoff = waitForValidHandoff;
+const fs_1 = require("fs");
+const path_1 = require("path");
+/** Returns the run directory for a given workspace + run id (target version). */
+function runDirPath(workspaceRoot, runId) {
+    return (0, path_1.join)(workspaceRoot, '.nx', 'migrate-runs', runId);
+}
+/**
+ * `mkdir -p` with a contextual error wrapper. Without this, the raw
+ * ENOSPC/EACCES/EROFS surfaces with no indication of which directory the
+ * migrate orchestrator was trying to create.
+ */
+function mkdirSafely(dir, purpose) {
+    try {
+        (0, fs_1.mkdirSync)(dir, { recursive: true });
+    }
+    catch (err) {
+        const code = err?.code;
+        // `{ cause }` preserves the original ErrnoException so callers can read
+        // `.cause.code`/`.cause.path`/`.cause.syscall` for targeted remediation.
+        // Without it the only signal beyond the formatted message would be the
+        // code string we splice in below.
+        throw new Error(`Could not create ${purpose} at ${dir}${code ? ` (${code})` : ''}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+}
+/**
+ * Wipes any prior contents for this run id and recreates an empty directory.
+ *
+ * Scope of the wipe is intentionally narrow (only `<run-id>/`) so that handoff
+ * artifacts from prior runs targeting different versions remain on disk for
+ * inspection.
+ */
+function initRunDir(workspaceRoot, runId) {
+    const dir = runDirPath(workspaceRoot, runId);
+    (0, fs_1.rmSync)(dir, { recursive: true, force: true });
+    mkdirSafely(dir, 'nx migrate run directory');
+    return dir;
+}
+// Windows reserved device names fail to open even with an extension —
+// a migration named `CON` would otherwise produce a `CON.json` that the
+// agent can't write to.
+const WINDOWS_RESERVED_NAMES = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
+/**
+ * The bare `.` / `..` check must come first — otherwise a malformed migration
+ * name of exactly `..` would let the handoff write escape the run directory.
+ */
+function sanitizeSegment(value) {
+    if (value === '.' || value === '..')
+        return '_';
+    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)) {
+        sanitized = `_${sanitized}`;
+    }
+    return sanitized || '_';
+}
+/**
+ * Absolute path of the handoff file for a migration step within a run.
+ * 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.
+ */
+function stepHandoffPath(runDir, migration) {
+    return (0, path_1.join)(runDir, ...migration.package.split('/').map(sanitizeSegment), `${sanitizeSegment(migration.name)}.json`);
+}
+/**
+ * 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.
+ */
+function readHandoffWithReason(filePath) {
+    let raw;
+    try {
+        raw = (0, fs_1.readFileSync)(filePath, 'utf-8');
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === 'ENOENT')
+            return { ok: false, reason: 'missing' };
+        return {
+            ok: false,
+            reason: 'read-error',
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: 'parse-error',
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+    if (!parsed ||
+        typeof parsed !== 'object' ||
+        Array.isArray(parsed) ||
+        typeof parsed.summary !== 'string') {
+        return { ok: false, reason: 'shape-mismatch' };
+    }
+    const obj = parsed;
+    const status = obj.status;
+    const summary = obj.summary;
+    if (status !== 'success' && status !== 'failed') {
+        return { ok: false, reason: 'shape-mismatch' };
+    }
+    // Null-prototype object guards against a prototype-pollution gadget:
+    // JSON.parse materializes `__proto__` as an own enumerable property, and
+    // a rest-spread would carry it through to wherever extras gets merged.
+    const extras = Object.create(null);
+    for (const key of Object.keys(obj)) {
+        if (key === 'status' || key === 'summary')
+            continue;
+        extras[key] = obj[key];
+    }
+    const handoff = { status, summary: summary };
+    if (Object.keys(extras).length > 0) {
+        handoff.extras = extras;
+    }
+    return { ok: true, handoff };
+}
+/**
+ * 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.
+ */
+function readHandoff(filePath) {
+    const result = readHandoffWithReason(filePath);
+    return result.ok ? result.handoff : 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
+ * orchestrator can close the agent's session without depending on the agent
+ * exiting on its own.
+ *
+ * Rejects with the abort reason when `options.signal` is aborted.
+ */
+function waitForValidHandoff(handoffFilePath, options = {}) {
+    const intervalMs = options.intervalMs ?? 500;
+    const { signal } = options;
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason ?? new Error('aborted'));
+            return;
+        }
+        let timer;
+        const onAbort = () => {
+            if (timer)
+                clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            reject(signal.reason ?? new Error('aborted'));
+        };
+        const tick = () => {
+            if (signal?.aborted) {
+                onAbort();
+                return;
+            }
+            if (readHandoff(handoffFilePath) !== null) {
+                signal?.removeEventListener('abort', onAbort);
+                resolve();
+                return;
+            }
+            timer = setTimeout(tick, intervalMs);
+        };
+        signal?.addEventListener('abort', onAbort);
+        timer = setTimeout(tick, intervalMs);
+    });
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Returns true when `nx migrate` is itself being run from inside another AI
+ * agent's terminal session. Used to short-circuit the agentic flow so we never
+ * spawn an inner agent inside an outer agent.
+ *
+ * Native `isAiAgent()` covers all supported agents (Claude Code, Cursor,
+ * OpenCode, Codex, Gemini, Replit) via parent-process env-var sniffing.
+ */
+export declare function isInsideAgent(): boolean;

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

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInsideAgent = isInsideAgent;
+const native_1 = require("../../../native");
+/**
+ * Returns true when `nx migrate` is itself being run from inside another AI
+ * agent's terminal session. Used to short-circuit the agentic flow so we never
+ * spawn an inner agent inside an outer agent.
+ *
+ * Native `isAiAgent()` covers all supported agents (Claude Code, Cursor,
+ * OpenCode, Codex, Gemini, Replit) via parent-process env-var sniffing.
+ */
+function isInsideAgent() {
+    return (0, native_1.isAiAgent)();
+}

package/dist/src/command-line/migrate/agentic/print-dropped-agent-context.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Surfaces a migration's `agentContext` to stdout in an XML-tagged block so an
+ * outer AI agent driving `nx migrate` can ingest the hints when no inner agent
+ * step ran to consume them.
+ *
+ * Used only when `agentic.kind === 'inside-agent'`. Under `enabled`, the inner
+ * step consumes `agentContext` via the prompt builders. Under `disabled` the
+ * run is human-driven and printing agent-targeted context would only add noise.
+ *
+ * The label format is unambiguous so the outer agent can locate the block
+ * within the mixed stdout stream (logger output, migration progress, etc.).
+ */
+export interface DroppedAgentContextInput {
+    migration: {
+        package: string;
+        name: string;
+        prompt?: string;
+    };
+    agentContext: string[];
+}
+export declare function formatDroppedAgentContextForOuterAgent(input: DroppedAgentContextInput): string;
+export declare function printDroppedAgentContextForOuterAgent(input: DroppedAgentContextInput): void;

package/dist/src/command-line/migrate/agentic/print-dropped-agent-context.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatDroppedAgentContextForOuterAgent = formatDroppedAgentContextForOuterAgent;
+exports.printDroppedAgentContextForOuterAgent = printDroppedAgentContextForOuterAgent;
+const shared_rendering_1 = require("./prompts/shared-rendering");
+function formatDroppedAgentContextForOuterAgent(input) {
+    const entries = (0, shared_rendering_1.filterNonEmptyStrings)(input.agentContext);
+    if (entries.length === 0) {
+        return '';
+    }
+    const id = `${input.migration.package}:${input.migration.name}`;
+    // Migration metadata and agentContext entries are user-authored (migrations
+    // are published by third-party packages); escape any `<` / `&` so a hostile
+    // value can't break out of the surrounding XML-framed block. The agent
+    // reads `&lt;/agent_context&gt;` as literal text, not a closing tag.
+    const safeName = (0, shared_rendering_1.escapeXmlBody)(input.migration.name);
+    const safePrompt = input.migration.prompt
+        ? (0, shared_rendering_1.escapeXmlBody)(input.migration.prompt)
+        : undefined;
+    const preamble = safePrompt
+        ? `ℹ Hints from the ${safeName} generator for the AI agent driving this run, when applying ${safePrompt}:`
+        : `ℹ Hints from the ${safeName} generator for the AI agent driving this run:`;
+    return [
+        preamble,
+        ``,
+        `<agent_context migration="${escapeXmlAttr(id)}">`,
+        ...entries.map((entry) => (0, shared_rendering_1.renderListItem)((0, shared_rendering_1.escapeXmlBody)(entry))),
+        `</agent_context>`,
+    ].join('\n');
+}
+// Migration package/name come from arbitrary user-authored package.json /
+// migrations.json — a name with `"` / `<` / `>` / `&` would produce malformed
+// XML the outer agent can't parse. `'` is not strictly required for
+// double-quoted attribute values but is included for defense.
+function escapeXmlAttr(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+function printDroppedAgentContextForOuterAgent(input) {
+    const block = formatDroppedAgentContextForOuterAgent(input);
+    if (block) {
+        // Bare newline pair frames the block so adjacent stdout (logger output,
+        // migration progress) doesn't run into the opening or closing tag.
+        process.stdout.write(`\n${block}\n\n`);
+    }
+}

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

@@ -0,0 +1,51 @@
+import type { FileChange } from '../../../../generators/tree';
+export interface GenericValidationPromptContext {
+    package: string;
+    name: string;
+    version: string;
+    description?: string;
+    /** Absolute path the agent must write its handoff file to. */
+    handoffFileAbsolutePath: string;
+    /** Context captured from the deterministic generator phase. */
+    impl: {
+        /** Raw output from the generator (devkit logger + console). */
+        logs?: string;
+        /**
+         * Files the generator changed. Rendered inside `<files_changed>` as a
+         * `[TYPE] path` list — only when `hasDiffContext` is false; when true the
+         * agent is instead instructed to inspect via git.
+         */
+        changes: FileChange[];
+        /** Strings the generator author put in `agentContext`. */
+        agentContext?: string[];
+        /**
+         * True when per-migration commits are in effect (git repo + commits
+         * enabled). The prompt instructs the agent to use `git status`/`git diff`
+         * for the file list. When false (no git, or commits disabled), the
+         * `<files_changed>` block is embedded with `changes` instead.
+         */
+        hasDiffContext: boolean;
+    };
+}
+/**
+ * Cap on the number of file entries rendered verbatim inside `<files_changed>`
+ * when the embedded-list path is used (no per-migration commits / no git).
+ * Excess entries collapse into a `… and N more files.` line.
+ */
+export declare const GENERIC_VALIDATION_FILE_LIST_CAP = 50;
+/**
+ * Builds the user prompt for the framework-owned generic-validation agent step
+ * that runs after a generator-only migration produces changes (when `--validate`
+ * is enabled and `--agentic` resolves to an enabled agent).
+ *
+ * Differences from `buildHybridPromptUserPrompt`:
+ * - No `<instructions_file>` block — the framework owns the instructions, and
+ *   they live inline in `<validation_instructions>` below.
+ * - No `<precedence>` block — there's no external instructions file to defer
+ *   to.
+ * - File-list cap: when the diff exceeds `GENERIC_VALIDATION_FILE_LIST_CAP`,
+ *   the first N entries render verbatim and the remainder collapses into a
+ *   `… and N more files.` count line.
+ * - The lead sentence frames the agent as a validator, not an applier.
+ */
+export declare function buildGenericValidationUserPrompt(ctx: GenericValidationPromptContext): string;

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

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GENERIC_VALIDATION_FILE_LIST_CAP = void 0;
+exports.buildGenericValidationUserPrompt = buildGenericValidationUserPrompt;
+const shared_rendering_1 = require("./shared-rendering");
+/**
+ * Cap on the number of file entries rendered verbatim inside `<files_changed>`
+ * when the embedded-list path is used (no per-migration commits / no git).
+ * Excess entries collapse into a `… and N more files.` line.
+ */
+exports.GENERIC_VALIDATION_FILE_LIST_CAP = 50;
+/**
+ * Builds the user prompt for the framework-owned generic-validation agent step
+ * that runs after a generator-only migration produces changes (when `--validate`
+ * is enabled and `--agentic` resolves to an enabled agent).
+ *
+ * Differences from `buildHybridPromptUserPrompt`:
+ * - No `<instructions_file>` block — the framework owns the instructions, and
+ *   they live inline in `<validation_instructions>` below.
+ * - No `<precedence>` block — there's no external instructions file to defer
+ *   to.
+ * - File-list cap: when the diff exceeds `GENERIC_VALIDATION_FILE_LIST_CAP`,
+ *   the first N entries render verbatim and the remainder collapses into a
+ *   `… and N more files.` count line.
+ * - The lead sentence frames the agent as a validator, not an applier.
+ */
+function buildGenericValidationUserPrompt(ctx) {
+    const lines = [
+        `You are validating the output of an Nx migration's deterministic generator phase. The generator has already run; inspect what it produced, verify the workspace is in a consistent state for what this migration intended to accomplish, apply any minor in-scope fixes the generator should have produced cleanly, and report findings.`,
+        ...(0, shared_rendering_1.renderMigrationBlock)(ctx),
+    ];
+    const logs = (0, shared_rendering_1.escapeXmlBody)((0, shared_rendering_1.stripAnsi)(ctx.impl.logs ?? '').trim());
+    lines.push(...(0, shared_rendering_1.renderGeneratorOutputBlock)(logs));
+    if (!ctx.impl.hasDiffContext && ctx.impl.changes.length > 0) {
+        lines.push(``, `<files_changed>`, ...renderFileListBody(ctx.impl.changes), `</files_changed>`);
+    }
+    const agentContext = (0, shared_rendering_1.filterNonEmptyStrings)(ctx.impl.agentContext ?? []);
+    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 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 write your handoff. On \`status: "success"\`, summarize what you verified and any fixes you applied. On \`status: "failed"\`, enumerate the unresolved 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>`, ``, `Once you finish, write your handoff JSON to:`, ...(0, shared_rendering_1.renderHandoffPathFooter)(ctx.handoffFileAbsolutePath));
+    return lines.join('\n');
+}
+function renderFileListBody(changes) {
+    // File paths from `tree.write` are user-authored; escape `<` / `&` so a
+    // hostile path can't break out of `<files_changed>`. `change.type` is an
+    // nx-controlled enum (CREATE/UPDATE/DELETE) and needs no escape.
+    const safe = changes.map((change) => ({
+        ...change,
+        path: (0, shared_rendering_1.escapeXmlBody)(change.path),
+    }));
+    if (safe.length <= exports.GENERIC_VALIDATION_FILE_LIST_CAP) {
+        return safe.map(shared_rendering_1.renderFileEntry);
+    }
+    const shown = safe.slice(0, exports.GENERIC_VALIDATION_FILE_LIST_CAP);
+    const remaining = safe.length - exports.GENERIC_VALIDATION_FILE_LIST_CAP;
+    return [
+        ...shown.map(shared_rendering_1.renderFileEntry),
+        ``,
+        `… and ${remaining} more file${remaining === 1 ? '' : 's'}.`,
+    ];
+}

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

@@ -0,0 +1,44 @@
+import type { FileChange } from '../../../../generators/tree';
+export interface HybridPromptMigrationContext {
+    package: string;
+    name: string;
+    version: string;
+    description?: string;
+    /** Workspace-relative path to the prompt `.md` file. */
+    promptPath: string;
+    /** Absolute path the agent must write its handoff file to. */
+    handoffFileAbsolutePath: string;
+    /** Context captured from the deterministic generator phase. */
+    impl?: {
+        /** Raw output from the generator (devkit logger + console). */
+        logs?: string;
+        /**
+         * Files the generator changed. Rendered inside `<files_changed>` as a
+         * `[TYPE] path` list — only when `hasDiffContext` is false; when true the
+         * agent is instead pointed at `git status` / `git diff`.
+         */
+        changes?: FileChange[];
+        /** Strings the generator author put in `agentContext`. */
+        agentContext?: string[];
+        /**
+         * True when per-migration commits are in effect (git repo + commits
+         * enabled). The prompt then points the agent at git for the file list;
+         * when false (no git or commits disabled), `changes` is embedded.
+         */
+        hasDiffContext?: boolean;
+    };
+}
+/**
+ * Builds the user prompt for a hybrid migration's prompt phase (`implementation`
+ * + `prompt`). The deterministic generator has already run; sections of the
+ * prompt summarize what it did so the agent can complete the paired step with
+ * awareness of the generator's output.
+ *
+ * Structure: XML tags carry section boundaries; markdown (fenced blocks,
+ * bullet lists) sits inside tags for inline structure. This is the
+ * multi-section case where both Anthropic and OpenAI guidance most clearly
+ * favors XML for unambiguous parsing. Each impl section is omitted when its
+ * source is empty so the prompt stays minimal when the generator made no
+ * meaningful contribution.
+ */
+export declare function buildHybridPromptUserPrompt(ctx: HybridPromptMigrationContext): string;

package/dist/src/command-line/migrate/agentic/prompts/hybrid-prompt-migration.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildHybridPromptUserPrompt = buildHybridPromptUserPrompt;
+const shared_rendering_1 = require("./shared-rendering");
+/**
+ * Builds the user prompt for a hybrid migration's prompt phase (`implementation`
+ * + `prompt`). The deterministic generator has already run; sections of the
+ * prompt summarize what it did so the agent can complete the paired step with
+ * awareness of the generator's output.
+ *
+ * Structure: XML tags carry section boundaries; markdown (fenced blocks,
+ * bullet lists) sits inside tags for inline structure. This is the
+ * multi-section case where both Anthropic and OpenAI guidance most clearly
+ * favors XML for unambiguous parsing. Each impl section is omitted when its
+ * source is empty so the prompt stays minimal when the generator made no
+ * meaningful contribution.
+ */
+function buildHybridPromptUserPrompt(ctx) {
+    const lines = [
+        `Complete the AI-driven step that follows the generator phase of a two-phase Nx migration. The deterministic generator phase has already run; the sections below summarize what it did. The step may apply additional changes, verify the generator's output, or both — follow the instructions file.`,
+        ...(0, shared_rendering_1.renderMigrationBlock)(ctx),
+    ];
+    const logs = (0, shared_rendering_1.escapeXmlBody)((0, shared_rendering_1.stripAnsi)(ctx.impl?.logs ?? '').trim());
+    const agentContext = (0, shared_rendering_1.filterNonEmptyStrings)(ctx.impl?.agentContext ?? []);
+    const hasDiffContext = !!ctx.impl?.hasDiffContext;
+    const hasChanges = !!ctx.impl?.changes && ctx.impl.changes.length > 0;
+    lines.push(...(0, shared_rendering_1.renderGeneratorOutputBlock)(logs));
+    if (hasDiffContext && hasChanges) {
+        // Live view via git. Suppressed when the generator made no changes —
+        // pointing the agent at `git status` for an empty diff is noise.
+        lines.push(``, `<inspect_changes>`, (0, shared_rendering_1.renderGitInspectInstruction)(), `</inspect_changes>`);
+    }
+    else if (!hasDiffContext) {
+        const embeddedFileList = renderFileList(ctx.impl?.changes);
+        if (embeddedFileList) {
+            lines.push(``, `<files_changed>`, embeddedFileList, `</files_changed>`);
+        }
+    }
+    if (agentContext.length > 0) {
+        lines.push(...(0, shared_rendering_1.renderAdvisoryContext)('hints from the generator phase; consult while following the instructions, not as separate tasks', agentContext));
+    }
+    lines.push(``, `<instructions_file>${(0, shared_rendering_1.escapeXmlBody)(ctx.promptPath)}</instructions_file>`, ``, `<precedence>If anything in the sections above conflicts with the instructions file, the instructions file wins.</precedence>`, ``, `Open the instructions file (path is workspace-relative), follow its instructions step by step using the sections above as context, then write your handoff JSON to:`, ...(0, shared_rendering_1.renderHandoffPathFooter)(ctx.handoffFileAbsolutePath));
+    return lines.join('\n');
+}
+function renderFileList(changes) {
+    if (!changes || changes.length === 0)
+        return '';
+    return changes
+        .map((change) => ({ ...change, path: (0, shared_rendering_1.escapeXmlBody)(change.path) }))
+        .map(shared_rendering_1.renderFileEntry)
+        .join('\n');
+}

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

@@ -0,0 +1,21 @@
+export interface PromptMigrationContext {
+    package: string;
+    name: string;
+    version: string;
+    description?: string;
+    /** Workspace-relative path to the prompt `.md` file. */
+    promptPath: string;
+    /** Absolute path the agent must write its handoff file to. */
+    handoffFileAbsolutePath: string;
+}
+/**
+ * Builds the first user-facing message for a prompt-migration step.
+ *
+ * Keeps the framing short — the heavy lifting (handoff contract, scope rules)
+ * already lives in the system prompt; this message just identifies the
+ * migration and points at the instructions file.
+ *
+ * XML tags wrap path values and the migration metadata so the agent does
+ * not misread them as headers or prose.
+ */
+export declare function buildPromptMigrationUserPrompt(ctx: PromptMigrationContext): string;

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

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPromptMigrationUserPrompt = buildPromptMigrationUserPrompt;
+const shared_rendering_1 = require("./shared-rendering");
+/**
+ * Builds the first user-facing message for a prompt-migration step.
+ *
+ * Keeps the framing short — the heavy lifting (handoff contract, scope rules)
+ * already lives in the system prompt; this message just identifies the
+ * migration and points at the instructions file.
+ *
+ * XML tags wrap path values and the migration metadata so the agent does
+ * not misread them as headers or prose.
+ */
+function buildPromptMigrationUserPrompt(ctx) {
+    const lines = [
+        `Apply one prompt-based migration to this Nx workspace.`,
+        ...(0, shared_rendering_1.renderMigrationBlock)(ctx),
+        ``,
+        `<instructions_file>${(0, shared_rendering_1.escapeXmlBody)(ctx.promptPath)}</instructions_file>`,
+        ``,
+        `Open the instructions file (path is workspace-relative), follow its instructions step by step, then write your handoff JSON to:`,
+        ...(0, shared_rendering_1.renderHandoffPathFooter)(ctx.handoffFileAbsolutePath),
+    ];
+    return lines.join('\n');
+}

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

@@ -0,0 +1,18 @@
+import type { FileChange } from '../../../../generators/tree';
+export declare function renderFileEntry(change: FileChange): string;
+export declare function renderListItem(entry: string): string;
+export declare function renderKeyMultilineValue(key: string, value: string): string[];
+export declare function stripAnsi(text: string): string;
+export declare function filterNonEmptyStrings(entries: unknown[]): string[];
+export declare function escapeXmlBody(value: string): string;
+export declare function renderGitInspectInstruction(): string;
+export declare function renderGeneratorOutputBlock(logs: string): string[];
+export interface MigrationBlockContext {
+    package: string;
+    name: string;
+    version: string;
+    description?: string;
+}
+export declare function renderMigrationBlock(ctx: MigrationBlockContext): string[];
+export declare function renderHandoffPathFooter(handoffFileAbsolutePath: string): string[];
+export declare function renderAdvisoryContext(note: string, entries: string[]): string[];