@depup/nx 23.2.1-depup.7 → 23.3.0-depup.0

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

@@ -0,0 +1,37 @@
+import type { MigrateStepAwaitingKind } from './run-state';
+export declare function agentWorkPayloadPath(runDirPath: string, stepId: string, attempt: number): string;
+export interface ExpectedAgentWorkPayload {
+    migrationId: string;
+    kind: MigrateStepAwaitingKind;
+    promptPath?: string;
+}
+/**
+ * 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.
+ */
+export declare function persistAgentWorkPayload(filePath: string, payload: object): void;
+/**
+ * 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.
+ */
+export declare function readAgentWorkPayload(filePath: string, expected: ExpectedAgentWorkPayload): Record<string, unknown> | 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.
+ */
+export declare function latestStoredAgentWorkPayload(runDirPath: string, stepId: string, beforeAttempt: number, fromAttempt: number | undefined, expected: ExpectedAgentWorkPayload): Record<string, unknown> | null;
+/**
+ * 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.
+ */
+export declare function removeAgentWorkPayloads(runDirPath: string, stepId: string, throughAttempt: number): void;

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

@@ -0,0 +1,156 @@
+"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;
+    }
+    let matchesKind;
+    switch (expected.kind) {
+        case 'generator-validation':
+            matchesKind = payload.kind === 'generator-validation';
+            break;
+        case 'migration-prompt':
+            matchesKind =
+                payload.kind === undefined &&
+                    expected.promptPath !== undefined &&
+                    payload.prompt === expected.promptPath;
+            break;
+        case 'final-validation':
+            // Derived from run state at every dispense; nothing is stored.
+            throw new Error('The final validation pass stores no agent-work payload.');
+        default: {
+            const exhaustive = expected.kind;
+            throw new Error(`Unhandled awaiting kind '${exhaustive}'.`);
+        }
+    }
+    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/broker.d.ts

