@ohos-ports/nx 23.3.0-beta.2 → 24.0.2-beta.0

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

@@ -1,5 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIGRATE_OWNED_PATHS = void 0;
+exports.migrateCommitExcludes = migrateCommitExcludes;
+exports.migrateTreeStatus = migrateTreeStatus;
 exports.commitMigrationIfRequested = commitMigrationIfRequested;
 exports.commitCheckpointBeforeMigrations = commitCheckpointBeforeMigrations;
 exports.resolveCreateCommits = resolveCreateCommits;
@@ -14,35 +17,93 @@ 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 prompt_files_1 = require("./prompt-files");
 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];
+const MIGRATE_PLAN_PATHS = ['migrations.json', prompt_files_1.AI_MIGRATIONS_DIR];
+/** Workspace-relative paths nx migrate writes for itself. */
+exports.MIGRATE_OWNED_PATHS = [
+    types_1.MIGRATE_RUNS_RELATIVE_DIR,
+    ...MIGRATE_PLAN_PATHS,
+];
+/**
+ * The scratch state is excluded even when git ignores it, since its ignore
+ * rule can go missing mid-run.
+ */
+function migrateCommitExcludes(root) {
+    return [
+        types_1.MIGRATE_RUNS_RELATIVE_DIR,
+        ...MIGRATE_PLAN_PATHS.filter((path) => isUncommitted(path, root)),
+    ];
+}
+function isUncommitted(path, root) {
+    const status = (0, git_utils_1.getPathHeadStatus)(path, root);
+    switch (status) {
+        case 'absent':
+            return true;
+        // On a failed probe the path stays visible, so clean-tree checks err
+        // toward dirty.
+        case 'committed':
+        case 'unknown':
+            return false;
+        default: {
+            const unhandled = status;
+            throw new Error(`Unhandled path HEAD status: ${unhandled}`);
+        }
+    }
+}
+function migrateTreeStatus(root) {
+    return (0, git_utils_1.getWorkingTreeStatus)(root, migrateCommitExcludes(root));
+}
+const AGENT_SESSION_NO_INPUT = "Commits in this session cannot ask for input, such as a signing passphrase or a hook's prompt";
+function commitFailureGuidance(recovery, inAgentSession) {
+    switch (recovery) {
+        case 'later-step':
+            // Without the session half, the agent continues as the absorb guidance
+            // says, and a cause that fails every commit leaves the run uncommitted.
+            return `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.${inAgentSession
+                ? ` ${AGENT_SESSION_NO_INPUT}, so later commits may fail the same way until the cause is fixed. Before the next step, tell the user what failed and ask whether to fix the cause first or to continue as is. Either way nx tries every later commit, and the first one that lands includes these changes.`
+                : ''}`;
+        case 'manual':
+            return `Commit or revert any remaining uncommitted changes manually.${inAgentSession
+                ? ` ${AGENT_SESSION_NO_INPUT}. Tell the user what failed.`
+                : ''}`;
+        default: {
+            const unhandled = recovery;
+            throw new Error(`Unhandled commit failure recovery: ${unhandled}`);
+        }
+    }
+}
 /**
  * `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.
+ * `recovery` picks the failure guidance: the default describes the classic
+ * loop's absorb-and-recap behavior, and a caller with no later migration step
+ * (a `--run-migration` run) passes 'manual'.
+ *
+ * A `sink` collects the output for a caller sharing the terminal with an
+ * agent, and the commit then runs without the terminal.
  */
-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) {
+async function commitMigrationIfRequested(root, migration, shouldCreateCommits, commitPrefix, installDepsIfChanged, pendingMigrations = [], recovery = 'later-step', sink) {
     if (!shouldCreateCommits)
         return { status: 'disabled' };
+    const out = sink ?? deferred_output_1.terminalOutput;
     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.
+    // Generator may have only touched gitignored paths or the excluded owned
+    // paths, 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)) {
+    const excludes = migrateCommitExcludes(root);
+    if (!(0, git_utils_1.hasUncommittedChanges)(root, 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);
+        const sha = await (0, git_utils_1.tryCommitChangesAsync)(commitMessage, root, excludes, {
+            withoutTerminal: sink !== undefined,
+        });
         if (sha)
             return { status: 'committed', sha };
         // null = commit landed but `git rev-parse HEAD` failed (see
@@ -52,7 +113,7 @@ async function commitMigrationIfRequested(root, migration, shouldCreateCommits,
     }
     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}`);
+        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. ${commitFailureGuidance(recovery, sink !== undefined)}`);
         return { status: 'failed', reason };
     }
 }
