nx 23.2.1 → 23.3.0-beta.1

package/dist/src/command-line/migrate/run/agent-work-payload.js

@@ -0,0 +1,142 @@
+"use strict";
+// Internal to run/: deliberately not re-exported from ./index.
+//
+// Persists each parked payload by step and attempt, so a reconcile can re-emit
+// it after a compaction or restart without reusing payloads from discarded
+// attempts.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentWorkPayloadPath = agentWorkPayloadPath;
+exports.persistAgentWorkPayload = persistAgentWorkPayload;
+exports.readAgentWorkPayload = readAgentWorkPayload;
+exports.latestStoredAgentWorkPayload = latestStoredAgentWorkPayload;
+exports.removeAgentWorkPayloads = removeAgentWorkPayloads;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const atomic_write_1 = require("./atomic-write");
+const AGENT_WORK_DIR_NAME = 'agent-work';
+// Both segments are Nx-issued (`step-<n>` and the attempt counter), so the
+// name never carries untrusted path segments.
+function agentWorkPayloadPath(runDirPath, stepId, attempt) {
+    return (0, path_1.join)(runDirPath, AGENT_WORK_DIR_NAME, `${stepId}-attempt-${attempt}.json`);
+}
+/**
+ * Failures propagate: the runbook promises a parked step's block is
+ * re-emitted, so a caller that cannot store the payload must fail the attempt
+ * rather than park.
+ */
+function persistAgentWorkPayload(filePath, payload) {
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(filePath), { recursive: true });
+    (0, atomic_write_1.publishFileAtomically)(filePath, (tmpPath) => (0, fs_1.writeFileSync)(tmpPath, JSON.stringify(payload, null, 2)));
+}
+/**
+ * The stored payload, or null when nothing usable is on disk: the file is
+ * missing (the park predates this mechanism), does not parse to a plain
+ * object, or does not match what the step awaits. Null is undifferentiated on
+ * purpose: every caller's remediation is the same freshly derived payload.
+ * The returned object is never re-emitted as text; both re-emission sites go
+ * back through the block writer's escaping, so a tampered file cannot break
+ * the framing.
+ */
+function readAgentWorkPayload(filePath, expected) {
+    let content;
+    try {
+        content = (0, fs_1.readFileSync)(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return null;
+    }
+    const payload = parsed;
+    if (payload.migrationId !== expected.migrationId) {
+        return null;
+    }
+    const matchesKind = expected.kind === 'generator-validation'
+        ? payload.kind === 'generator-validation'
+        : payload.kind === undefined &&
+            expected.promptPath !== undefined &&
+            payload.prompt === expected.promptPath;
+    return matchesKind ? payload : null;
+}
+/**
+ * Returns the newest payload from the current generator lineage, or null.
+ * `fromAttempt` excludes generator runs discarded by reset-backed retries; an
+ * absent boundary fails closed for states written by older Nx.
+ */
+function latestStoredAgentWorkPayload(runDirPath, stepId, beforeAttempt, fromAttempt, expected) {
+    if (fromAttempt === undefined) {
+        return null;
+    }
+    // Enumerated from disk rather than counted down from `beforeAttempt`:
+    // attempts are persisted numbers, and a loop spanning their range would
+    // let a tampered-but-valid counter drive that many synchronous reads.
+    const candidates = storedAttemptsForStep(runDirPath, stepId)
+        .filter((attempt) => attempt >= fromAttempt && attempt < beforeAttempt)
+        .sort((a, b) => b - a);
+    for (const attempt of candidates) {
+        const payload = readAgentWorkPayload(agentWorkPayloadPath(runDirPath, stepId, attempt), expected);
+        if (payload) {
+            return payload;
+        }
+    }
+    return null;
+}
+// An unreadable directory reads as empty: the lookup falls back to a freshly
+// derived payload, and removal is best effort. The `-attempt-` infix keeps
+// `step-1` from matching `step-12`'s files.
+function storedAttemptsForStep(runDirPath, stepId) {
+    let entries;
+    try {
+        entries = (0, fs_1.readdirSync)((0, path_1.join)(runDirPath, AGENT_WORK_DIR_NAME));
+    }
+    catch {
+        return [];
+    }
+    const prefix = `${stepId}-attempt-`;
+    const suffix = '.json';
+    const attempts = [];
+    for (const name of entries) {
+        if (!name.startsWith(prefix) || !name.endsWith(suffix)) {
+            continue;
+        }
+        const middle = name.slice(prefix.length, -suffix.length);
+        if (!/^[1-9]\d*$/.test(middle)) {
+            continue;
+        }
+        const attempt = Number(middle);
+        if (Number.isSafeInteger(attempt)) {
+            attempts.push(attempt);
+        }
+    }
+    return attempts;
+}
+/**
+ * Best effort per file: the callers run after the outcome or rearm is already
+ * decided, so an entry that cannot be removed (a permission failure, a
+ * directory planted at the path) is left to whole-run pruning rather than
+ * failing the reconcile. A planted directory is never re-handed either way:
+ * reading it fails, which the reader treats as no stored copy.
+ */
+function removeAgentWorkPayloads(runDirPath, stepId, throughAttempt) {
+    // Enumerated for the same reason as the lookup: a tampered-but-valid attempt
+    // would otherwise drive that many synchronous removals.
+    for (const attempt of storedAttemptsForStep(runDirPath, stepId)) {
+        if (attempt > throughAttempt) {
+            continue;
+        }
+        try {
+            (0, fs_1.rmSync)(agentWorkPayloadPath(runDirPath, stepId, attempt), {
+                force: true,
+            });
+        }
+        catch { }
+    }
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Runs `write` against a unique sibling temp path, then renames it over
+ * `filePath`: a crash mid-write can only leave a stale temp file, never a
+ * half-written artifact, and rename replaces whatever sits at the destination
+ * without following it. The random suffix keeps concurrent writers apart; a
+ * pid would collide across PID namespaces sharing the workspace.
+ */
+export declare function publishFileAtomically(filePath: string, write: (tmpPath: string) => void): void;

package/dist/src/command-line/migrate/run/atomic-write.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publishFileAtomically = publishFileAtomically;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+/**
+ * Runs `write` against a unique sibling temp path, then renames it over
+ * `filePath`: a crash mid-write can only leave a stale temp file, never a
+ * half-written artifact, and rename replaces whatever sits at the destination
+ * without following it. The random suffix keeps concurrent writers apart; a
+ * pid would collide across PID namespaces sharing the workspace.
+ */
+function publishFileAtomically(filePath, write) {
+    const tmpPath = `${filePath}~${(0, crypto_1.randomBytes)(4).toString('hex')}`;
+    write(tmpPath);
+    (0, fs_1.renameSync)(tmpPath, filePath);
+}

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

@@ -1,5 +1,5 @@
 export { CURRENT_RUN_STATE_FORMAT_VERSION, NewerRunStateFormatError, migrateRunsDir, runDir, readRunState, writeRunState, findActiveRun, createRun, } from './run-state';
-export type { MigrateRunStatus, MigrateRunRound, MigrateStepStatus, PromptOutcomeStatus, MigrateStepOutcome, MigrateStepPromptOutcome, MigrateStep, MigrateCommitKind, MigrateCommitLedgerEntry, MigrateRunAnalytics, MigrateRunState, } from './run-state';
+export type { MigrateRunStatus, MigrateRunRound, MigrateStepStatus, PromptOutcomeStatus, MigrateStepAwaitingKind, MigrateStepOutcome, MigrateStepPromptOutcome, MigrateStep, MigrateCommitKind, MigrateCommitLedgerEntry, MigrateIssueDisposition, MigrateRunIssue, MigrateRunAnalytics, MigrateRunNoProgress, MigrateRunState, } from './run-state';
 export { applyStepEvent, hasPendingCommitDebt } from './state-machine';
 export type { StepAction, StepEvent, ApplyStepEventResult, } from './state-machine';
 export { createRunId, computePlanHash } from './run-id';

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

@@ -0,0 +1,106 @@
+import { issueFingerprint, type MigrateCommitLedgerEntry, type MigrateIssueDisposition, type MigrateRunIssue, type MigrateRunState, type MigrateStep } from './run-state';
+export { issueFingerprint };
+export interface ReportedIssue {
+    summary: string;
+    detail?: string;
+    applicableMigrations: string[] | 'unknown';
+    disposition?: MigrateIssueDisposition;
+}
+export interface ReportedIssueUpdate {
+    id: string;
+    disposition: Exclude<MigrateIssueDisposition, 'recorded'>;
+    note?: string;
+}
+export type ParsedHandoffIssues = {
+    ok: true;
+    issues: ReportedIssue[];
+    updates: ReportedIssueUpdate[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Validates a handoff's `issues` / `issueUpdates` against the run's current
+ * state. Absent fields parse as empty; any invalid entry rejects the whole
+ * report with a reason the awaiting dispense hands back to the agent. Also
+ * rejects unrecognized top-level handoff fields: a misspelled "issueUpates"
+ * would otherwise read as an absent report and be discarded with the handoff.
+ */
+export declare function parseHandoffIssues(extras: Record<string, unknown> | undefined, state: MigrateRunState, reportingStep: MigrateStep): ParsedHandoffIssues;
+export interface IssueArchiveUpdate {
+    issueId: string;
+    stepId: string;
+    disposition: MigrateIssueDisposition;
+    note?: string;
+    detail?: string;
+    applicableMigrations?: string[];
+}
+export interface IssueApplication {
+    state: MigrateRunState;
+    newIssues: {
+        entry: MigrateRunIssue;
+        report: ReportedIssue;
+    }[];
+    updates: IssueArchiveUpdate[];
+}
+/**
+ * Pure. Must run on state read fresh inside the fold's locked write, or ids
+ * collide and the claim checks test state that is no longer on disk.
+ */
+export declare function applyReportedIssues(state: MigrateRunState, reportingStep: MigrateStep, issues: ReportedIssue[], updates: ReportedIssueUpdate[]): IssueApplication;
+/**
+ * The issue ids a landed commit naming `stepIds` carries. Attribution rides on
+ * the persisted `resolvedByStepId`, so a resolution whose own commit attempt
+ * failed still reaches the later commit that absorbs that step's tree.
+ */
+export declare function issueIdsForCommit(state: MigrateRunState, stepIds: string[]): string[];
+/**
+ * Attaches the issue ids a landed entry carries; non-landed entries pass
+ * through. Every commit append (worker, fold, adopt) routes through this so
+ * attribution cannot diverge between terminal paths.
+ */
+export declare function attachIssueIdsToCommitEntry(state: MigrateRunState, entry: MigrateCommitLedgerEntry): MigrateCommitLedgerEntry;
+/**
+ * Reverts resolutions not carried by a landed commit and releases claims
+ * during a reset-backed retry. Returned disposition changes form the archive
+ * trail; claim releases do not.
+ */
+export declare function reopenResolutionsForStep(state: MigrateRunState, stepId: string): {
+    state: MigrateRunState;
+    updates: IssueArchiveUpdate[];
+};
+/**
+ * Claims the still-recorded issues applicable to the step being dispensed, up
+ * to what the digest can publish. Must run inside the dispense's locked write:
+ * serial dispensing is what makes reassignment to the next applicable step
+ * deterministic when an earlier one left the issue unresolved.
+ */
+export declare function claimIssuesForStep(state: MigrateRunState, stepId: string, runId: string): MigrateRunState;
+/**
+ * Before rendering, release terminal claims and defer issues no remaining
+ * step can claim; report-time routing can become stale as steps finish. Do
+ * not archive Nx-driven progression.
+ */
+export declare function settleUnclaimableIssues(state: MigrateRunState): MigrateRunState;
+/**
+ * The bounded "Known issues" digest a work dispense carries. Assigned entries
+ * lead and share claimIssuesForStep's prefix bound, so every kept claim appears.
+ */
+export declare function renderIssueDigestLines(state: MigrateRunState, currentStepId: string, runId: string): string[];
+export declare function renderUnresolvedIssueLines(state: MigrateRunState, runId: string): string[];
+export declare function issueArchivePath(runDirPath: string, issueId: string): string;
+/**
+ * Archives an application's new issues (with the detail the ledger does not
+ * carry) and appends its updates to the archived files. Failures propagate;
+ * the caller then keeps the handoff file as the fallback detail store.
+ * `reconstructedIds` is filled as it goes rather than returned alone: a retry
+ * finds a rebuilt shell healthy, so a throw-interrupted pass is the only
+ * chance to warn that an archive was lost.
+ */
+export declare function archiveIssues(runDirPath: string, application: IssueApplication, reconstructedIds?: string[]): string[];
+/**
+ * Verifies the archive state expected after phase 1. New-issue fields must
+ * match the report and have no updates; existing-issue updates must end with
+ * this application's whole batch.
+ */
+export declare function applicationArchivesIntact(runDirPath: string, application: IssueApplication): boolean;