@ohos-ports/nx 23.2.1-beta.1 → 23.3.0-beta.0

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

@@ -11,9 +11,9 @@ const logger_1 = require("../../../utils/logger");
 const types_1 = require("./types");
 /**
  * Both the agentic runner and the orchestrator write per-run scratch under
- * `.nx/migrate-runs/<run-id>/`: handoff files in both cases, plus the durable
- * run state and its plan snapshots for the orchestrator. The v23 migration
- * `23-0-0-add-migrate-runs-to-git-ignore` adds `.nx/migrate-runs` to
+ * `.nx/migrate-runs/<run-id>/`: handoff and prompt files in both cases, plus
+ * the durable run state and its plan snapshots for the orchestrator. The v23
+ * migration `23-0-0-add-migrate-runs-to-git-ignore` adds `.nx/migrate-runs` to
  * `.gitignore`; in its declared slot (typically late) earlier per-migration
  * commits would absorb the scratch into the user-visible diff.
  *

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;
@@ -19,19 +20,17 @@ export declare function mkdirSafely(dir: string, purpose: string): void;
  * inspection.
  */
 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.
- */
+export declare function truncateUtf8(value: string, maxBytes: number): string;
 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 declare function stepPromptsDir(runDir: string, migration: {
+    package: string;
+    name: string;
+}): string;
 export type HandoffReadFailureReason = 'missing' | 'read-error' | 'parse-error' | 'shape-mismatch';
 export type HandoffReadResult = {
     ok: true;
@@ -42,19 +41,53 @@ 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 handoffsDirState(handoffsDir: string): 'directory' | 'missing' | 'other';
+/**
+ * Non-recursive mkdir: the run dir exists, and a symlink created after the
+ * missing-path check fails with EEXIST instead of being followed.
+ */
+export declare function ensureRunSubdir(dir: string, notADirectory: () => Error): void;
+/**
+ * Thrown by {@link readInspectedFile} when the opened descriptor is not the
+ * file the caller's lstat described: a symlink followed on Windows, or an
+ * atomic replacement between the lstat and the open.
+ */
+export declare class FileReplacedDuringReadError extends Error {
+}
+/**
+ * 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;
+/**
+ * Reads a file its owner publishes atomically (tmp + rename), with
+ * {@link readInspectedFile}'s refusal of a symlink or FIFO but tolerant of the
+ * publish: a rename swaps the inode between the lstat and the open, read as a
+ * replacement, so re-lstat and retry to read the new file. A pre-existing
+ * symlink or FIFO fails the isFile check before any open; a file that keeps
+ * changing past the retry budget is refused. Throws `notRegularMessage` for a
+ * non-regular file; ENOENT and ELOOP propagate.
+ */
+export declare function readAtomicallyPublishedFile(filePath: string, notRegularMessage: 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): HandoffReadResult;
+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 +96,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

@@ -1,13 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileReplacedDuringReadError = void 0;
 exports.runDirPath = runDirPath;
 exports.resolveAgenticRunId = resolveAgenticRunId;
 exports.mkdirSafely = mkdirSafely;
 exports.initRunDir = initRunDir;
+exports.truncateUtf8 = truncateUtf8;
 exports.stepHandoffPath = stepHandoffPath;
+exports.runStepHandoffPath = runStepHandoffPath;
+exports.stepPromptsDir = stepPromptsDir;
+exports.handoffsDirState = handoffsDirState;
+exports.ensureRunSubdir = ensureRunSubdir;
+exports.readInspectedFile = readInspectedFile;
+exports.readAtomicallyPublishedFile = readAtomicallyPublishedFile;
 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");
@@ -56,14 +65,10 @@ function initRunDir(workspaceRoot, runId) {
 // 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, '_');
+    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 +76,166 @@ function sanitizeSegment(value) {
     }
     return sanitized || '_';
 }
+const STEP_NAME_PREFIX_MAX_BYTES = 64;
+// Truncates to a UTF-8 byte budget without splitting a code point.
+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.
+ * The name a step's own files are keyed by, bounded to fit one path component.
+ * Sanitizing folds many characters to `_` and the prefix is cut to fit, so the
+ * SHA-256 of the raw package and name is what keeps two migrations apart.
  */
+function stepStem(migration) {
+    const prefix = truncateUtf8([...migration.package.split('/'), migration.name]
+        .map(sanitizeSegment)
+        .join('+'), STEP_NAME_PREFIX_MAX_BYTES);
+    const hash = (0, crypto_1.createHash)('sha256')
+        .update(JSON.stringify([migration.package, migration.name]))
+        .digest('hex');
+    return `${prefix}-${hash}`;
+}
 function stepHandoffPath(runDir, migration) {
-    return (0, path_1.join)(runDir, types_1.HANDOFFS_DIR_NAME, ...migration.package.split('/').map(sanitizeSegment), `${sanitizeSegment(migration.name)}.json`);
+    return (0, path_1.join)(runDir, types_1.HANDOFFS_DIR_NAME, `${stepStem(migration)}.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`);
+}
+function stepPromptsDir(runDir, migration) {
+    return (0, path_1.join)(runDir, types_1.PROMPTS_DIR_NAME, stepStem(migration));
+}
+/**
+ * `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;
+    }
+}
+/**
+ * Non-recursive mkdir: the run dir exists, and a symlink created after the
+ * missing-path check fails with EEXIST instead of being followed.
+ */
+function ensureRunSubdir(dir, notADirectory) {
+    const state = handoffsDirState(dir);
+    switch (state) {
+        case 'directory':
+            return;
+        case 'missing':
+            (0, fs_1.mkdirSync)(dir);
+            return;
+        case 'other':
+            throw notADirectory();
+        default: {
+            const unhandled = state;
+            throw new Error(`Unhandled directory state: ${unhandled}`);
+        }
+    }
 }
 /**
- * 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.
+ * Thrown by {@link readInspectedFile} when the opened descriptor is not the
+ * file the caller's lstat described: a symlink followed on Windows, or an
+ * atomic replacement between the lstat and the open.
  */
-function readHandoffWithReason(filePath) {
+class FileReplacedDuringReadError extends Error {
+}
+exports.FileReplacedDuringReadError = FileReplacedDuringReadError;
+/**
+ * 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 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 FileReplacedDuringReadError(replacedMessage);
+        }
+        return (0, fs_1.readFileSync)(fd, 'utf-8');
+    }
+    finally {
+        (0, fs_1.closeSync)(fd);
+    }
+}
+const ATOMIC_READ_ATTEMPTS = 5;
+/**
+ * Reads a file its owner publishes atomically (tmp + rename), with
+ * {@link readInspectedFile}'s refusal of a symlink or FIFO but tolerant of the
+ * publish: a rename swaps the inode between the lstat and the open, read as a
+ * replacement, so re-lstat and retry to read the new file. A pre-existing
+ * symlink or FIFO fails the isFile check before any open; a file that keeps
+ * changing past the retry budget is refused. Throws `notRegularMessage` for a
+ * non-regular file; ENOENT and ELOOP propagate.
+ */
+function readAtomicallyPublishedFile(filePath, notRegularMessage) {
+    for (let attempt = 1;; attempt++) {
+        const stat = (0, fs_1.lstatSync)(filePath, { bigint: true });
+        if (!stat.isFile()) {
+            throw new Error(notRegularMessage);
+        }
+        try {
+            return readInspectedFile(filePath, stat, `${filePath} was replaced while being read.`);
+        }
+        catch (e) {
+            if (e instanceof FileReplacedDuringReadError &&
+                attempt < ATOMIC_READ_ATTEMPTS) {
+                continue;
+            }
+            throw e;
+        }
+    }
+}
+/**
+ * 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 +290,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 +302,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 +322,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/instruction-files.d.ts

@@ -0,0 +1,23 @@
+export interface StepInstructionFiles {
+    /** Absolute path: config loaders resolve it, not the agent from its cwd. */
+    systemPromptFilePath: string;
+    /** Single-line command-line text pointing the agent at its instructions. */
+    instructionsPointer: string;
+}
+export interface WriteStepInstructionFilesArgs {
+    workspaceRoot: string;
+    runDir: string;
+    migration: {
+        package: string;
+        name: string;
+    };
+    systemPrompt: string;
+    instructions: string;
+}
+/**
+ * Writes prompts as files on every platform to keep one delivery path.
+ * Windows npm shims cannot carry multi-line prompts within cmd.exe's limit.
+ */
+export declare function writeStepInstructionFiles(args: WriteStepInstructionFilesArgs): StepInstructionFiles;
+/** Writes `instructions.md` into an existing `promptsDir`; returns its path. */
+export declare function writeInstructionsFile(workspaceRoot: string, promptsDir: string, instructions: string): string;

package/dist/src/command-line/migrate/agentic/instruction-files.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeStepInstructionFiles = writeStepInstructionFiles;
+exports.writeInstructionsFile = writeInstructionsFile;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const handoff_1 = require("./handoff");
+/**
+ * Writes prompts as files on every platform to keep one delivery path.
+ * Windows npm shims cannot carry multi-line prompts within cmd.exe's limit.
+ */
+function writeStepInstructionFiles(args) {
+    const { workspaceRoot, runDir, migration, systemPrompt, instructions } = args;
+    const promptsDir = (0, handoff_1.stepPromptsDir)(runDir, migration);
+    (0, handoff_1.mkdirSafely)(promptsDir, `prompt directory for ${migration.name}`);
+    const systemPromptFilePath = (0, path_1.join)(promptsDir, 'system.md');
+    writeStepFile(systemPromptFilePath, systemPrompt, 'system prompt');
+    const instructionsFilePath = writeInstructionsFile(workspaceRoot, promptsDir, instructions);
+    return {
+        systemPromptFilePath,
+        instructionsPointer: `Your instructions for this migration step are in the file ${instructionsFilePath} (path is relative to the workspace root). Read it in full, then follow it.`,
+    };
+}
+/** Writes `instructions.md` into an existing `promptsDir`; returns its path. */
+function writeInstructionsFile(workspaceRoot, promptsDir, instructions) {
+    const absolutePath = (0, path_1.join)(promptsDir, 'instructions.md');
+    writeStepFile(absolutePath, instructions, 'instructions');
+    // Workspace-relative: the agent resolves this one itself with its cwd pinned
+    // to the workspace root. Forward slashes because it is read as prose out of
+    // the agent's prompt, where a `\` is an escape.
+    return (0, path_1.relative)(workspaceRoot, absolutePath).replace(/\\/g, '/');
+}
+function writeStepFile(filePath, contents, purpose) {
+    try {
+        (0, fs_1.writeFileSync)(filePath, contents, 'utf-8');
+    }
+    catch (err) {
+        const code = err?.code;
+        throw new Error(`Could not write the step's ${purpose} to ${filePath}${code ? ` (${code})` : ''}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+}

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

@@ -0,0 +1,12 @@
+import type { AgentId, InvocationSpec } from '../types';
+export interface MasterInvocationContext {
+    runId: string;
+    reconcileCommand: string;
+    /** Workspace-relative with forward slashes: prose the agent reads, not a shell path. */
+    runbookPath: string;
+    /** Same form as `runbookPath`; its existence closes the session. */
+    sentinelPath: string;
+}
+export declare function masterInvariant(ctx: MasterInvocationContext): string;
+export declare function masterBootstrapPrompt(ctx: MasterInvocationContext): string;
+export declare function buildMasterInvocation(agentId: AgentId, ctx: MasterInvocationContext): InvocationSpec;

package/dist/src/command-line/migrate/agentic/master/invocations.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.masterInvariant = masterInvariant;
+exports.masterBootstrapPrompt = masterBootstrapPrompt;
+exports.buildMasterInvocation = buildMasterInvocation;
+const definitions_1 = require("../definitions");
+// One line with no `%`: the Windows shim refuses line breaks and the pinned
+// text is what its command-line budget is measured against.
+function masterInvariant(ctx) {
+    return `You are driving Nx migrate run ${ctx.runId}. Its state lives on disk and is owned by nx migrate; never infer its progress from this conversation. Whenever you are unsure what to do, after a compaction or restart, and after you finish any piece of work, run \`${ctx.reconcileCommand}\` and follow the step block it returns. The run's contract is the runbook at ${ctx.runbookPath}; re-read it whenever a step block says so. When a step block reports the run complete, tell the user the outcome, then create the file ${ctx.sentinelPath} as your last action; nx closes this session once it exists.`;
+}
+function masterBootstrapPrompt(ctx) {
+    return `Read the runbook at ${ctx.runbookPath} in full, then run \`${ctx.reconcileCommand}\` and follow the step block it returns.`;
+}
+const OPENCODE_AGENT_NAME = 'nx-migrate';
+// Keyed by agent id so a new agent fails to compile until it gets a builder.
+const builders = {
+    'claude-code': (ctx) => {
+        const allowedTools = (0, definitions_1.claudeCodeHandoffAllowedTools)(ctx.runId);
+        return {
+            // `--allowedTools` is variadic: the non-variadic flag between it and
+            // the positional prompt keeps the prompt from being read as a rule.
+            args: [
+                ...(allowedTools ? ['--allowedTools', allowedTools] : []),
+                '--append-system-prompt',
+                masterInvariant(ctx),
+                masterBootstrapPrompt(ctx),
+            ],
+        };
+    },
+    codex: (ctx) => ({
+        args: [
+            '-c',
+            `developer_instructions=${(0, definitions_1.encodeTomlString)(masterInvariant(ctx))}`,
+            masterBootstrapPrompt(ctx),
+        ],
+    }),
+    opencode: (ctx) => ({
+        args: [
+            '--agent',
+            OPENCODE_AGENT_NAME,
+            '--prompt',
+            masterBootstrapPrompt(ctx),
+        ],
+        env: {
+            OPENCODE_CONFIG_CONTENT: JSON.stringify({
+                agent: { [OPENCODE_AGENT_NAME]: { prompt: masterInvariant(ctx) } },
+            }),
+        },
+    }),
+};
+function buildMasterInvocation(agentId, ctx) {
+    return builders[agentId](ctx);
+}

package/dist/src/command-line/migrate/agentic/master/run-master-session.d.ts

@@ -0,0 +1,16 @@
+import { type RunOrchestratorInitInput } from '../../run';
+import type { DetectedInstalledAgent } from '../types';
+export interface RunMasterSessionInput extends Omit<RunOrchestratorInitInput, 'emitAgentInstructions' | 'onExistingRun'> {
+    agent: DetectedInstalledAgent;
+    interactive?: boolean;
+    runId?: string;
+    startFresh?: boolean;
+    confirmStart: () => Promise<boolean>;
+}
+/**
+ * Starts (or continues) an orchestrated run and hands it to one agent session
+ * that drives it through `--run-id` reconciles. Run state is the only
+ * authority on the outcome: the exit code follows what run.json says once the
+ * session ends, not what the agent process returned.
+ */
+export declare function runMasterSession(input: RunMasterSessionInput): Promise<number | undefined>;