@@ -76,19 +137,21 @@ function buildCommitMessage(subject, pendingMigrations) {
     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.
+ * Commits pre-existing working-tree state, except what `migrateCommitExcludes`
+ * leaves out, 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))
+    const excludes = migrateCommitExcludes(root);
+    if (!(0, git_utils_1.hasUncommittedChanges)(root, excludes))
         return;
     try {
-        const sha = (0, git_utils_1.tryCommitChanges)(`${commitPrefix}checkpoint before running migrations`, root, MIGRATE_COMMIT_EXCLUDES);
+        const sha = (0, git_utils_1.tryCommitChanges)(`${commitPrefix}checkpoint before running migrations`, root, excludes);
         if (sha) {
             logger_1.logger.info(pc.dim(`- Checkpoint commit created: ${sha}`));
             return;
@@ -113,11 +176,6 @@ function commitCheckpointBeforeMigrations(root, commitPrefix) {
         });
     }
 }
-/**
- * `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,
@@ -127,7 +185,6 @@ function resolveCreateCommits(args) {
     if (createCommits === true && !isGitRepo) {
         return {
             effective: false,
-            agenticHasDiffContext: false,
             error: '`--create-commits` requires a git repository. Run `git init` first, or omit the flag.',
         };
     }
@@ -135,7 +192,6 @@ function resolveCreateCommits(args) {
         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.") +
@@ -149,7 +205,6 @@ function resolveCreateCommits(args) {
         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.') +
@@ -158,11 +213,10 @@ function resolveCreateCommits(args) {
                         : ''),
             };
         }
-        return { effective: true, agenticHasDiffContext: true };
+        return { effective: 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,

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

@@ -9,12 +9,12 @@ import { type MigrateArgs } from './command-object';
  * 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.
+ * running the whole migrations file or a standalone single migration, and
+ * `finalValidation` for the whole file only. 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 five.
  *
  * `include` is carried as `includeFromConfig` so it is never mistaken for an
  * explicit `--include`: `resolveInclude` applies it only when the resolved

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

@@ -14,12 +14,12 @@ const MULTI_MAJOR_MODE_ENV = 'NX_MULTI_MAJOR_MODE';
  * 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.
+ * running the whole migrations file or a standalone single migration, and
+ * `finalValidation` for the whole file only. 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 five.
  *
  * `include` is carried as `includeFromConfig` so it is never mistaken for an
  * explicit `--include`: `resolveInclude` applies it only when the resolved
@@ -60,6 +60,12 @@ function applyNxJsonMigrateDefaults(args, migrateConfig, env = process.env) {
             assertType(migrateConfig.validate, 'boolean', 'validate');
             merged.validate = migrateConfig.validate;
         }
+        if (isRunMigrations &&
+            merged.finalValidation === undefined &&
+            migrateConfig.finalValidation !== undefined) {
+            assertType(migrateConfig.finalValidation, 'boolean', 'finalValidation');
+            merged.finalValidation = migrateConfig.finalValidation;
+        }
     }
     // A continue takes `agentic` too; the reconcile and the worker must not:
     // there it trips the `--agentic`/`--run-id` parse conflict.

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

@@ -1,7 +1,7 @@
 /**
  * Pure presentation helpers for the migrate run phase (`--run-migrations` and
  * the single-migration worker). Shared glyph vocabulary:
- *   `→` start, `✓` success, `✗` failure, `↷` skipped, `ℹ` info, `─` boundary
+ *   `→` start, `↷` skipped, `ℹ` info, `─` boundary
  *
  * Inputs are typed structurally (e.g. `{ name: string }[]`) so this module
  * stays decoupled from the migration executor in migrate.ts.
@@ -18,11 +18,6 @@ export declare function resetSgrAfterAgent(): void;
  * 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

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

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resetSgrAfterAgent = resetSgrAfterAgent;
 exports.logMigrationBoundary = logMigrationBoundary;
-exports.logAgenticSuccessOutcome = logAgenticSuccessOutcome;
 exports.logWaivedAgenticStep = logWaivedAgenticStep;
 exports.countLandedCommits = countLandedCommits;
 exports.countWaivedAgenticSteps = countWaivedAgenticSteps;
@@ -19,7 +18,7 @@ const migration_shape_1 = require("./migration-shape");
 /**
  * Pure presentation helpers for the migrate run phase (`--run-migrations` and
  * the single-migration worker). Shared glyph vocabulary:
- *   `→` start, `✓` success, `✗` failure, `↷` skipped, `ℹ` info, `─` boundary
+ *   `→` start, `↷` skipped, `ℹ` info, `─` boundary
  *
  * Inputs are typed structurally (e.g. `{ name: string }[]`) so this module
  * stays decoupled from the migration executor in migrate.ts.
@@ -43,14 +42,6 @@ function logMigrationBoundary(index, total, pkg, name) {
     const dashes = Math.max(3, targetWidth - label.length);
     logger_1.logger.info(`${label}${'─'.repeat(dashes)}`);
 }
-/**
- * Logs the outcome line that closes an agentic phase. Vocabulary:
- *   ✓ <label>[ (<sha>)]: <summary>
- */
-function logAgenticSuccessOutcome(label, sha, summary) {
-    const shaPart = sha ? ` (${sha})` : '';
-    logger_1.logger.info(`${pc.green('✓')} ${label}${shaPart}: ${summary}`);
-}
 /**
  * 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

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

@@ -81,6 +81,7 @@ export declare class Migrator {
             prompt?: string;
             requires?: Record<string, string>;
             documentation?: string;
+            optionalUpdate?: boolean;
             package: string;
             name: string;
         }[];
@@ -111,6 +112,8 @@ export declare class Migrator {
     private addPackageUpdate;
     private areRequirementsMet;
     private areIncompatiblePackagesPresent;
+    private shouldCollectMigration;
+    private areRequirementsMetAfterUpdates;
     private areMigrationRequirementsMet;
     private isMigrationForHigherVersionThanWhatIsInstalled;
     private wasMigrationSkipped;
@@ -196,7 +199,9 @@ export { filterDowngradedUpdates };
 export declare function generateMigrationsJsonAndUpdatePackageJson(root: string, opts: GenerateMigrations, fetch?: MigratorOptions['fetch']): Promise<void>;
 export { isPromptOnlyMigration, isHybridMigration };
 export declare function formatSkippedPromptsNextStep(skipped: PlannedMigration[]): string;
-export declare function executeMigrations(root: string, migrations: PlannedMigration[], isVerbose: boolean, shouldCreateCommits: boolean, commitPrefix: string, shouldSkipInstall?: boolean, agentic?: ResolvedAgentic, agenticHasDiffContext?: boolean, shouldRunValidation?: boolean): Promise<{
+export declare function executeMigrations(root: string, migrations: PlannedMigration[], isVerbose: boolean, shouldCreateCommits: boolean, commitPrefix: string, shouldSkipInstall?: boolean, agentic?: Exclude<ResolvedAgentic, {
+    kind: 'enabled';
+}>): Promise<{
     migrationsWithNoChanges: PlannedMigration[];
     skippedPromptsCount: number;
     notRunMigrationsCount: number;
@@ -213,33 +218,4 @@ export declare function migrate(root: string, args: {
 }, rawArgs: string[]): Promise<number>;
 export declare function readLocalNxVersion(root: string): string | undefined;
 export declare function runMigration(): Promise<number>;
-/**
- * Resolves a migration's collection once and derives everything the run loop
- * needs from that single read: the implementation context (`collection` +
- * `collectionPath`, handed to `runNxOrAngularMigration`) and, for agentic runs,
- * the workspace-relative documentation path handed to the agent.
- *
- * Read fresh per migration (not cached across the loop) so a prior migration's
- * reinstall is reflected, exactly as before. Error handling matches each field's
- * role:
- * - Migrations that run an implementation REQUIRE the collection; an unreadable
- *   collection throws and aborts that migration (caught by the run loop).
- * - Prompt-only migrations don't run an implementation, so the collection is
- *   read only to resolve documentation - a failure there is non-fatal: the
- *   prompt still runs and the supplementary doc is skipped with a warning.
- */
-export declare function resolveMigrationForRun(root: string, migration: {
-    package: string;
-    name: string;
-    documentation?: string;
-    implementation?: string;
-    factory?: string;
-    prompt?: string;
-}, resolveDocumentation: boolean): {
-    resolvedCollection?: {
-        collection: MigrationsJson;
-        collectionPath: string;
-    };
-    documentationPath?: string;
-};
 export declare function nxCliPath(nxWorkspaceRoot?: string): Promise<string>;