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

package/dist/src/command-line/migrate/migrate-commits.js

@@ -0,0 +1,227 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commitMigrationIfRequested = commitMigrationIfRequested;
+exports.commitCheckpointBeforeMigrations = commitCheckpointBeforeMigrations;
+exports.resolveCreateCommits = resolveCreateCommits;
+exports.currentBranchIfDefault = currentBranchIfDefault;
+exports.confirmMigrationCommitsOnDefaultBranch = confirmMigrationCommitsOnDefaultBranch;
+exports.confirmCommitsOnDefaultBranch = confirmCommitsOnDefaultBranch;
+const tslib_1 = require("tslib");
+const pc = tslib_1.__importStar(require("picocolors"));
+const configuration_1 = require("../../config/configuration");
+const command_line_utils_1 = require("../../utils/command-line-utils");
+const git_utils_1 = require("../../utils/git-utils");
+const logger_1 = require("../../utils/logger");
+const output_1 = require("../../utils/output");
+const types_1 = require("./agentic/types");
+const safe_prompt_1 = require("./safe-prompt");
+const deferred_output_1 = require("./deferred-output");
+// `git add -A` captures an orchestrated run's scratch state whenever the
+// ignore rule that normally hides it goes missing mid-run (a checkout, a
+// .gitignore edit, or the migration's own changes).
+const MIGRATE_COMMIT_EXCLUDES = [types_1.MIGRATE_RUNS_RELATIVE_DIR];
+/**
+ * `pendingMigrations` are listed in the commit body so a `git log -p` reader
+ * can see which earlier migrations' diffs this commit absorbed (their own
+ * commits failed and `git add -A` picked their working-tree state up too).
+ *
+ * The default `failureGuidance` describes the classic loop's absorb-and-recap
+ * behavior; a caller with no later commit or recap to absorb the diff (the
+ * standalone single-migration worker) passes its own.
+ */
+async function commitMigrationIfRequested(root, migration, shouldCreateCommits, commitPrefix, installDepsIfChanged, pendingMigrations = [], failureGuidance = 'Any uncommitted changes will be included in the next successful commit, which will reference this migration; if they remain uncommitted, the end-of-run output will list this migration so you can commit or revert them manually.', out = deferred_output_1.terminalOutput) {
+    if (!shouldCreateCommits)
+        return { status: 'disabled' };
+    await installDepsIfChanged();
+    // Generator may have only touched gitignored paths or the excluded scratch
+    // dir, or the prompt half made no change: log neutrally, not as an error.
+    // The probe excludes what the commit excludes, else the commit fails empty.
+    if (!(0, git_utils_1.hasUncommittedChanges)(root, MIGRATE_COMMIT_EXCLUDES)) {
+        out.line('dim', `- No changes to commit for ${migration.name}.`);
+        return { status: 'no-changes' };
+    }
+    const commitMessage = buildCommitMessage(`${commitPrefix}${migration.name}`, pendingMigrations);
+    try {
+        const sha = await (0, git_utils_1.tryCommitChangesAsync)(commitMessage, root, MIGRATE_COMMIT_EXCLUDES);
+        if (sha)
+            return { status: 'committed', sha };
+        // null = commit landed but `git rev-parse HEAD` failed (see
+        // `tryCommitChangesAsync`). Degraded-but-correct — log yellow, not red.
+        out.line('yellow', `The commit for ${migration.name} was created, but its sha could not be resolved (\`git rev-parse HEAD\` failed transiently). Continuing without recording the sha for this step.`);
+        return { status: 'committed', sha: null };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        out.line('red', `The commit for ${migration.name} failed:\n${reason}\nCheck \`git status\` and \`git log\`; the commit may have landed despite this error. ${failureGuidance}`);
+        return { status: 'failed', reason };
+    }
+}
+// Migration names come from migrations.json (third-party plugin authored);
+// they cannot be trusted to be single-line. Strip CR/LF so a hostile name
+// cannot inject body lines or fake `Co-Authored-By:` / similar trailers.
+function sanitizeMigrationLine(value) {
+    return value.replace(/[\r\n]+/g, ' ').trim();
+}
+function buildCommitMessage(subject, pendingMigrations) {
+    if (pendingMigrations.length === 0)
+        return subject;
+    // Two newlines separate the subject from the body per the
+    // conventional-commits convention.
+    const lines = [
+        subject,
+        '',
+        'Includes changes from prior migrations whose own commits failed:',
+        ...pendingMigrations.map((p) => `  - ${sanitizeMigrationLine(p.package)}: ${sanitizeMigrationLine(p.name)}`),
+    ];
+    return lines.join('\n');
+}
+/**
+ * Commits any pre-existing working-tree state into a dedicated "checkpoint"
+ * commit before the first migration runs. Without this, the first migration's
+ * commit would absorb whatever was already pending — most commonly the
+ * package.json edit `nx migrate latest` produces and the lockfile churn from
+ * the orchestrator's `npm install --ignore-scripts` step — and migration 1's
+ * validation would see that mixed in with the generator output. No-op when
+ * the working tree is already clean.
+ */
+function commitCheckpointBeforeMigrations(root, commitPrefix) {
+    if (!(0, git_utils_1.hasUncommittedChanges)(root, MIGRATE_COMMIT_EXCLUDES))
+        return;
+    try {
+        const sha = (0, git_utils_1.tryCommitChanges)(`${commitPrefix}checkpoint before running migrations`, root, MIGRATE_COMMIT_EXCLUDES);
+        if (sha) {
+            logger_1.logger.info(pc.dim(`- Checkpoint commit created: ${sha}`));
+            return;
+        }
+        // null = commit landed but `git rev-parse HEAD` failed (see
+        // `tryCommitChanges`). State is captured, just unanchored.
+        output_1.output.warn({
+            title: 'Could not resolve checkpoint commit sha',
+            bodyLines: [
+                'The checkpoint commit was created, but its sha could not be resolved (`git rev-parse HEAD` failed transiently).',
+            ],
+        });
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        output_1.output.warn({
+            title: 'Could not create checkpoint commit before migrations',
+            bodyLines: [
+                reason,
+                `Migration 1's commit will absorb any pre-existing working-tree state.`,
+            ],
+        });
+    }
+}
+/**
+ * `agenticHasDiffContext` gates the agent prompt: without per-migration commits
+ * to isolate a migration's diff, the prompt embeds a file list instead of
+ * pointing at git.
+ */
+function resolveCreateCommits(args) {
+    const { createCommits, mode, isGitRepo, commitPrefixIsCustom } = args;
+    // The orchestrator forces the agentic defaults without the `--agentic` flag,
+    // so its warnings must not name a flag the user never passed.
+    const orchestrated = mode === 'orchestrated';
+    const agenticKind = orchestrated ? 'enabled' : mode;
+    if (createCommits === true && !isGitRepo) {
+        return {
+            effective: false,
+            agenticHasDiffContext: false,
+            error: '`--create-commits` requires a git repository. Run `git init` first, or omit the flag.',
+        };
+    }
+    if (agenticKind === 'enabled') {
+        if (createCommits === false) {
+            return {
+                effective: false,
+                agenticHasDiffContext: false,
+                warning: (orchestrated
+                    ? "--no-create-commits was passed, but orchestrated migrate runs create per-migration commits by default. Without them, the agent can't isolate the current migration's changes from earlier migrations in this run. Drop --no-create-commits for accurate per-migration review."
+                    : "--no-create-commits was passed alongside --agentic. Without per-migration commits, the agent can't isolate the current migration's changes from earlier migrations in this run. Drop --no-create-commits for accurate per-migration review.") +
+                    (commitPrefixIsCustom
+                        ? ' Note: the custom --commit-prefix value will have no effect because commits are disabled.'
+                        : ''),
+            };
+        }
+        // Not an error like the explicit `--create-commits` branch above: the
+        // agentic default was never asked for, so degrade instead.
+        if (!isGitRepo) {
+            return {
+                effective: false,
+                agenticHasDiffContext: false,
+                warning: (orchestrated
+                    ? 'Orchestrated migrate runs create per-migration commits by default, but the workspace is not a git repository. Continuing without commits, so the agent will not receive per-file diff context. Run `git init` to enable.'
+                    : '`--agentic` enables per-migration commits by default, but the workspace is not a git repository. Continuing without commits, so the agent will not receive per-file diff context. Run `git init` to enable.') +
+                    (commitPrefixIsCustom
+                        ? ' The custom --commit-prefix value will have no effect.'
+                        : ''),
+            };
+        }
+        return { effective: true, agenticHasDiffContext: true };
+    }
+    return {
+        effective: createCommits === true,
+        agenticHasDiffContext: false,
+        warning: commitPrefixIsCustom && createCommits !== true
+            ? 'A custom migrate commit prefix is configured, but commits are not enabled for this run, so it has no effect. Set `migrate.createCommits` to `true` (or pass `--create-commits`) to create a commit per migration.'
+            : undefined,
+    };
+}
+// The branch to hold `getBaseRef`'s value against. It may name a remote-tracking
+// ref whose local counterpart drops the remote (the CI-workflow generator writes
+// `origin/<branch>`), yet a local branch can be named `up/feature` while `up` is
+// a remote, so an exact match wins before any stripping and the longest matching
+// remote wins after. `origin` counts even undeclared: the generator assumes it.
+function defaultBranchToCompare(baseRef, currentBranch, root) {
+    if (currentBranch === baseRef) {
+        return baseRef;
+    }
+    const remote = [...(0, git_utils_1.getGitRemoteNames)(root), 'origin']
+        .filter((name) => baseRef.startsWith(`${name}/`))
+        .sort((a, b) => b.length - a.length)[0];
+    return remote ? baseRef.slice(remote.length + 1) : baseRef;
+}
+function currentBranchIfDefault(root) {
+    const currentBranch = (0, git_utils_1.getGitCurrentBranch)(root);
+    if (!currentBranch) {
+        return null;
+    }
+    const defaultBranch = defaultBranchToCompare((0, command_line_utils_1.getBaseRef)((0, configuration_1.readNxJson)(root)), currentBranch, root);
+    return currentBranch === defaultBranch ? currentBranch : null;
+}
+/**
+ * Asks before a run starts committing on the workspace's default branch, and
+ * reports the decision when the answer is no. Returns whether to proceed.
+ *
+ * Callers gate this on commits being effective and on prompting being
+ * possible, so non-interactive runs (CI, `--no-interactive`) never reach here;
+ * `confirmCommitsOnDefaultBranch` has no guard of its own and would block on a
+ * prompt nobody can answer.
+ */
+async function confirmMigrationCommitsOnDefaultBranch(root, whatWouldRun) {
+    const currentBranch = (0, git_utils_1.getGitCurrentBranch)(root);
+    const proceed = await confirmCommitsOnDefaultBranch({
+        currentBranch,
+        defaultBranch: defaultBranchToCompare((0, command_line_utils_1.getBaseRef)((0, configuration_1.readNxJson)(root)), currentBranch, root),
+    });
+    if (!proceed) {
+        output_1.output.log({
+            title: `Skipped ${whatWouldRun} to avoid committing to the default branch '${currentBranch}'.`,
+            bodyLines: [
+                'Switch to a different branch and re-run, or re-run and confirm to proceed.',
+            ],
+        });
+    }
+    return proceed;
+}
+async function confirmCommitsOnDefaultBranch(args) {
+    const { currentBranch, defaultBranch } = args;
+    if (!currentBranch || !defaultBranch || currentBranch !== defaultBranch) {
+        return true;
+    }
+    return (0, safe_prompt_1.migrateConfirm)({
+        message: `You're on the default branch '${currentBranch}'. nx migrate will create a commit for each migration on this branch. Continue?`,
+        initial: false,
+    });
+}

