@depup/nx 23.1.2-depup.1 → 23.2.0-depup.0

package/dist/src/command-line/migrate/agentic/types.js

@@ -1,2 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.HANDOFFS_DIR_NAME = exports.MIGRATE_RUNS_RELATIVE_DIR = void 0;
+exports.isHandoffGitignoreMigration = isHandoffGitignoreMigration;
+/**
+ * Workspace-relative directory holding all migrate-run scratch: a run
+ * directory per run id. Shared by the run-dir layout in `handoff.ts` and the
+ * agent permission rules in `definitions.ts` so the pre-authorized write scope
+ * can't drift from the actual layout. It lives here so `definitions.ts`,
+ * loaded whenever the agentic flow is resolved, doesn't pull in the handoff
+ * runtime for the path alone.
+ */
+exports.MIGRATE_RUNS_RELATIVE_DIR = '.nx/migrate-runs';
+/**
+ * The one subtree of a run directory an agent writes: its handoff files.
+ * Everything beside it is state Nx owns and reads back, the orchestrator's
+ * run state and plan snapshots included, so the pre-authorized write scope
+ * stops at this segment. Package names make up the rest of a handoff path,
+ * so without it they would occupy the run directory's top level and leave Nx
+ * no name it could add there safely.
+ */
+exports.HANDOFFS_DIR_NAME = 'handoffs';
+/**
+ * Composite identity of the v23 migration that adds `.nx/migrate-runs` to
+ * `.gitignore`. Hard-coded because the agentic preflight is a deliberate
+ * one-off coupling: this exact migration owns the entry that keeps
+ * `.nx/migrate-runs/<run-id>/...` scratch out of per-migration commits. If
+ * the migration is ever renamed, this entry must move with it. It lives here
+ * rather than in `handoff-gitignore.ts` so `sortMigrations`' hoist check
+ * doesn't load that module's migration-execution machinery.
+ */
+const HANDOFF_GITIGNORE_MIGRATION_PACKAGE = 'nx';
+const HANDOFF_GITIGNORE_MIGRATION_NAME = '23-0-0-add-migrate-runs-to-git-ignore';
+function isHandoffGitignoreMigration(m) {
+    return (m.package === HANDOFF_GITIGNORE_MIGRATION_PACKAGE &&
+        m.name === HANDOFF_GITIGNORE_MIGRATION_NAME);
+}

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

@@ -1,5 +1,6 @@
 import { CommandModule } from 'yargs';
 import type { AgenticArg } from './agentic/select';
+import { type StepAction } from './step-actions';
 export declare const yargsMigrateCommand: CommandModule;
 export declare const yargsInternalMigrateCommand: CommandModule;
 export declare const DEFAULT_MIGRATION_COMMIT_PREFIX = "chore: [nx migration] ";