@@ -0,0 +1,150 @@
+import { type DeferredOutputRecord } from '../deferred-output';
+import { type CommitResult } from '../migrate-commits';
+import { type GiveUpOutcome } from './give-up';
+import { type MigrateRunPolicy, type MigrateRunState, type MigrateStep, type MigrateTreeOperation } from './run-state';
+export declare const BROKER_ENV_VAR = "NX_MIGRATE_BROKER";
+export type BrokerRequestKind = 'commit' | 'install' | 'fold-install' | 'action-install' | 'reset' | 'give-up';
+export type InstallSeam = 'install' | 'fold-install' | 'action-install';
+export interface BrokerRequest {
+    kind: BrokerRequestKind;
+    stepId: string;
+    attempt: number;
+    invocation?: string;
+    commitAs?: 'adopt';
+}
+export type BrokerResult = {
+    kind: 'commit';
+    result: CommitResult;
+    absorbedStepIds: string[];
+    output: DeferredOutputRecord[];
+} | {
+    kind: 'installed';
+    output: DeferredOutputRecord[];
+} | {
+    kind: 'install-failed';
+    message: string;
+    peerDeps: boolean;
+    output: DeferredOutputRecord[];
+} | {
+    kind: 'reset';
+    error?: string;
+} | {
+    kind: 'give-up';
+    outcome: GiveUpOutcome;
+    output: DeferredOutputRecord[];
+} | {
+    kind: 'stale';
+};
+export interface BrokeredCommit {
+    result: CommitResult;
+    absorbedStepIds: string[];
+    /**
+     * True when the session's parent ran the commit and recorded whatever it
+     * produced before answering, so the caller appends nothing. False for an
+     * in-process commit, which the caller records.
+     */
+    recorded: boolean;
+}
+/** The request no longer matches the step: another attempt owns it. */
+export declare class BrokerStaleRequestError extends Error {
+}
+/**
+ * The advertised parent could not accept the request, or went away before
+ * answering it. It may have landed the install or the commit; the tree and
+ * the run state say.
+ */
+export declare class BrokerUnavailableError extends Error {
+}
+/** Another live process holds the working tree for an operation of its own. */
+export declare class TreeBusyError extends Error {
+}
+export interface TreeOperationRequest {
+    kind: BrokerRequestKind | 'checkpoint';
+    stepId?: string;
+    attempt?: number;
+}
+export interface TreeLease {
+    readonly owner: string;
+    markedStepId?: string;
+    release(): void;
+}
+/**
+ * Owned by the scope that runs an operation and its state write: a seam that
+ * acquires in process writes the lease here before its fallible callback
+ * runs, and the scope releases it in a `finally` once the write landed or
+ * failed. A brokered call leaves it empty; the parent holds its own.
+ */
+export interface TreeScope {
+    lease?: TreeLease;
+}
+/**
+ * Reserves the working tree for one operation in a single fresh-state write:
+ * the request must still be at its seam (else the attempt moved on and the
+ * request is stale), and no other live process may hold a reservation.
+ * A reservation whose owner process is gone holds nothing.
+ */
+export declare function acquireTreeOperation(dir: string, request: TreeOperationRequest, owner?: string): TreeLease;
+/**
+ * Owner-checked: a lease released late never drops a newer reservation, nor
+ * the mark it set.
+ */
+export declare function releaseTreeOperation(dir: string, owner: string, markedStepId?: string): void;
+/** The reservation a live process other than `owner` holds, if any. */
+export declare function liveTreeOperation(state: MigrateRunState, owner?: string): MigrateTreeOperation | undefined;
+export declare function treeBusyMessage(held: MigrateTreeOperation): string;
+export declare function treeOperationLabel(held: Pick<MigrateTreeOperation, 'kind' | 'stepId'>): string;
+export declare function brokerDir(runDirPath: string): string;
+/**
+ * Runs the step's install and commit where they can land: in this process
+ * unless a parent session advertised its broker, in which case the request
+ * goes to the parent and the answer comes back with the output the parent
+ * collected, printed here. The absorbed step ids come from whichever side
+ * ran the commit, so the ledger entry names what its `git add -A` took.
+ */
+export declare function commitStepTree(dir: string, step: MigrateStep, absorbedStepIds: string[], commitInProcess: () => Promise<CommitResult>, scope: TreeScope, commitAs?: 'adopt'): Promise<BrokeredCommit>;
+/**
+ * The same for a step that owes only its install: no commit is due, or the
+ * commit waits for a fold.
+ */
+export declare function installStepTree(dir: string, step: MigrateStep, seam: InstallSeam, installInProcess: () => Promise<void>, scope: TreeScope): Promise<void>;
+/**
+ * The same for the reset a clean retry of a failed or died step needs. Runs
+ * `resetInProcess` under the reservation, or asks the parent, which resets
+ * against the state it reads then; a reset that could not run throws.
+ */
+export declare function resetStepTree(dir: string, step: MigrateStep, resetInProcess: () => void, scope: TreeScope): Promise<void>;
+/**
+ * The same for giving a failed or died step up while the run commits. Unlike
+ * the seams above, the operation settles the step itself, under the
+ * reservation it runs with, so the caller writes no transition of its own.
+ */
+export declare function giveUpStepTree(root: string, dir: string, step: MigrateStep, skipInstall: boolean, reconcileCommand: string, scope: TreeScope): Promise<GiveUpOutcome>;
+/**
+ * The parent side. Holds one exclusive lock for the session's lifetime so a
+ * waiting step can tell a slow parent from a dead one, answers each request
+ * once, and removes its own requests on close; its answers stay for the steps
+ * still reading them. Requests carrying another session's nonce belong to
+ * that session and are never touched. Whether to install or commit comes from
+ * the policy the session started with, never from run state, which the
+ * agent's sandbox can write.
+ */
+export declare class MigrateCommitBroker {
+    private readonly root;
+    private readonly dir;
+    private readonly reconcileCommand;
+    private readonly policy;
+    readonly nonce: string;
+    private readonly handled;
+    private inFlight;
+    private readonly lock;
+    constructor(root: string, dir: string, reconcileCommand: string, policy: MigrateRunPolicy);
+    /** The request whose operation this process is running right now. */
+    get requestInFlight(): BrokerRequest | null;
+    /** Answers this session's unanswered requests, one at a time. */
+    service(): Promise<void>;
+    private record;
+    private answer;
+    /** Releases the lock; call after the last `service` settled. */
+    close(): void;
+    private notADirectory;
+}