package/dist/src/command-line/migrate/migrate-config.d.ts

@@ -0,0 +1,32 @@
+import type { NxMigrateConfiguration } from '../../config/nx-json';
+import { type MigrateArgs } from './command-object';
+/**
+ * Overlays `nx.json` `migrate` defaults onto the raw CLI args: a CLI flag wins,
+ * then `nx.json`, then the built-in default. Returns a new args object; the
+ * input is not mutated.
+ *
+ * Phase-aware so each option is only filled where it is consumed, and so a
+ * config value never trips the mutually-exclusive-flag guards in
+ * `parseMigrationsOptions`: `include` and `multiMajorMode` in the generate
+ * phase only; `createCommits` / `commitPrefix` and `agentic` / `validate` when
+ * running the whole migrations file or a standalone single migration. A
+ * `--run-id` reconcile or recorded worker takes none of them: a recorded run
+ * takes its commit config from run.json and is driven by the outer agent. A
+ * `--run-migrations --run-id` continue takes `agentic` only, to select the
+ * agent of the new session. A `--start-fresh` starts a new run and takes all
+ * four.
+ *
+ * `include` is carried as `includeFromConfig` so it is never mistaken for an
+ * explicit `--include`: `resolveInclude` applies it only when the resolved
+ * target supports optional updates.
+ */
+export declare function applyNxJsonMigrateDefaults(args: MigrateArgs, migrateConfig: NxMigrateConfiguration | undefined, env?: NodeJS.ProcessEnv): MigrateArgs;
+/**
+ * The single authority for the "a custom commit prefix needs commits enabled"
+ * invariant. Run it against the final merged args (after
+ * `applyNxJsonMigrateDefaults`): the yargs `.check()` only sees the CLI args,
+ * but nx.json may enable commits via `createCommits` or `agentic`. The CLI
+ * `.check()` only fast-fails the unrescuable explicit `--no-create-commits`
+ * case; everything else is decided here.
+ */
+export declare function assertCommitPrefixHasCommits(merged: MigrateArgs): void;