@@ -17,6 +18,9 @@ export type MultiMajorMode = (typeof MULTI_MAJOR_MODES)[number];
 export interface MigrateArgs {
     packageAndVersion?: string;
     runMigrations?: string;
+    runMigration?: string;
+    runId?: string;
+    stepAction?: StepAction;
     include?: MigrateInclude;
     /**
      * nx.json `migrate.include` default. Consumed by `resolveInclude` only when the
@@ -30,6 +34,8 @@ export interface MigrateArgs {
     commitPrefix?: string;
     agentic?: AgenticArg;
     validate?: boolean;
+    ifExists?: boolean;
+    interactive?: boolean;
     [key: string]: any;
 }
 /**

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

@@ -6,11 +6,13 @@ const handle_import_1 = require("../../utils/handle-import");
 const documentation_1 = require("../yargs-utils/documentation");
 const shared_options_1 = require("../yargs-utils/shared-options");
 const cli_args_1 = require("./agentic/cli-args");
+const step_actions_1 = require("./step-actions");
 exports.yargsMigrateCommand = {
     command: 'migrate [packageAndVersion]',
     describe: `Creates a migrations file or runs migrations from the migrations file.
   - Migrate packages and create migrations.json (e.g., nx migrate @nx/workspace@latest)
-  - Run migrations (e.g., nx migrate --run-migrations=migrations.json). Use flag --if-exists to run migrations only if the migrations file exists.`,
+  - Run migrations (e.g., nx migrate --run-migrations=migrations.json). Use flag --if-exists to run migrations only if the migrations file exists.
+  - Run a single migration from migrations.json by id (e.g., nx migrate --run-migration=@nx/js:my-migration).`,
     builder: (yargs) => (0, documentation_1.linkToNxDevAndExamples)(withMigrationOptions(yargs), 'migrate'),
     handler: async () => process.exit(await (await (0, handle_import_1.handleImport)('./migrate.js', __dirname)).runMigration()),
 };
@@ -51,6 +53,22 @@ function withMigrationOptions(yargs) {
         .option('runMigrations', {
         describe: `Execute migrations from a file (when the file isn't provided, execute migrations from migrations.json).`,
         type: 'string',
+    })
+        .option('runMigration', {
+        describe: "Run a single migration from migrations.json by id. The id is '<package>:<name>'; a bare '<name>' is accepted when it matches exactly one migration. A name that contains ':' must use the full '<package>:<name>' form.",
+        type: 'string',
+    })
+        .option('runId', {
+        // Hidden with the orchestrator itself.
+        describe: 'The orchestrated migrate run to record a single migration into, or to reconcile when given without --run-migration.',
+        type: 'string',
+        hidden: true,
+    })
+        .option('stepAction', {
+        describe: 'How an orchestrated reconcile resolves its single failed or died step.',
+        choices: step_actions_1.STEP_ACTIONS,
+        type: 'string',
+        hidden: true,
     })
         .option('ifExists', {
         describe: `Run migrations only if the migrations file exists, if not continues successfully.`,

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

@@ -6,7 +6,7 @@ interface PackageMigrationConfig extends NxMigrationsConfiguration {
     packageGroup: ArrayPackageGroup;
 }
 export declare function readPackageMigrationConfig(packageName: string, dir: string): PackageMigrationConfig;
-export declare function runInstall(nxWorkspaceRoot?: string, phase?: MigrationInstallPhase): Promise<void>;
+export declare function runInstall(nxWorkspaceRoot?: string, phase?: MigrationInstallPhase, rerunCommand?: string): Promise<void>;
 export type MigrationInstallPhase = 'pre-migration' | 'post-migration';
 export declare class NpmPeerDepsInstallError extends Error {
     constructor();
@@ -19,14 +19,24 @@ export declare class NpmPeerDepsInstallError extends Error {
  * captured output.
  */
 export declare function isNpmPeerDepsError(stderr: string): boolean;
-export declare function logNpmPeerDepsError(phase: MigrationInstallPhase): void;
+export declare function formatSingleMigrationRerunCommand(migrationId: string): string;
+export declare function logNpmPeerDepsError(phase: MigrationInstallPhase, rerunCommand?: string): void;
+export declare function logSkippedPostMigrationInstall(root: string): void;
 export declare class ChangedDepInstaller {
     private readonly root;
     private readonly shouldSkipInstall;
+    private readonly rerunCommand?;
     private initialDeps;
     private _skippedInstall;
-    constructor(root: string, shouldSkipInstall?: boolean);
+    private _installed;
+    constructor(root: string, shouldSkipInstall?: boolean, rerunCommand?: string);
     get skippedInstall(): boolean;
+    /**
+     * Whether an install actually ran. Distinct from `!skippedInstall`, which is
+     * only about the skip-install flag: dependencies that never changed leave
+     * both false.
+     */
+    get installed(): boolean;
     installDepsIfChanged(): Promise<void>;
 }
 export declare function runNxOrAngularMigration(root: string, migration: {
@@ -34,32 +44,41 @@ export declare function runNxOrAngularMigration(root: string, migration: {
     name: string;
     description?: string;
     version: string;
-}, isVerbose: boolean, captureGeneratorOutput?: boolean, resolvedCollection?: {
-    collection: MigrationsJson;
-    collectionPath: string;
-}): Promise<{
+}, isVerbose: boolean, captureGeneratorOutput?: boolean, resolvedCollection?: ResolvedMigrationCollection): Promise<{
     changes: FileChange[];
     nextSteps: string[];
     agentContext: string[];
+    skipAgentic: boolean;
     logs: string;
     madeChanges: boolean;
 }>;
+/**
+ * The workspace's declared dependencies, serialized for equality comparison,
+ * or `null` when package.json could not be read or parsed. Callers that
+ * persist the value across processes need that distinction: an unreadable
+ * package.json is not an empty dependency set.
+ */
+export declare function readPackageJsonDeps(root: string): string | null;
 export declare function getStringifiedPackageJsonDeps(root: string): string;
 export declare function runNxMigration(root: string, collectionPath: string, collection: MigrationsJson, name: string, migrationVersion: string | undefined, captureGeneratorOutput: boolean): Promise<{
     changes: FileChange[];
     nextSteps: string[];
     agentContext: string[];
+    skipAgentic: boolean;
     logs: string;
 }>;
 export declare function parseMigrationReturn(value: unknown): {
     nextSteps: string[];
     agentContext: string[];
+    skipAgentic: boolean;
 };
 export declare function filterStrings(value: unknown): string[];
-export declare function readMigrationCollection(packageName: string, root: string): {
+export interface ResolvedMigrationCollection {
     collection: MigrationsJson;
     collectionPath: string;
-};
+}
+export declare function readMigrationCollection(packageName: string, root: string): ResolvedMigrationCollection;
+export declare function resolveDocumentationFileToWorkspacePath(root: string, migrationsDir: string, documentation: string): string | undefined;
 export declare function getImplementationPath(collection: MigrationsJson, collectionPath: string, name: string, migrationVersion?: string): {
     path: string;
     fnSymbol: string;

package/dist/src/command-line/migrate/execute-migration.js

@@ -4,13 +4,17 @@ exports.getNgCompatLayer = exports.MigrationImplementationMissingError = exports
 exports.readPackageMigrationConfig = readPackageMigrationConfig;
 exports.runInstall = runInstall;
 exports.isNpmPeerDepsError = isNpmPeerDepsError;
+exports.formatSingleMigrationRerunCommand = formatSingleMigrationRerunCommand;
 exports.logNpmPeerDepsError = logNpmPeerDepsError;
+exports.logSkippedPostMigrationInstall = logSkippedPostMigrationInstall;
 exports.runNxOrAngularMigration = runNxOrAngularMigration;
+exports.readPackageJsonDeps = readPackageJsonDeps;
 exports.getStringifiedPackageJsonDeps = getStringifiedPackageJsonDeps;
 exports.runNxMigration = runNxMigration;
 exports.parseMigrationReturn = parseMigrationReturn;
 exports.filterStrings = filterStrings;
 exports.readMigrationCollection = readMigrationCollection;
+exports.resolveDocumentationFileToWorkspacePath = resolveDocumentationFileToWorkspacePath;
 exports.getImplementationPath = getImplementationPath;
 exports.isAngularMigration = isAngularMigration;
 const tslib_1 = require("tslib");
@@ -22,11 +26,13 @@ const handle_import_1 = require("../../utils/handle-import");
 const tree_1 = require("../../generators/tree");
 const fileutils_1 = require("../../utils/fileutils");
 const logger_1 = require("../../utils/logger");
+const text_1 = require("./text");
 const package_json_1 = require("../../utils/package-json");
 const package_manager_1 = require("../../utils/package-manager");
 const output_1 = require("../../utils/output");
 const fs_1 = require("fs");
 const installation_directory_1 = require("../../utils/installation-directory");
+const shell_quoting_1 = require("../../utils/shell-quoting");
 const project_graph_1 = require("../../project-graph/project-graph");
 const version_utils_1 = require("./version-utils");
 function readPackageMigrationConfig(packageName, dir) {
@@ -55,7 +61,7 @@ function readPackageMigrationConfig(packageName, dir) {
         };
     }
 }
-function runInstall(nxWorkspaceRoot, phase = 'pre-migration') {
+function runInstall(nxWorkspaceRoot, phase = 'pre-migration', rerunCommand) {
     const cwd = nxWorkspaceRoot ?? process.cwd();
     const packageManager = (0, package_manager_1.detectPackageManager)(cwd);
     const pmCommands = (0, package_manager_1.getPackageManagerCommand)(packageManager, cwd);
@@ -92,7 +98,7 @@ function runInstall(nxWorkspaceRoot, phase = 'pre-migration') {
                     // (CLI migrate, `nx repair`, single-migration runner, etc.) surfaces
                     // it consistently. Top-level callers catch `NpmPeerDepsInstallError`
                     // and return a non-zero exit code without re-logging.
-                    logNpmPeerDepsError(phase);
+                    logNpmPeerDepsError(phase, rerunCommand);
                     reject(new NpmPeerDepsInstallError());
                     return;
                 }
@@ -124,7 +130,20 @@ function isNpmPeerDepsError(stderr) {
         lowerStderr.includes('could not resolve dependency') ||
         lowerStderr.includes('conflicting peer dependency'));
 }
-function logNpmPeerDepsError(phase) {
+// The single-migration rerun command lands in copyable guidance (see
+// `logNpmPeerDepsError` below), so quote ids a shell would split or expand.
+// Single quotes stay literal in POSIX shells and PowerShell alike; double
+// quotes would leave $-expansion active in both. The embedded-quote escape is
+// the POSIX '\'' sequence, the one character PowerShell disagrees on (it wants
+// ''). cmd.exe is knowingly not covered: it does not group on single quotes,
+// and no quoting suppresses its %VAR% expansion.
+function formatSingleMigrationRerunCommand(migrationId) {
+    const id = (0, shell_quoting_1.needsShellQuoting)(migrationId)
+        ? `'${migrationId.replace(/'/g, String.raw `'\''`)}'`
+        : migrationId;
+    return `nx migrate --run-migration=${id}`;
+}
+function logNpmPeerDepsError(phase, rerunCommand = 'nx migrate --run-migrations') {
     const peerDepsResolutionSteps = [
         'Recommended approaches (in order of preference):',
         '',
@@ -138,7 +157,7 @@ function logNpmPeerDepsError(phase) {
     ];
     const manualInstallHint = [
         'If you installed the dependencies manually, pass "--skip-install" to avoid re-installing them:',
-        '   nx migrate --run-migrations --skip-install',
+        `   ${rerunCommand} --skip-install`,
     ];
     if (phase === 'pre-migration') {
         output_1.output.error({
@@ -146,8 +165,8 @@ function logNpmPeerDepsError(phase) {
             bodyLines: [
                 ...peerDepsResolutionSteps,
                 '',
-                'Once the conflicts are resolved, re-run the migrations:',
-                '   nx migrate --run-migrations',
+                'Once the conflicts are resolved, re-run the migration command:',
+                `   ${rerunCommand}`,
                 '',
                 ...manualInstallHint,
             ],
@@ -160,24 +179,42 @@ function logNpmPeerDepsError(phase) {
                 ...peerDepsResolutionSteps,
                 '',
                 'Once the conflicts are resolved, run "npm install" to install the updated dependencies.',
-                'If the migration was interrupted before completing, re-run the remaining migrations:',
-                '   nx migrate --run-migrations',
+                'If the migration run was interrupted before completing, re-run it:',
+                `   ${rerunCommand}`,
                 '',
                 ...manualInstallHint,
             ],
         });
     }
 }
+function logSkippedPostMigrationInstall(root) {
+    const packageManager = (0, package_manager_1.detectPackageManager)(root);
+    const installCommand = (0, package_manager_1.getPackageManagerCommand)(packageManager, root).install;
+    output_1.output.warn({
+        title: 'Migrations updated your dependencies, but the install was skipped',
+        bodyLines: [`Run "${installCommand}" to install the updated dependencies.`],
+    });
+}
 class ChangedDepInstaller {
-    constructor(root, shouldSkipInstall = false) {
+    constructor(root, shouldSkipInstall = false, rerunCommand) {
         this.root = root;
         this.shouldSkipInstall = shouldSkipInstall;
+        this.rerunCommand = rerunCommand;
         this._skippedInstall = false;
+        this._installed = false;
         this.initialDeps = getStringifiedPackageJsonDeps(root);
     }
     get skippedInstall() {
         return this._skippedInstall;
     }
+    /**
+     * Whether an install actually ran. Distinct from `!skippedInstall`, which is
+     * only about the skip-install flag: dependencies that never changed leave
+     * both false.
+     */
+    get installed() {
+        return this._installed;
+    }
     async installDepsIfChanged() {
         const currentDeps = getStringifiedPackageJsonDeps(this.root);
         if (this.initialDeps !== currentDeps) {
@@ -185,7 +222,8 @@ class ChangedDepInstaller {
                 this._skippedInstall = true;
             }
             else {
-                await runInstall(this.root, 'post-migration');
+                await runInstall(this.root, 'post-migration', this.rerunCommand);
+                this._installed = true;
             }
         }
         this.initialDeps = currentDeps;
@@ -197,6 +235,8 @@ async function runNxOrAngularMigration(root, migration, isVerbose, captureGenera
     let changes = [];
     let nextSteps = [];
     let agentContext = [];
+    // Angular schematics have no return channel, so they can never waive it.
+    let skipAgentic = false;
     let logs = '';
     // Angular's `ngResult.changes` is synthesized from the schematic's
     // DryRunEvent stream so Nx and Angular paths can share commit/validation
@@ -204,16 +244,24 @@ async function runNxOrAngularMigration(root, migration, isVerbose, captureGenera
     let madeChanges = false;
     logger_1.logger.info(pc.dim('→ Running generator…'));
     if (!isAngularMigration(collection, migration.name)) {
-        ({ nextSteps, changes, agentContext, logs } = await runNxMigration(root, collectionPath, collection, migration.name, migration.version, captureGeneratorOutput));
+        ({ nextSteps, changes, agentContext, skipAgentic, logs } =
+            await runNxMigration(root, collectionPath, collection, migration.name, migration.version, captureGeneratorOutput));
         madeChanges = changes.length > 0;
-        logger_1.logger.info(`Ran ${migration.name} from ${migration.package}`);
+        logger_1.logger.info((0, text_1.singleLine)(`Ran ${migration.name} from ${migration.package}`));
         if (migration.description) {
-            logger_1.logger.info(`  ${migration.description}`);
+            logger_1.logger.info((0, text_1.singleLine)(`  ${migration.description}`));
         }
         logger_1.logger.info('');
         if (!madeChanges) {
             logger_1.logger.info(`No changes were made\n`);
-            return { changes, nextSteps, agentContext, logs, madeChanges };
+            return {
+                changes,
+                nextSteps,
+                agentContext,
+                skipAgentic,
+                logs,
+                madeChanges,
+            };
         }
         logger_1.logger.info('Changes:');
         (0, tree_1.printChanges)(changes, '  ');
@@ -226,32 +274,48 @@ async function runNxOrAngularMigration(root, migration, isVerbose, captureGenera
         changes = ngResult.changes;
         madeChanges = ngResult.madeChanges;
         logs = ngResult.loggingQueue.join('\n');
-        logger_1.logger.info(`Ran ${migration.name} from ${migration.package}`);
+        logger_1.logger.info((0, text_1.singleLine)(`Ran ${migration.name} from ${migration.package}`));
         if (migration.description) {
-            logger_1.logger.info(`  ${migration.description}`);
+            logger_1.logger.info((0, text_1.singleLine)(`  ${migration.description}`));
         }
         logger_1.logger.info('');
         if (!madeChanges) {
             logger_1.logger.info(`No changes were made\n`);
-            return { changes, nextSteps, agentContext, logs, madeChanges };
+            return {
+                changes,
+                nextSteps,
+                agentContext,
+                skipAgentic,
+                logs,
+                madeChanges,
+            };
         }
         logger_1.logger.info('Changes:');
-        ngResult.loggingQueue.forEach((log) => logger_1.logger.info('  ' + log));
+        ngResult.loggingQueue.forEach((log) => logger_1.logger.info((0, text_1.singleLine)('  ' + log)));
         logger_1.logger.info('');
     }
-    return { changes, nextSteps, agentContext, logs, madeChanges };
+    return { changes, nextSteps, agentContext, skipAgentic, logs, madeChanges };
 }
-function getStringifiedPackageJsonDeps(root) {
+/**
+ * The workspace's declared dependencies, serialized for equality comparison,
+ * or `null` when package.json could not be read or parsed. Callers that
+ * persist the value across processes need that distinction: an unreadable
+ * package.json is not an empty dependency set.
+ */
+function readPackageJsonDeps(root) {
     try {
         const { dependencies, devDependencies } = (0, fileutils_1.readJsonFile)((0, path_1.join)(root, 'package.json'));
         return JSON.stringify([dependencies, devDependencies]);
     }
     catch {
-        // We don't really care if the .nx/installation property changes,
-        // whenever nxw is invoked it will handle the dep updates.
-        return '';
+        return null;
     }
 }
+function getStringifiedPackageJsonDeps(root) {
+    // We don't really care if the .nx/installation property changes,
+    // whenever nxw is invoked it will handle the dep updates.
+    return readPackageJsonDeps(root) ?? '';
+}
 async function runNxMigration(root, collectionPath, collection, name, migrationVersion, captureGeneratorOutput) {
     const { path: implPath, fnSymbol } = getImplementationPath(collection, collectionPath, name, migrationVersion);
     const fn = require(implPath)[fnSymbol];
@@ -265,25 +329,31 @@ async function runNxMigration(root, collectionPath, collection, name, migrationV
     else {
         result = await fn(host, {});
     }
-    const { nextSteps, agentContext } = parseMigrationReturn(result);
+    const { nextSteps, agentContext, skipAgentic } = parseMigrationReturn(result);
     host.lock();
     const changes = host.listChanges();
     (0, tree_1.flushChanges)(root, changes);
-    return { changes, nextSteps, agentContext, logs };
+    return { changes, nextSteps, agentContext, skipAgentic, logs };
 }
 function parseMigrationReturn(value) {
     if (Array.isArray(value)) {
-        return { nextSteps: filterStrings(value), agentContext: [] };
+        return {
+            nextSteps: filterStrings(value),
+            agentContext: [],
+            skipAgentic: false,
+        };
     }
     if (value && typeof value === 'object') {
         const obj = value;
         return {
             nextSteps: filterStrings(obj.nextSteps),
             agentContext: filterStrings(obj.agentContext),
+            // Strict, so a truthy non-boolean can't opt a migration out of its AI step.
+            skipAgentic: obj.skipAgentic === true,
         };
     }
     // Catches `void`, mistakenly-returned generator callbacks, malformed values.
-    return { nextSteps: [], agentContext: [] };
+    return { nextSteps: [], agentContext: [], skipAgentic: false };
 }
 // Bucket-level tolerance: a single non-string entry shouldn't discard the
 // whole `nextSteps` / `agentContext` array. Migration authors occasionally
@@ -303,6 +373,21 @@ function readMigrationCollection(packageName, root) {
         collectionPath,
     };
 }
+// Workspace-relative because the agent runs with cwd at the workspace root;
+// absolute only for layouts that resolve outside it (hoisted/symlinked).
+function resolveDocumentationFileToWorkspacePath(root, migrationsDir, documentation) {
+    let documentationFile;
+    try {
+        documentationFile = require.resolve(documentation, {
+            paths: [migrationsDir],
+        });
+    }
+    catch {
+        return undefined;
+    }
+    const relativePath = (0, path_1.relative)(root, documentationFile);
+    return relativePath.startsWith('..') ? documentationFile : relativePath;
+}
 function getImplementationPath(collection, collectionPath, name, migrationVersion) {
     const g = collection.generators?.[name] || collection.schematics?.[name];
     if (!g) {

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

@@ -67,5 +67,40 @@ export declare function reportMigrateRunError(opts: {
     migrationCount?: number;
     error?: unknown;
 }): void;
+export declare function reportMigrateOrchestratorInit(opts: {
+    migrationCount: number;
+    createCommits: boolean;
+}): void;
+/**
+ * One event per orchestrator dispense. The `action` (dispense case) is a
+ * closed enum carried on a reused dimension, read conditioned on the event
+ * name (the same multiplexing pattern as {@link reportMigratePrompt});
+ * `attempt` rides the migration-count dimension.
+ */
+export declare function reportMigrateOrchestratorDispense(opts: {
+    action: string;
+    attempt: number;
+}): void;
+/**
+ * Terminal funnel event. The two step tallies and the total dispense count
+ * ride reused numeric dimensions, read conditioned on the event name.
+ */
+export declare function reportMigrateOrchestratorComplete(opts: {
+    completed: number;
+    skipped: number;
+    dispenseCount: number;
+}): void;
+/**
+ * Counts invocations, not completions: emitted as soon as the migration id
+ * resolves, while the worker can still stop before running anything.
+ *
+ * An invocation recorded into an orchestrated run (`--run-id`) gets its own
+ * event name. Every other one keeps the name `--run-migration` shipped with,
+ * so that series stays continuous for users who never enable the orchestrator.
+ */
+export declare function reportMigrateSingleMigrationInvocation(opts: {
+    migrationType: 'generator' | 'prompt' | 'hybrid';
+    orchestrated: boolean;
+}): void;
 export declare function computeMajorsCrossed(installed: string | null | undefined, target: string | null | undefined): number | undefined;
 export declare function safeReport(emit: () => void): void;

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

@@ -11,6 +11,10 @@ exports.reportMigrateRunStart = reportMigrateRunStart;
 exports.hasMigrateRunStarted = hasMigrateRunStarted;
 exports.reportMigrateRunComplete = reportMigrateRunComplete;
 exports.reportMigrateRunError = reportMigrateRunError;
+exports.reportMigrateOrchestratorInit = reportMigrateOrchestratorInit;
+exports.reportMigrateOrchestratorDispense = reportMigrateOrchestratorDispense;
+exports.reportMigrateOrchestratorComplete = reportMigrateOrchestratorComplete;
+exports.reportMigrateSingleMigrationInvocation = reportMigrateSingleMigrationInvocation;
 exports.computeMajorsCrossed = computeMajorsCrossed;
 exports.safeReport = safeReport;
 const semver_1 = require("semver");
@@ -180,6 +184,66 @@ function reportMigrateRunError(opts) {
         });
     });
 }
+function reportMigrateOrchestratorInit(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_orchestrator_init', {
+            [analytics_1.customDimensions.createCommits]: opts.createCommits,
+            [analytics_1.customDimensions.migrationCount]: opts.migrationCount,
+        });
+    });
+}
+/**
+ * One event per orchestrator dispense. The `action` (dispense case) is a
+ * closed enum carried on a reused dimension, read conditioned on the event
+ * name (the same multiplexing pattern as {@link reportMigratePrompt});
+ * `attempt` rides the migration-count dimension.
+ */
+function reportMigrateOrchestratorDispense(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_orchestrator_dispense', {
+            [analytics_1.customDimensions.promptChoice]: opts.action,
+            [analytics_1.customDimensions.migrationCount]: opts.attempt,
+        });
+    });
+}
+/**
+ * Terminal funnel event. The two step tallies and the total dispense count
+ * ride reused numeric dimensions, read conditioned on the event name.
+ */
+function reportMigrateOrchestratorComplete(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)('migrate_orchestrator_complete', {
+            [analytics_1.customDimensions.appliedCount]: opts.completed,
+            [analytics_1.customDimensions.taskCount]: opts.skipped,
+            [analytics_1.customDimensions.migrationCount]: opts.dispenseCount,
+        });
+    });
+}
+/**
+ * Counts invocations, not completions: emitted as soon as the migration id
+ * resolves, while the worker can still stop before running anything.
+ *
+ * An invocation recorded into an orchestrated run (`--run-id`) gets its own
+ * event name. Every other one keeps the name `--run-migration` shipped with,
+ * so that series stays continuous for users who never enable the orchestrator.
+ */
+function reportMigrateSingleMigrationInvocation(opts) {
+    safeReport(() => {
+        if (!analytics_1.customDimensions)
+            return;
+        (0, analytics_1.reportEvent)(opts.orchestrated
+            ? 'migrate_single_migration_recorded'
+            : 'migrate_single_migration_invocation', {
+            [analytics_1.customDimensions.promptChoice]: opts.migrationType,
+        });
+    });
+}
 // `_migrate` runs either from a temp install of the latest CLI or from the
 // workspace-local installation; same signal as the run-phase re-dispatch
 // check in migrate.ts.