package/dist/src/command-line/migrate/migrate-config.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyNxJsonMigrateDefaults = applyNxJsonMigrateDefaults;
+exports.assertCommitPrefixHasCommits = assertCommitPrefixHasCommits;
+const cli_args_1 = require("./agentic/cli-args");
+const command_object_1 = require("./command-object");
+const MULTI_MAJOR_MODE_ENV = 'NX_MULTI_MAJOR_MODE';
+/**
+ * Overlays `nx.json` `migrate` defaults onto the raw CLI args: a CLI flag wins,
+ * then `nx.json`, then the built-in default. Returns a new args object; the
+ * input is not mutated.
+ *
+ * Phase-aware so each option is only filled where it is consumed, and so a
+ * config value never trips the mutually-exclusive-flag guards in
+ * `parseMigrationsOptions`: `include` and `multiMajorMode` in the generate
+ * phase only; `createCommits` / `commitPrefix` and `agentic` / `validate` when
+ * running the whole migrations file or a standalone single migration. A
+ * `--run-id` reconcile or recorded worker takes none of them: a recorded run
+ * takes its commit config from run.json and is driven by the outer agent. A
+ * `--run-migrations --run-id` continue takes `agentic` only, to select the
+ * agent of the new session. A `--start-fresh` starts a new run and takes all
+ * four.
+ *
+ * `include` is carried as `includeFromConfig` so it is never mistaken for an
+ * explicit `--include`: `resolveInclude` applies it only when the resolved
+ * target supports optional updates.
+ */
+function applyNxJsonMigrateDefaults(args, migrateConfig, env = process.env) {
+    if (!migrateConfig) {
+        return args;
+    }
+    const merged = { ...args };
+    // `--run-migrations` with no value is normalized to '' by yargs, so a defined
+    // (even empty-string) value means we're in the run-migrations phase.
+    const isRunMigrations = merged.runMigrations !== undefined;
+    // A bare `--run-id` (orchestrated reconcile) must never take the
+    // generate-options overlay, which would leak `include` etc. from nx.json.
+    const isSingleMigration = merged.runMigration !== undefined || merged.runId !== undefined;
+    // These overlays are for an invocation that decides the options for itself,
+    // which a `--run-id` invocation only does when it starts fresh: the recorded
+    // worker and the reconcile both read the commit config from run.json.
+    const startsRun = (isRunMigrations || isSingleMigration) &&
+        (merged.runId === undefined || merged.startFresh === true);
+    if (startsRun) {
+        if (merged.createCommits === undefined &&
+            migrateConfig.createCommits !== undefined) {
+            assertType(migrateConfig.createCommits, 'boolean', 'createCommits');
+            merged.createCommits = migrateConfig.createCommits;
+        }
+        // `commitPrefix` carries a yargs default, so the default value is
+        // indistinguishable from "not provided" - treat it as not provided so
+        // nx.json can override it.
+        if ((merged.commitPrefix === undefined ||
+            merged.commitPrefix === command_object_1.DEFAULT_MIGRATION_COMMIT_PREFIX) &&
+            migrateConfig.commitPrefix !== undefined) {
+            assertType(migrateConfig.commitPrefix, 'string', 'commitPrefix');
+            merged.commitPrefix = migrateConfig.commitPrefix;
+        }
+        if (merged.validate === undefined && migrateConfig.validate !== undefined) {
+            assertType(migrateConfig.validate, 'boolean', 'validate');
+            merged.validate = migrateConfig.validate;
+        }
+    }
+    // A continue takes `agentic` too; the reconcile and the worker must not:
+    // there it trips the `--agentic`/`--run-id` parse conflict.
+    if ((startsRun || isRunMigrations) &&
+        merged.agentic === undefined &&
+        migrateConfig.agentic !== undefined) {
+        assertValidAgentic(migrateConfig.agentic);
+        merged.agentic = (0, cli_args_1.coerceAgenticArg)(migrateConfig.agentic);
+    }
+    if (!isRunMigrations && !isSingleMigration) {
+        if (merged.include === undefined && migrateConfig.include !== undefined) {
+            assertOneOf(migrateConfig.include, command_object_1.MIGRATE_INCLUDE_VALUES, 'include');
+            merged.includeFromConfig = migrateConfig.include;
+        }
+        // The NX_MULTI_MAJOR_MODE env var is an established per-invocation override,
+        // so it takes precedence over nx.json (CLI flag > env > nx.json > default).
+        if (merged.multiMajorMode === undefined &&
+            !env[MULTI_MAJOR_MODE_ENV] &&
+            migrateConfig.multiMajorMode !== undefined) {
+            assertOneOf(migrateConfig.multiMajorMode, command_object_1.MULTI_MAJOR_MODES, 'multiMajorMode');
+            merged.multiMajorMode = migrateConfig.multiMajorMode;
+        }
+    }
+    return merged;
+}
+function assertOneOf(value, allowed, field) {
+    if (!allowed.includes(value)) {
+        throw new Error(`Error: Invalid nx.json migrate.${field} "${value}". Allowed: ${allowed.join(', ')}.`);
+    }
+}
+function assertType(value, type, field) {
+    if (typeof value !== type) {
+        throw new Error(`Error: Invalid nx.json migrate.${field} ${JSON.stringify(value)}. Expected a ${type}.`);
+    }
+}
+function assertValidAgentic(agentic) {
+    if (typeof agentic === 'boolean') {
+        return;
+    }
+    if (typeof agentic !== 'string' ||
+        !cli_args_1.AGENT_IDS.includes(agentic)) {
+        throw new Error(`Error: Invalid nx.json migrate.agentic "${agentic}". Allowed: ${cli_args_1.AGENT_IDS.join(', ')}, true, false.`);
+    }
+}
+/**
+ * The single authority for the "a custom commit prefix needs commits enabled"
+ * invariant. Run it against the final merged args (after
+ * `applyNxJsonMigrateDefaults`): the yargs `.check()` only sees the CLI args,
+ * but nx.json may enable commits via `createCommits` or `agentic`. The CLI
+ * `.check()` only fast-fails the unrescuable explicit `--no-create-commits`
+ * case; everything else is decided here.
+ */
+function assertCommitPrefixHasCommits(merged) {
+    const { createCommits, commitPrefix, agentic } = merged;
+    if ((0, command_object_1.customCommitPrefixHasNoEffect)({ createCommits, commitPrefix, agentic })) {
+        throw new Error('Error: A custom migrate commit prefix requires commits to be enabled. Set `migrate.createCommits` to `true` in nx.json or pass `--create-commits`.');
+    }
+}

package/dist/src/command-line/migrate/migrate-output.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Pure presentation helpers for the migrate run phase (`--run-migrations` and
+ * the single-migration worker). Shared glyph vocabulary:
+ *   `→` start, `✓` success, `✗` failure, `↷` skipped, `ℹ` info, `─` boundary
+ *
+ * Inputs are typed structurally (e.g. `{ name: string }[]`) so this module
+ * stays decoupled from the migration executor in migrate.ts.
+ */
+/**
+ * Some agent TUIs (codex, opencode) don't fully reset their cursor / SGR state
+ * when they exit, which corrupts subsequent orchestrator output. Emit an SGR
+ * reset + newline so our log lines land on a clean row instead of being
+ * overlaid by leftover status bars.
+ */
+export declare function resetSgrAfterAgent(): void;
+/**
+ * Per-migration boundary header. Anchors the orchestrator log at the start of
+ * each migration with the migration index and identity.
+ */
+export declare function logMigrationBoundary(index: number, total: number, pkg: string, name: string): void;
+/**
+ * Logs the outcome line that closes an agentic phase. Vocabulary:
+ *   ✓ <label>[ (<sha>)]: <summary>
+ */
+export declare function logAgenticSuccessOutcome(label: string, sha: string | null, summary: string): void;
+/**
+ * Callers must already know an agentic step was owed; this only picks which one
+ * the waiver dropped. The dropped-`agentContext` note is aimed at the migration
+ * author, hence `--verbose`.
+ */
+export declare function logWaivedAgenticStep(migration: {
+    package: string;
+    name: string;
+    prompt?: string;
+    implementation?: string;
+    factory?: string;
+}, agentContext: string[]): void;
+/**
+ * Per-migration outcome record consumed by the failure recap. One entry is
+ * appended per iteration that returned without throwing; the failing migration
+ * has no record.
+ *
+ * - `applied`: ran fully to completion, including any agentic step.
+ * - `no-changes`: generator ran but produced no diff (counts as applied work).
+ * - `deferred`: prompt half was not applied (agent disabled or inside-agent
+ *   mode hands it off). For hybrid migrations the deterministic half still ran.
+ *
+ * `committedAsPartOf` is set when this migration's own commit attempt failed
+ * but its diff was later absorbed into a successor migration's commit (which
+ * stages the working tree's accumulated state via `git add -A`). The recap
+ * uses this to anchor "last applied" honestly when the last-named commit
+ * landed multiple migrations' contributions.
+ */
+export type MigrationOutcomeKind = 'applied' | 'no-changes' | 'deferred';
+/**
+ * The state of a migration's commit attempt. Tagged union so consumers don't
+ * have to re-derive legal combinations from nullable fields.
+ *
+ * - `none`     — no commit was attempted (`--no-create-commits` or no diff to
+ *                commit).
+ * - `landed`   — a commit was actually created. `sha: null` only when
+ *                `git rev-parse HEAD` failed transiently right after the
+ *                commit landed; by contract the diff did clear.
+ * - `failed`   — commit was attempted and errored (signing, hook rejection,
+ *                lock, install error mid-attempt, etc.). The diff stays in
+ *                the working tree until a later migration's commit absorbs
+ *                it (then transitions to `absorbed`) or until the run ends
+ *                (then surfaces as retained state).
+ * - `absorbed` — own commit failed but a later migration's commit absorbed
+ *                this diff via `git add -A`. `into.sha: null` means that
+ *                absorbing commit itself hit a HEAD-resolve race; the recap
+ *                renders an anchor without a sha.
+ */
+export type CommitState = {
+    kind: 'none';
+} | {
+    kind: 'landed';
+    sha: string | null;
+} | {
+    kind: 'failed';
+} | {
+    kind: 'absorbed';
+    into: {
+        name: string;
+        sha: string | null;
+    };
+};
+/**
+ * Per-migration record produced by the executor loop. `status: 'completed'`
+ * carries the kind (applied / no-changes / deferred); `status: 'aborted'`
+ * means the migration threw before completing — the executor's catch block
+ * records it so the recap can list it under retained-state alongside any
+ * other migrations whose commits never landed.
+ *
+ * `waivedAgenticStep` is set when the migration returned `skipAgentic: true`
+ * and something was actually waived: a hybrid's prompt, which is owed in every
+ * agentic mode, or a generator-only migration's validation step, only when it
+ * would have run. Recorded here rather than counted in the executor so the
+ * success tally and the failure recap derive the same number from the same
+ * records instead of threading a counter through both.
+ */
+export type MigrationOutcome = {
+    migration: {
+        package: string;
+        name: string;
+    };
+    status: 'completed';
+    kind: MigrationOutcomeKind;
+    commit: CommitState;
+    waivedAgenticStep?: boolean;
+} | {
+    migration: {
+        package: string;
+        name: string;
+    };
+    status: 'aborted';
+    commit: CommitState;
+};
+/**
+ * Counts the migrations whose own commit actually landed — including the
+ * HEAD-resolve-race case (`commit: { kind: 'landed', sha: null }`). Used by
+ * the end-of-run "<K> commits created" tally and by the success-path
+ * accounting in `executeMigrations`. Counts landed-commit *records* rather
+ * than distinct shas; absorbed predecessors (`kind: 'absorbed'`) are not
+ * counted because the absorbing commit's record already contributes one.
+ */
+export declare function countLandedCommits(outcomes: ReadonlyArray<MigrationOutcome>): number;
+/**
+ * Counts the migrations that waived the AI step they would otherwise have
+ * run. Shared by the success tally and the failure recap so the two can't
+ * report different numbers.
+ */
+export declare function countWaivedAgenticSteps(outcomes: ReadonlyArray<MigrationOutcome>): number;
+/**
+ * The recap phrase for waived AI steps. "not needed" rather than
+ * "skipped"/"deferred", which both recaps reserve for work the user still
+ * owes.
+ */
+export declare function formatWaivedAgenticSteps(count: number): string;
+/**
+ * Migrations whose own commit attempt failed and whose diff was never
+ * absorbed by a later commit. Surfaces what the user has to commit or
+ * revert after the run. Filters on `commit.kind === 'failed'` exactly —
+ * `'absorbed'` means the diff cleared into a later commit, `'none'` means
+ * no commit was attempted (intentional `--no-create-commits` or no-op).
+ */
+export declare function retainedMigrations(outcomes: ReadonlyArray<MigrationOutcome>): Array<{
+    package: string;
+    name: string;
+}>;
+/**
+ * Logs a structured recap when a migration throws mid-loop. Inserted between
+ * the "Failed to run X" error block and the re-throw so the user (or AI agent
+ * driving the run) can see what completed before the failure without scrolling
+ * back through the per-migration log to count shas.
+ *
+ * Counts-based rather than full migration lists so a 24-migration run that
+ * fails at #12 doesn't dump 24 names into the recap — readers scroll up to
+ * see specifics in the per-migration log. The "last applied" anchor pairs the
+ * most recent fully-applied migration with the sha its commit actually
+ * produced, so a skipped/deferred step trailing an applied one can't borrow
+ * the earlier sha.
+ */
+export declare function logFailureRecap(opts: {
+    migrationIndex: number;
+    totalMigrations: number;
+    outcomes: ReadonlyArray<MigrationOutcome>;
+    migrationEmittedNextSteps: string[];
+    insideAgent: boolean;
+}): void;
+/**
+ * Builds the tally body line shown under the top end-of-run NX block. Returns
+ * `null` when there is nothing meaningful to tally (e.g. an empty
+ * migrations.json), so the caller can omit the body entirely instead of
+ * emitting a misleading `0 prompt migrations skipped.` line.
+ *
+ * Rule (kept coherent across every scenario):
+ * - When at least one migration was applied: `<N> migrations applied, <K> commits created[, <D> prompt migrations <skipped|deferred>][, <W> AI steps not needed]`.
+ *   The `<K> commits created` part stays even at 0 — it tells the reader work
+ *   was applied but not committed (the J4/J8 information made explicit).
+ * - When zero migrations were applied but some prompt halves were
+ *   skipped/deferred: `<D> prompt migrations <skipped|deferred>` only. Waiving
+ *   never adds to `skippedPromptsCount`, so `appliedCount` is non-zero whenever
+ *   `waivedAgenticStepsCount` is, and this branch can't be reached with one.
+ * - When zero of either: no body line.
+ */
+export declare function buildTallyBodyLine(opts: {
+    appliedCount: number;
+    committedShasCount: number;
+    skippedPromptsCount: number;
+    waivedAgenticStepsCount: number;
+    insideAgent: boolean;
+}): string | null;
+/**
+ * Body lines for the end-of-run retained-state warning. Fires on the success
+ * path — the run completed but one or more migrations' own commits failed
+ * and were never absorbed.
+ */
+export declare function buildRetainedAtSuccessBody(retainedNames: ReadonlyArray<string>): string[];
+/**
+ * Builds the body lines for the inside-agent directive block. Sub-sections
+ * drop independently when empty. Returns an empty array when the block has
+ * nothing actionable (no deferred prompts AND no migration-emitted notes) —
+ * the caller skips emitting the block entirely in that case.
+ */
+export declare function buildDirectiveBlockBodyLines(opts: {
+    skippedPrompts: ReadonlyArray<{
+        prompt?: string;
+        name: string;
+        implementation?: string;
+        factory?: string;
+    }>;
+    migrationEmittedNextSteps: string[];
+}): string[];