@unbrained/pm-cli 2026.7.1 → 2026.7.3

package/dist/cli/main.js

@@ -5,7 +5,7 @@
  * Provides CLI runtime support for Main.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9f13a662-73c4-5ffa-99bc-4edee2b7a7fb")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="aa682568-77f6-5659-a6dd-3a69dd4e1fc0")}catch(e){}}();
 import { Command } from "commander";
 import { activateExtensions, clearActiveExtensionHooks, createEmptyExtensionRegistrationRegistry, discoverExtensions, getActiveCommandResult, getActiveExtensionRegistrations, loadExtensions, consumeAfterCommandAffectedItems, runActiveCommandHandler, runActiveParserOverride, runActivePreflightOverride, runAfterCommandHooks, runBeforeCommandHooks, setActiveCommandResult, setActiveCommandContext, setActiveExtensionCommands, setActiveExtensionHooks, setActiveExtensionParsers, setActiveExtensionPreflight, setActiveExtensionRegistrations, setActiveExtensionRenderers, setActiveExtensionServices, } from "../core/extensions/index.js";
 import { pathExists } from "../core/fs/fs-utils.js";
@@ -132,6 +132,59 @@ function inferMissingFieldsFromErrorMessage(message) {
     /* c8 ignore next */
     return normalized.length > 0 ? normalized : undefined;
 }
+function inferMissingFieldsForRecovery(rawMessage, invocationArgv, existingRecovery) {
+    if (existingRecovery?.suggested_retry) {
+        return undefined;
+    }
+    const providedFields = extractProvidedOptionFlags(invocationArgv);
+    const providedSet = new Set(providedFields.map((flag) => normalizeLongOptionFlag(flag) ?? flag));
+    const rawInferred = inferMissingFieldsFromErrorMessage(rawMessage);
+    const trulyMissing = rawInferred?.filter((flag) => !providedSet.has(normalizeLongOptionFlag(flag) ?? flag));
+    return trulyMissing && trulyMissing.length > 0 ? trulyMissing : undefined;
+}
+function resolveRecoverySuggestedRetry(invocationArgv, attemptedCommand, inferredMissing, existingRecovery) {
+    if (existingRecovery?.suggested_retry) {
+        return existingRecovery.suggested_retry;
+    }
+    const missingFlag = inferredMissing?.[0];
+    const normalizedMissing = missingFlag ? normalizeLongOptionFlag(missingFlag) : undefined;
+    const suggestedRetry = normalizedMissing
+        ? renderAttemptedCommand([...invocationArgv, normalizedMissing, "<value>"])
+        : attemptedCommand;
+    return suggestedRetry === attemptedCommand ? undefined : suggestedRetry;
+}
+function projectExistingRecoveryOptionalFields(existingRecovery) {
+    if (!existingRecovery) {
+        return {};
+    }
+    const optionalFields = [
+        "recovery_mode",
+        "missing_required_fields",
+        "suggested_flags",
+        "fallback_candidates",
+        "next_best_command",
+    ];
+    const projected = {};
+    for (const field of optionalFields) {
+        const value = existingRecovery[field];
+        if (value !== undefined && value !== null) {
+            projected[field] = value;
+        }
+    }
+    return projected;
+}
+function buildRecoveryPayload(params) {
+    const existingRecovery = params.existingRecovery;
+    return {
+        attempted_command: existingRecovery?.attempted_command ?? params.attemptedCommand,
+        normalized_args: existingRecovery?.normalized_args ?? [...params.invocationArgv],
+        /* c8 ignore next */
+        provided_fields: existingRecovery?.provided_fields ?? (params.providedFields.length > 0 ? params.providedFields : undefined),
+        missing: existingRecovery?.missing ?? params.inferredMissing,
+        ...projectExistingRecoveryOptionalFields(existingRecovery),
+        ...(params.suggestedRetry ? { suggested_retry: params.suggestedRetry } : {}),
+    };
+}
 function buildPmCliRecoveryContext(context, invocationArgv, rawMessage) {
     const explainRequested = invocationArgv.includes("--explain");
     const existingRecovery = context?.recovery;
@@ -144,40 +197,16 @@ function buildPmCliRecoveryContext(context, invocationArgv, rawMessage) {
     }
     const attemptedCommand = renderAttemptedCommand(invocationArgv);
     const providedFields = extractProvidedOptionFlags(invocationArgv);
-    /* c8 ignore next */
-    const providedSet = new Set(providedFields.map((flag) => normalizeLongOptionFlag(flag) ?? flag));
-    const rawInferred = existingRecovery?.suggested_retry ? undefined : inferMissingFieldsFromErrorMessage(rawMessage);
-    /* c8 ignore next */
-    const trulyMissing = rawInferred?.filter((flag) => !providedSet.has(normalizeLongOptionFlag(flag) ?? flag));
-    const inferredMissing = trulyMissing && trulyMissing.length > 0 ? trulyMissing : undefined;
-    let suggestedRetry = existingRecovery?.suggested_retry;
-    if (!suggestedRetry && inferredMissing && inferredMissing.length > 0) {
-        const missingFlag = inferredMissing[0];
-        const normalizedMissing = normalizeLongOptionFlag(missingFlag);
-        /* c8 ignore next */
-        if (normalizedMissing) {
-            suggestedRetry = renderAttemptedCommand([...invocationArgv, normalizedMissing, "<value>"]);
-        }
-    }
-    if (!suggestedRetry) {
-        suggestedRetry = attemptedCommand;
-    }
-    if (!existingRecovery?.suggested_retry && suggestedRetry === attemptedCommand) {
-        suggestedRetry = undefined;
-    }
-    const recovery = {
-        attempted_command: existingRecovery?.attempted_command ?? attemptedCommand,
-        normalized_args: existingRecovery?.normalized_args ?? [...invocationArgv],
-        /* c8 ignore next */
-        provided_fields: existingRecovery?.provided_fields ?? (providedFields.length > 0 ? providedFields : undefined),
-        missing: existingRecovery?.missing ?? inferredMissing,
-        ...(existingRecovery?.recovery_mode ? { recovery_mode: existingRecovery.recovery_mode } : {}),
-        ...(existingRecovery?.missing_required_fields ? { missing_required_fields: existingRecovery.missing_required_fields } : {}),
-        ...(existingRecovery?.suggested_flags ? { suggested_flags: existingRecovery.suggested_flags } : {}),
-        ...(suggestedRetry ? { suggested_retry: suggestedRetry } : {}),
-        ...(existingRecovery?.fallback_candidates ? { fallback_candidates: existingRecovery.fallback_candidates } : {}),
-        ...(existingRecovery?.next_best_command ? { next_best_command: existingRecovery.next_best_command } : {}),
-    };
+    const inferredMissing = inferMissingFieldsForRecovery(rawMessage, invocationArgv, existingRecovery);
+    const suggestedRetry = resolveRecoverySuggestedRetry(invocationArgv, attemptedCommand, inferredMissing, existingRecovery);
+    const recovery = buildRecoveryPayload({
+        invocationArgv,
+        attemptedCommand,
+        providedFields,
+        inferredMissing,
+        suggestedRetry,
+        existingRecovery,
+    });
     return {
         ...context,
         recovery,
@@ -536,8 +565,11 @@ function collectExtensionFlagDefinitionsForInvocation(registrations, commandPath
     }
     return nestedMatch.length > 0 ? nestedMatch : exact;
 }
+function dynamicCommandArguments(descriptor) {
+    return descriptor.arguments ?? [];
+}
 function formatDynamicCommandUsage(descriptor) {
-    const argumentSuffix = descriptor.arguments
+    const argumentSuffix = dynamicCommandArguments(descriptor)
         .map((argument) => {
         const label = argument.variadic ? `${argument.name}...` : argument.name;
         return argument.required ? `<${label}>` : `[${label}]`;
@@ -562,10 +594,12 @@ function isImporterOrExporterCommandPath(registrations, commandPath) {
         registrations.exporters.some((entry) => normalizeExtensionCommandPath(`${entry.exporter} export`) === normalized));
 }
 function validateDynamicExtensionCommandArgs(descriptor, args) {
-    const requiredCount = descriptor.arguments.filter((argument) => argument.required).length;
-    const variadic = descriptor.arguments.some((argument) => argument.variadic);
-    const maxCount = variadic ? Number.POSITIVE_INFINITY : descriptor.arguments.length;
-    const hintSuffix = descriptor.failure_hints.length > 0 ? ` ${descriptor.failure_hints.join(" ")}` : "";
+    const descriptorArguments = dynamicCommandArguments(descriptor);
+    const requiredCount = descriptorArguments.filter((argument) => argument.required).length;
+    const variadic = descriptorArguments.some((argument) => argument.variadic);
+    const maxCount = variadic ? Number.POSITIVE_INFINITY : descriptorArguments.length;
+    const failureHints = descriptor.failure_hints ?? [];
+    const hintSuffix = failureHints.length > 0 ? ` ${failureHints.join(" ")}` : "";
     if (args.length < requiredCount) {
         throw new PmCliError(`Missing required argument for extension command '${descriptor.command}'. Usage: ${formatDynamicCommandUsage(descriptor)}${hintSuffix}`, EXIT_CODE.USAGE);
     }
@@ -1210,15 +1244,44 @@ async function runRequiredExtensionCommand(command, options, globalOptions, exte
     return extensionCommandResult.result;
 }
 const WRAPPED_ACTION_HANDLER = Symbol("pm.wrappedActionHandler");
+function resolveActionCommand(actionArgs, fallback) {
+    const possibleCommand = actionArgs[actionArgs.length - 1];
+    /* c8 ignore next */
+    return possibleCommand instanceof Command ? possibleCommand : fallback;
+}
+function maybePrintExtensionProfileWarnings(enabled, label, warnings) {
+    if (enabled && warnings.length > 0) {
+        printError(`profile:extensions ${label}=${formatHookWarnings(warnings)}`);
+    }
+}
+function validateDynamicInvocationArgs(params) {
+    const dynamicDescriptor = activeRuntimeExtensionCommandDescriptors.get(normalizeExtensionCommandPath(params.commandPath));
+    if (!dynamicDescriptor || !isImporterOrExporterCommandPath(params.activeRegistrations, params.commandPath)) {
+        return;
+    }
+    const positionalArgs = dynamicCommandArguments(dynamicDescriptor).length === 0
+        ? collectLoosePositionalArgs(params.commandArgs)
+        : stripLooseCommandOptionTokens(params.commandArgs, params.extensionFlagDefinitions);
+    validateDynamicExtensionCommandArgs(dynamicDescriptor, positionalArgs);
+}
+function syncCommanderActionArgs(actionCommand, actionArgs, commandArgs) {
+    actionCommand.args = [...commandArgs];
+    /* c8 ignore next */
+    if ("_processArguments" in actionCommand && typeof actionCommand._processArguments === "function") {
+        actionCommand._processArguments();
+    }
+    /* c8 ignore next */
+    if (actionArgs.length > 0 && Array.isArray(actionArgs[0])) {
+        actionArgs[0] = [...actionCommand.processedArgs];
+    }
+}
 function wrapProgramActionsForExtensionHandlers(rootProgram) {
     const visit = (entry) => {
         const actionEntry = entry;
         if (typeof actionEntry._actionHandler === "function" && actionEntry[WRAPPED_ACTION_HANDLER] !== true) {
             const originalAction = actionEntry._actionHandler;
             actionEntry._actionHandler = async function wrappedActionHandler(...actionArgs) {
-                const possibleCommand = actionArgs[actionArgs.length - 1];
-                /* c8 ignore next */
-                const actionCommand = possibleCommand instanceof Command ? possibleCommand : entry;
+                const actionCommand = resolveActionCommand(actionArgs, entry);
                 const startedAt = Date.now();
                 clearResolvedGlobalOptions(actionCommand);
                 let globalOptions = getGlobalOptions(actionCommand);
@@ -1241,9 +1304,7 @@ function wrapProgramActionsForExtensionHandlers(rootProgram) {
                     global: globalOptions,
                     pm_root: pmRoot,
                 });
-                if (globalOptions.profile && parserOverride.warnings.length > 0) {
-                    printError(`profile:extensions parser_warnings=${formatHookWarnings(parserOverride.warnings)}`);
-                }
+                maybePrintExtensionProfileWarnings(globalOptions.profile, "parser_warnings", parserOverride.warnings);
                 commandArgs = parserOverride.context.args;
                 commandOptions = parserOverride.context.options;
                 globalOptions = parserOverride.context.global;
@@ -1252,24 +1313,10 @@ function wrapProgramActionsForExtensionHandlers(rootProgram) {
                 // only arity validation, so excess positionals could reach handlers.
                 // Free-form `registerCommand` commands intentionally accept positionals
                 // via context.args, and core commands have no descriptor.
-                const dynamicDescriptor = activeRuntimeExtensionCommandDescriptors.get(normalizeExtensionCommandPath(commandPath));
-                if (dynamicDescriptor && isImporterOrExporterCommandPath(activeRegistrations, commandPath)) {
-                    const positionalArgs = dynamicDescriptor.arguments.length === 0
-                        ? collectLoosePositionalArgs(commandArgs)
-                        : stripLooseCommandOptionTokens(commandArgs, extensionFlagDefinitions);
-                    validateDynamicExtensionCommandArgs(dynamicDescriptor, positionalArgs);
-                }
+                validateDynamicInvocationArgs({ activeRegistrations, commandPath, commandArgs, extensionFlagDefinitions });
                 globalOptions = await applyDefaultOutputFormat(globalOptions);
                 setResolvedGlobalOptions(actionCommand, globalOptions);
-                actionCommand.args = [...commandArgs];
-                /* c8 ignore next */
-                if ("_processArguments" in actionCommand && typeof actionCommand._processArguments === "function") {
-                    actionCommand._processArguments();
-                }
-                /* c8 ignore next */
-                if (actionArgs.length > 0 && Array.isArray(actionArgs[0])) {
-                    actionArgs[0] = [...actionCommand.processedArgs];
-                }
+                syncCommanderActionArgs(actionCommand, actionArgs, commandArgs);
                 for (const [key, value] of Object.entries(commandOptions)) {
                     actionCommand.setOptionValueWithSource(key, value, "cli");
                 }
@@ -1288,9 +1335,7 @@ function wrapProgramActionsForExtensionHandlers(rootProgram) {
                     global: globalOptions,
                     pm_root: pmRoot,
                 });
-                if (globalOptions.profile && extensionCommandResult.warnings.length > 0) {
-                    printError(`profile:extensions command_handler_warnings=${formatHookWarnings(extensionCommandResult.warnings)}`);
-                }
+                maybePrintExtensionProfileWarnings(globalOptions.profile, "command_handler_warnings", extensionCommandResult.warnings);
                 if (extensionCommandResult.handled) {
                     setActiveCommandResult(extensionCommandResult.result);
                     printResult(extensionCommandResult.result, {
@@ -1316,36 +1361,67 @@ function wrapProgramActionsForExtensionHandlers(rootProgram) {
     visit(rootProgram);
 }
 /* c8 ignore stop */
+async function clearDynamicExtensionCommandState(params) {
+    activeRuntimeExtensionCommandDescriptors = new Map();
+    setActiveExtensionServices({ overrides: [] });
+    if (params) {
+        await maybeAttachCreateUpdatePolicyHelpText(params.rootProgram, params.pmRoot, params.invocationArgv, createEmptyExtensionRegistrationRegistry(), params.settings);
+    }
+}
+/* v8 ignore start -- dynamic help fallback variants are exercised through registration integration tests; residual legacy branches are defensive */
+function attachDynamicExtensionHelp(command, descriptor, flagHelp, metadataHelp) {
+    if (descriptor?.flags && descriptor.flags.length > 0) {
+        applyDynamicExtensionFlagOptions(command, descriptor.flags);
+        const residualFlagHelp = buildResidualDynamicExtensionFlagHelp(command, descriptor.flags);
+        if (residualFlagHelp) {
+            command.addHelpText("after", residualFlagHelp);
+        }
+    }
+    else if (flagHelp) {
+        command.addHelpText("after", flagHelp);
+    }
+    if (metadataHelp) {
+        command.addHelpText("after", metadataHelp);
+    }
+}
+/* v8 ignore stop */
 /* c8 ignore start */
 async function registerDynamicExtensionCommandPaths(rootProgram, invocationArgv) {
     const bootstrapGlobalOptions = parseBootstrapGlobalOptions(invocationArgv);
     const pmRoot = resolvePmRoot(process.cwd(), bootstrapGlobalOptions.path);
     if (bootstrapGlobalOptions.noExtensions) {
-        activeRuntimeExtensionCommandDescriptors = new Map();
-        setActiveExtensionServices({ overrides: [] });
-        await maybeAttachCreateUpdatePolicyHelpText(rootProgram, pmRoot, invocationArgv, createEmptyExtensionRegistrationRegistry());
+        await clearDynamicExtensionCommandState({
+            rootProgram,
+            pmRoot,
+            invocationArgv,
+        });
         return;
     }
     const discoverySnapshot = await loadRuntimeExtensionDiscoverySnapshot(pmRoot);
     const probe = buildBootstrapActivationProbe(invocationArgv);
     if (!discoverySnapshot) {
-        activeRuntimeExtensionCommandDescriptors = new Map();
-        setActiveExtensionServices({ overrides: [] });
+        await clearDynamicExtensionCommandState();
         return;
     }
     if (!discoveryNeedsActivationForProbe(discoverySnapshot.discovery, probe)) {
-        activeRuntimeExtensionCommandDescriptors = new Map();
-        setActiveExtensionServices({ overrides: [] });
-        await maybeAttachCreateUpdatePolicyHelpText(rootProgram, pmRoot, invocationArgv, createEmptyExtensionRegistrationRegistry(), discoverySnapshot.settings);
+        await clearDynamicExtensionCommandState({
+            rootProgram,
+            pmRoot,
+            invocationArgv,
+            settings: discoverySnapshot.settings,
+        });
         emitExtensionSkippedProfile(bootstrapProfileEnabled(invocationArgv), discoverySnapshot, probe);
         return;
     }
     const snapshot = await loadRuntimeExtensionSnapshot(pmRoot);
     /* c8 ignore next */
     if (!snapshot) {
-        activeRuntimeExtensionCommandDescriptors = new Map();
-        setActiveExtensionServices({ overrides: [] });
-        await maybeAttachCreateUpdatePolicyHelpText(rootProgram, pmRoot, invocationArgv, createEmptyExtensionRegistrationRegistry(), discoverySnapshot.settings);
+        await clearDynamicExtensionCommandState({
+            rootProgram,
+            pmRoot,
+            invocationArgv,
+            settings: discoverySnapshot.settings,
+        });
         return;
     }
     // Ensure usage/help/error formatting overrides are available even when parse
@@ -1364,20 +1440,7 @@ async function registerDynamicExtensionCommandPaths(rootProgram, invocationArgv)
         const flagHelp = snapshot.commandFlagHelp.get(commandPath);
         const metadataHelp = descriptor ? buildDynamicExtensionCommandMetadataHelp(descriptor) : null;
         if (existingCommand) {
-            if (descriptor?.flags && descriptor.flags.length > 0) {
-                applyDynamicExtensionFlagOptions(existingCommand, descriptor.flags);
-                const residualFlagHelp = buildResidualDynamicExtensionFlagHelp(existingCommand, descriptor.flags);
-                if (residualFlagHelp) {
-                    existingCommand.addHelpText("after", residualFlagHelp);
-                }
-            }
-            else if (flagHelp) {
-                existingCommand.addHelpText("after", flagHelp);
-            }
-            /* c8 ignore next */
-            if (metadataHelp) {
-                existingCommand.addHelpText("after", metadataHelp);
-            }
+            attachDynamicExtensionHelp(existingCommand, descriptor, flagHelp, metadataHelp);
             continue;
         }
         const dynamicCommand = ensureCommandPath(rootProgram, pathParts);
@@ -1861,6 +1924,315 @@ function enforceExplicitRetryForFlagTypos(bootstrapInvocation) {
         },
     });
 }
+function createTelemetryCommandErrorEmitter(params) {
+    return async (event) => {
+        const errorCategory = resolveTelemetryErrorCategory(event.errorCode);
+        const commandResolution = deriveTelemetryCommandResolution({
+            ok: false,
+            errorCode: event.errorCode,
+            errorCategory,
+        });
+        await emitTelemetryErrorEvent({
+            command: event.command,
+            args: params.invocationArgv,
+            options: event.options,
+            global: params.bootstrapGlobal,
+            pm_version: CLI_VERSION,
+            pm_root: params.bootstrapPmRoot,
+            error_code: event.errorCode,
+            error_message: event.errorMessage,
+            exit_code: event.exitCode,
+            error_category: errorCategory,
+            command_resolution: commandResolution,
+            resolution_stage: event.resolutionStage,
+        });
+        return {
+            errorCategory,
+            commandResolution,
+        };
+    };
+}
+async function prepareExtensionServicesForRunPmCliError(params) {
+    if (params.bootstrapGlobal.noExtensions) {
+        return;
+    }
+    const bootstrapProbe = buildBootstrapActivationProbe(params.invocationArgv);
+    const discoverySnapshot = await loadRuntimeExtensionDiscoverySnapshot(params.bootstrapPmRoot);
+    if (discoverySnapshot && discoveryNeedsActivationForProbe(discoverySnapshot.discovery, bootstrapProbe)) {
+        const bootstrapSnapshot = await loadRuntimeExtensionSnapshot(params.bootstrapPmRoot);
+        setRecoveredExtensionServices(bootstrapSnapshot);
+        return;
+    }
+    if (discoverySnapshot) {
+        emitExtensionSkippedProfile(bootstrapProfileEnabled(params.invocationArgv), discoverySnapshot, bootstrapProbe);
+    }
+    setActiveExtensionServices({ overrides: [] });
+}
+function setRecoveredExtensionServices(bootstrapSnapshot) {
+    if (!bootstrapSnapshot) {
+        setActiveExtensionServices({ overrides: [] });
+        return;
+    }
+    setActiveExtensionServices(bootstrapSnapshot.services);
+}
+async function finishRunPmCliFailure(params) {
+    sentryFinishCommandSpan(false, params.errorMessage, {
+        error_code: params.classificationCode,
+        error_category: params.errorCategory,
+        exit_code: params.exitCode,
+        command_resolution: params.commandResolution,
+        resolution_stage: params.resolutionStage,
+    });
+    await runAndClearAfterCommandHooks({
+        ok: false,
+        error: params.errorMessage,
+        exit_code: params.exitCode,
+        error_code: params.classificationCode,
+        error_category: params.errorCategory,
+        command_resolution: params.commandResolution,
+        resolution_stage: params.resolutionStage,
+    });
+}
+async function finishRunPmCliSuccessParse() {
+    sentryFinishCommandSpan(true, undefined, {
+        exit_code: EXIT_CODE.SUCCESS,
+        command_resolution: "success",
+        resolution_stage: "parse",
+    });
+    await runAndClearAfterCommandHooks({
+        ok: true,
+        exit_code: EXIT_CODE.SUCCESS,
+        command_resolution: "success",
+        resolution_stage: "parse",
+    });
+    process.exitCode = EXIT_CODE.SUCCESS;
+}
+async function handleRunPmCliKnownError(context, numericExitCode) {
+    const hasExplicitExitCode = typeof numericExitCode === "number" && Number.isFinite(numericExitCode);
+    if (!(context.error instanceof PmCliError) &&
+        (isCommanderError(context.error) || !hasExplicitExitCode)) {
+        return false;
+    }
+    const errorMessage = describeUnknownError(context.error);
+    const exitCode = context.error instanceof PmCliError ? context.error.exitCode : normalizeThrownExitCode(numericExitCode);
+    const rawContext = context.error instanceof PmCliError ? context.error.context : undefined;
+    const enrichedContext = buildPmCliRecoveryContext(rawContext, context.invocationArgv, errorMessage);
+    const classification = classifyPmCliError(errorMessage, enrichedContext);
+    const renderedError = context.jsonErrors
+        ? JSON.stringify(formatPmCliErrorForJson(errorMessage, exitCode, enrichedContext), null, 2)
+        : formatPmCliErrorForDisplay(errorMessage, enrichedContext);
+    printError(renderedError);
+    const { errorCategory, commandResolution } = await context.emitTelemetryCommandError({
+        command: context.attemptedCommand,
+        errorCode: classification.code,
+        errorMessage: classification.detail,
+        exitCode,
+        options: {
+            bootstrap_global_options: context.bootstrapGlobal,
+        },
+        resolutionStage: "execute",
+    });
+    const loggedHandledErrorToSentry = await maybeLogHandledCliErrorToSentry({
+        command: context.attemptedCommand,
+        error_code: classification.code,
+        error_category: errorCategory,
+        exit_code: exitCode,
+        error_message: classification.detail,
+        command_resolution: commandResolution,
+        resolution_stage: "execute",
+        source_context: activeTelemetryCommandContext?.source_context,
+    });
+    await finishRunPmCliFailure({
+        errorMessage,
+        exitCode,
+        classificationCode: classification.code,
+        errorCategory,
+        commandResolution,
+        resolutionStage: "execute",
+    });
+    if (loggedHandledErrorToSentry) {
+        sentryCaptureCliError(wrapThrownErrorForSentry(context.error, errorMessage));
+        await sentryFlush(HANDLED_ERROR_SENTRY_FLUSH_TIMEOUT_MS);
+    }
+    process.exitCode = exitCode;
+    return true;
+}
+function resolveUnknownHelpToken(invocationArgv) {
+    const helpRequest = parseBootstrapHelpRequest(invocationArgv);
+    return helpRequest.commandPathTokens[0] ?? parseBootstrapCommandName(invocationArgv) ?? "<command>";
+}
+async function handleUnknownHelpCommandError(context, code) {
+    const unknownToken = resolveUnknownHelpToken(context.invocationArgv);
+    const unknownMessage = `unknown command '${unknownToken}'`;
+    const recoveryCommandDescriptors = await loadRuntimeExtensionCommandDescriptorsForRecovery(resolvePmRoot(process.cwd(), context.bootstrapGlobal.path));
+    const usageContext = await resolveCommanderUsageContext({ message: unknownMessage }, program, recoveryCommandDescriptors);
+    const classification = classifyCommanderError(usageContext.message, usageContext.commandName, usageContext.allowedTypes, {
+        unknownCommandExamples: usageContext.unknownCommandExamples,
+        unknownCommandNextSteps: usageContext.unknownCommandNextSteps,
+        attemptedCommand: usageContext.attemptedCommand,
+        normalizedInvocationArgs: usageContext.normalizedInvocationArgs,
+        providedOptionFlags: usageContext.providedOptionFlags,
+        unknownOptionSuggestions: usageContext.unknownOptionSuggestions,
+        suggestedRetryCommand: usageContext.suggestedRetryCommand,
+    });
+    const { errorCategory, commandResolution } = await context.emitTelemetryCommandError({
+        command: unknownToken,
+        errorCode: classification.code,
+        errorMessage: classification.detail,
+        exitCode: EXIT_CODE.USAGE,
+        options: {
+            bootstrap_global_options: context.bootstrapGlobal,
+            commander_code: code ?? "commander.helpDisplayed",
+        },
+        resolutionStage: "parse",
+    });
+    const loggedHandledErrorToSentry = await maybeLogHandledCliErrorToSentry({
+        command: unknownToken,
+        error_code: classification.code,
+        error_category: errorCategory,
+        exit_code: EXIT_CODE.USAGE,
+        error_message: classification.detail,
+        command_resolution: commandResolution,
+        resolution_stage: "parse",
+        source_context: activeTelemetryCommandContext?.source_context,
+    });
+    const renderedUsage = context.jsonErrors
+        ? await formatCommanderUsageJson({ message: unknownMessage }, program, recoveryCommandDescriptors)
+        : await formatCommanderUsageMessage({ message: unknownMessage }, program, recoveryCommandDescriptors);
+    await finishRunPmCliFailure({
+        errorMessage: unknownMessage,
+        exitCode: EXIT_CODE.USAGE,
+        classificationCode: classification.code,
+        errorCategory,
+        commandResolution,
+        resolutionStage: "parse",
+    });
+    printError(renderedUsage);
+    if (loggedHandledErrorToSentry) {
+        await sentryFlush(HANDLED_ERROR_SENTRY_FLUSH_TIMEOUT_MS);
+    }
+    process.exitCode = EXIT_CODE.USAGE;
+}
+async function handleRunPmCliHelpDisplayError(context, code, rawMessage) {
+    const isHelpDisplayCode = code === "commander.helpDisplayed" || code === "commander.help" || code === "commander.helpCommand";
+    if (!isHelpDisplayCode && !rawMessage.includes("(outputHelp)")) {
+        return false;
+    }
+    const helpRequest = parseBootstrapHelpRequest(context.invocationArgv);
+    if (helpRequest.requested && !isKnownHelpCommandPath(program, helpRequest.commandPathTokens)) {
+        await handleUnknownHelpCommandError(context, code);
+        return true;
+    }
+    await finishRunPmCliSuccessParse();
+    return true;
+}
+async function handleRunPmCliCommanderUsageError(context, code) {
+    const usageContext = await resolveCommanderUsageContext(context.error, program, activeRuntimeExtensionCommandDescriptors);
+    const classification = classifyCommanderError(usageContext.message, usageContext.commandName, usageContext.allowedTypes, {
+        unknownCommandExamples: usageContext.unknownCommandExamples,
+        unknownCommandNextSteps: usageContext.unknownCommandNextSteps,
+        attemptedCommand: usageContext.attemptedCommand,
+        normalizedInvocationArgs: usageContext.normalizedInvocationArgs,
+        providedOptionFlags: usageContext.providedOptionFlags,
+        unknownOptionSuggestions: usageContext.unknownOptionSuggestions,
+        suggestedRetryCommand: usageContext.suggestedRetryCommand,
+    });
+    const { errorCategory, commandResolution } = await context.emitTelemetryCommandError({
+        command: context.attemptedCommand,
+        errorCode: classification.code,
+        errorMessage: classification.detail,
+        exitCode: EXIT_CODE.USAGE,
+        options: {
+            bootstrap_global_options: context.bootstrapGlobal,
+            commander_code: code,
+        },
+        resolutionStage: "parse",
+    });
+    const loggedHandledErrorToSentry = await maybeLogHandledCliErrorToSentry({
+        command: context.attemptedCommand,
+        error_code: classification.code,
+        error_category: errorCategory,
+        exit_code: EXIT_CODE.USAGE,
+        error_message: classification.detail,
+        command_resolution: commandResolution,
+        resolution_stage: "parse",
+        source_context: activeTelemetryCommandContext?.source_context,
+    });
+    const renderedUsage = context.jsonErrors
+        ? await formatCommanderUsageJson(context.error, program, activeRuntimeExtensionCommandDescriptors)
+        : await formatCommanderUsageMessage(context.error, program, activeRuntimeExtensionCommandDescriptors);
+    await finishRunPmCliFailure({
+        errorMessage: usageContext.message,
+        exitCode: EXIT_CODE.USAGE,
+        classificationCode: classification.code,
+        errorCategory,
+        commandResolution,
+        resolutionStage: "parse",
+    });
+    printError(renderedUsage);
+    if (loggedHandledErrorToSentry) {
+        await sentryFlush(HANDLED_ERROR_SENTRY_FLUSH_TIMEOUT_MS);
+    }
+    process.exitCode = EXIT_CODE.USAGE;
+}
+function shouldHandleRunPmCliCommanderError(error) {
+    if (typeof error !== "object" || error === null || !("code" in error)) {
+        return false;
+    }
+    const code = error.code;
+    if (typeof code === "string" && (code === "commander.version" || code.startsWith("commander."))) {
+        return true;
+    }
+    const rawMessage = String(error.message ?? "");
+    return rawMessage.includes("(outputHelp)");
+}
+async function handleRunPmCliCommanderError(context) {
+    const code = context.error.code;
+    const rawMessage = String(context.error.message ?? "");
+    if (await handleRunPmCliHelpDisplayError(context, code, rawMessage)) {
+        return;
+    }
+    if (code === "commander.version") {
+        await finishRunPmCliSuccessParse();
+        return;
+    }
+    await handleRunPmCliCommanderUsageError(context, code);
+}
+async function handleRunPmCliError(params) {
+    const bootstrapGlobal = parseBootstrapGlobalOptions(params.invocationArgv);
+    const bootstrapPmRoot = resolvePmRoot(process.cwd(), bootstrapGlobal.path);
+    const context = {
+        error: params.error,
+        invocationArgv: params.invocationArgv,
+        bootstrapGlobal,
+        jsonErrors: bootstrapGlobal.json,
+        bootstrapPmRoot,
+        attemptedCommand: parseBootstrapCommandName(params.invocationArgv) ?? "<unknown>",
+        emitTelemetryCommandError: createTelemetryCommandErrorEmitter({
+            invocationArgv: params.invocationArgv,
+            bootstrapGlobal,
+            bootstrapPmRoot,
+        }),
+    };
+    await prepareExtensionServicesForRunPmCliError({
+        invocationArgv: params.invocationArgv,
+        bootstrapGlobal,
+        bootstrapPmRoot,
+    });
+    if (await handleRunPmCliKnownError(context, readThrownExitCode(params.error))) {
+        return;
+    }
+    if (shouldHandleRunPmCliCommanderError(params.error)) {
+        await handleRunPmCliCommanderError(context);
+        return;
+    }
+    await handleGenericRunPmCliError({
+        error: params.error,
+        attemptedCommand: context.attemptedCommand,
+        bootstrapGlobal,
+        emitTelemetryCommandError: context.emitTelemetryCommandError,
+    });
+}
 /**
  * Implements run pm cli for the public runtime surface of this module.
  */
@@ -1900,286 +2272,7 @@ export async function runPmCli(rawArgv = process.argv.slice(2)) {
         await program.parseAsync(invocationProcessArgv);
     }
     catch (error) {
-        /* c8 ignore start */
-        const bootstrapGlobal = parseBootstrapGlobalOptions(invocationArgv);
-        const jsonErrors = bootstrapGlobal.json;
-        const bootstrapPmRoot = resolvePmRoot(process.cwd(), bootstrapGlobal.path);
-        const attemptedCommand = parseBootstrapCommandName(invocationArgv) ?? "<unknown>";
-        const emitTelemetryCommandError = async (params) => {
-            const errorCategory = resolveTelemetryErrorCategory(params.errorCode);
-            const commandResolution = deriveTelemetryCommandResolution({
-                ok: false,
-                errorCode: params.errorCode,
-                errorCategory,
-            });
-            await emitTelemetryErrorEvent({
-                command: params.command,
-                args: invocationArgv,
-                options: params.options,
-                global: bootstrapGlobal,
-                pm_version: CLI_VERSION,
-                pm_root: bootstrapPmRoot,
-                error_code: params.errorCode,
-                error_message: params.errorMessage,
-                exit_code: params.exitCode,
-                error_category: errorCategory,
-                command_resolution: commandResolution,
-                resolution_stage: params.resolutionStage,
-            });
-            return {
-                errorCategory,
-                commandResolution,
-            };
-        };
-        if (!bootstrapGlobal.noExtensions) {
-            const bootstrapProbe = buildBootstrapActivationProbe(invocationArgv);
-            const discoverySnapshot = await loadRuntimeExtensionDiscoverySnapshot(bootstrapPmRoot);
-            if (discoverySnapshot && discoveryNeedsActivationForProbe(discoverySnapshot.discovery, bootstrapProbe)) {
-                const bootstrapSnapshot = await loadRuntimeExtensionSnapshot(bootstrapPmRoot);
-                /* c8 ignore next */
-                setActiveExtensionServices(bootstrapSnapshot?.services ?? { overrides: [] });
-            }
-            else {
-                /* c8 ignore next */
-                if (discoverySnapshot) {
-                    emitExtensionSkippedProfile(bootstrapProfileEnabled(invocationArgv), discoverySnapshot, bootstrapProbe);
-                }
-                setActiveExtensionServices({ overrides: [] });
-            }
-        }
-        const numericExitCode = readThrownExitCode(error);
-        if (error instanceof PmCliError ||
-            (!isCommanderError(error) && typeof numericExitCode === "number" && Number.isFinite(numericExitCode))) {
-            const errorMessage = describeUnknownError(error);
-            const exitCode = error instanceof PmCliError ? error.exitCode : normalizeThrownExitCode(numericExitCode);
-            const context = error instanceof PmCliError ? error.context : undefined;
-            const enrichedContext = buildPmCliRecoveryContext(context, invocationArgv, errorMessage);
-            const classification = classifyPmCliError(errorMessage, enrichedContext);
-            const renderedError = jsonErrors
-                ? JSON.stringify(formatPmCliErrorForJson(errorMessage, exitCode, enrichedContext), null, 2)
-                : formatPmCliErrorForDisplay(errorMessage, enrichedContext);
-            printError(renderedError);
-            const { errorCategory, commandResolution } = await emitTelemetryCommandError({
-                command: attemptedCommand,
-                errorCode: classification.code,
-                errorMessage: classification.detail,
-                exitCode,
-                options: {
-                    bootstrap_global_options: bootstrapGlobal,
-                },
-                resolutionStage: "execute",
-            });
-            const loggedHandledErrorToSentry = await maybeLogHandledCliErrorToSentry({
-                command: attemptedCommand,
-                error_code: classification.code,
-                error_category: errorCategory,
-                exit_code: exitCode,
-                error_message: classification.detail,
-                command_resolution: commandResolution,
-                resolution_stage: "execute",
-                source_context: activeTelemetryCommandContext?.source_context,
-            });
-            sentryFinishCommandSpan(false, errorMessage, {
-                error_code: classification.code,
-                error_category: errorCategory,
-                exit_code: exitCode,
-                command_resolution: commandResolution,
-                resolution_stage: "execute",
-            });
-            await runAndClearAfterCommandHooks({
-                ok: false,
-                error: errorMessage,
-                exit_code: exitCode,
-                error_code: classification.code,
-                error_category: errorCategory,
-                command_resolution: commandResolution,
-                resolution_stage: "execute",
-            });
-            if (loggedHandledErrorToSentry) {
-                sentryCaptureCliError(wrapThrownErrorForSentry(error, errorMessage));
-            }
-            if (loggedHandledErrorToSentry) {
-                await sentryFlush(HANDLED_ERROR_SENTRY_FLUSH_TIMEOUT_MS);
-            }
-            process.exitCode = exitCode;
-            return;
-        }
-        if (typeof error === "object" && error !== null && "code" in error) {
-            const code = error.code;
-            /* c8 ignore next */
-            const rawMessage = typeof error.message === "string" ? (error.message ?? "") : "";
-            const isHelpDisplayCode = code === "commander.helpDisplayed" || code === "commander.help" || code === "commander.helpCommand";
-            if (isHelpDisplayCode || rawMessage.includes("(outputHelp)")) {
-                const helpRequest = parseBootstrapHelpRequest(invocationArgv);
-                if (helpRequest.requested && !isKnownHelpCommandPath(program, helpRequest.commandPathTokens)) {
-                    /* c8 ignore next */
-                    const unknownToken = helpRequest.commandPathTokens[0] ?? parseBootstrapCommandName(invocationArgv) ?? "<command>";
-                    const unknownMessage = `unknown command '${unknownToken}'`;
-                    const recoveryCommandDescriptors = await loadRuntimeExtensionCommandDescriptorsForRecovery(resolvePmRoot(process.cwd(), bootstrapGlobal.path));
-                    const usageContext = await resolveCommanderUsageContext({ message: unknownMessage }, program, recoveryCommandDescriptors);
-                    const classification = classifyCommanderError(usageContext.message, usageContext.commandName, usageContext.allowedTypes, {
-                        unknownCommandExamples: usageContext.unknownCommandExamples,
-                        unknownCommandNextSteps: usageContext.unknownCommandNextSteps,
-                        attemptedCommand: usageContext.attemptedCommand,
-                        normalizedInvocationArgs: usageContext.normalizedInvocationArgs,
-                        providedOptionFlags: usageContext.providedOptionFlags,
-                        unknownOptionSuggestions: usageContext.unknownOptionSuggestions,
-                        suggestedRetryCommand: usageContext.suggestedRetryCommand,
-                    });
-                    const { errorCategory, commandResolution } = await emitTelemetryCommandError({
-                        command: unknownToken,
-                        errorCode: classification.code,
-                        errorMessage: classification.detail,
-                        exitCode: EXIT_CODE.USAGE,
-                        options: {
-                            bootstrap_global_options: bootstrapGlobal,
-                            commander_code: code ?? "commander.helpDisplayed",
-                        },
-                        resolutionStage: "parse",
-                    });
-                    const loggedHandledErrorToSentry = await maybeLogHandledCliErrorToSentry({
-                        command: unknownToken,
-                        error_code: classification.code,
-                        error_category: errorCategory,
-                        exit_code: EXIT_CODE.USAGE,
-                        error_message: classification.detail,
-                        command_resolution: commandResolution,
-                        resolution_stage: "parse",
-                        source_context: activeTelemetryCommandContext?.source_context,
-                    });
-                    const renderedUsage = jsonErrors
-                        ? await formatCommanderUsageJson({ message: unknownMessage }, program, recoveryCommandDescriptors)
-                        : await formatCommanderUsageMessage({ message: unknownMessage }, program, recoveryCommandDescriptors);
-                    sentryFinishCommandSpan(false, unknownMessage, {
-                        error_code: classification.code,
-                        error_category: errorCategory,
-                        exit_code: EXIT_CODE.USAGE,
-                        command_resolution: commandResolution,
-                        resolution_stage: "parse",
-                    });
-                    await runAndClearAfterCommandHooks({
-                        ok: false,
-                        error: unknownMessage,
-                        exit_code: EXIT_CODE.USAGE,
-                        error_code: classification.code,
-                        error_category: errorCategory,
-                        command_resolution: commandResolution,
-                        resolution_stage: "parse",
-                    });
-                    if (jsonErrors) {
-                        printError(renderedUsage);
-                    }
-                    else {
-                        printError(renderedUsage);
-                    }
-                    if (loggedHandledErrorToSentry) {
-                        await sentryFlush(HANDLED_ERROR_SENTRY_FLUSH_TIMEOUT_MS);
-                    }
-                    process.exitCode = EXIT_CODE.USAGE;
-                    return;
-                }
-                sentryFinishCommandSpan(true, undefined, {
-                    exit_code: EXIT_CODE.SUCCESS,
-                    command_resolution: "success",
-                    resolution_stage: "parse",
-                });
-                await runAndClearAfterCommandHooks({
-                    ok: true,
-                    exit_code: EXIT_CODE.SUCCESS,
-                    command_resolution: "success",
-                    resolution_stage: "parse",
-                });
-                process.exitCode = EXIT_CODE.SUCCESS;
-                return;
-            }
-            if (code === "commander.version") {
-                sentryFinishCommandSpan(true, undefined, {
-                    exit_code: EXIT_CODE.SUCCESS,
-                    command_resolution: "success",
-                    resolution_stage: "parse",
-                });
-                await runAndClearAfterCommandHooks({
-                    ok: true,
-                    exit_code: EXIT_CODE.SUCCESS,
-                    command_resolution: "success",
-                    resolution_stage: "parse",
-                });
-                process.exitCode = EXIT_CODE.SUCCESS;
-                return;
-            }
-            /* c8 ignore next */
-            if (code?.startsWith("commander.")) {
-                const usageContext = await resolveCommanderUsageContext(error, program, activeRuntimeExtensionCommandDescriptors);
-                const classification = classifyCommanderError(usageContext.message, usageContext.commandName, usageContext.allowedTypes, {
-                    unknownCommandExamples: usageContext.unknownCommandExamples,
-                    unknownCommandNextSteps: usageContext.unknownCommandNextSteps,
-                    attemptedCommand: usageContext.attemptedCommand,
-                    normalizedInvocationArgs: usageContext.normalizedInvocationArgs,
-                    providedOptionFlags: usageContext.providedOptionFlags,
-                    unknownOptionSuggestions: usageContext.unknownOptionSuggestions,
-                    suggestedRetryCommand: usageContext.suggestedRetryCommand,
-                });
-                const { errorCategory, commandResolution } = await emitTelemetryCommandError({
-                    command: attemptedCommand,
-                    errorCode: classification.code,
-                    errorMessage: classification.detail,
-                    exitCode: EXIT_CODE.USAGE,
-                    options: {
-                        bootstrap_global_options: bootstrapGlobal,
-                        commander_code: code,
-                    },
-                    resolutionStage: "parse",
-                });
-                const loggedHandledErrorToSentry = await maybeLogHandledCliErrorToSentry({
-                    command: attemptedCommand,
-                    error_code: classification.code,
-                    error_category: errorCategory,
-                    exit_code: EXIT_CODE.USAGE,
-                    error_message: classification.detail,
-                    command_resolution: commandResolution,
-                    resolution_stage: "parse",
-                    source_context: activeTelemetryCommandContext?.source_context,
-                });
-                const renderedUsage = jsonErrors
-                    ? await formatCommanderUsageJson(error, program, activeRuntimeExtensionCommandDescriptors)
-                    : await formatCommanderUsageMessage(error, program, activeRuntimeExtensionCommandDescriptors);
-                sentryFinishCommandSpan(false, usageContext.message, {
-                    error_code: classification.code,
-                    error_category: errorCategory,
-                    exit_code: EXIT_CODE.USAGE,
-                    command_resolution: commandResolution,
-                    resolution_stage: "parse",
-                });
-                await runAndClearAfterCommandHooks({
-                    ok: false,
-                    error: usageContext.message,
-                    exit_code: EXIT_CODE.USAGE,
-                    error_code: classification.code,
-                    error_category: errorCategory,
-                    command_resolution: commandResolution,
-                    resolution_stage: "parse",
-                });
-                if (jsonErrors) {
-                    printError(renderedUsage);
-                }
-                else {
-                    printError(renderedUsage);
-                }
-                if (loggedHandledErrorToSentry) {
-                    await sentryFlush(HANDLED_ERROR_SENTRY_FLUSH_TIMEOUT_MS);
-                }
-                process.exitCode = EXIT_CODE.USAGE;
-                return;
-            }
-        }
-        /* c8 ignore next */
-        await handleGenericRunPmCliError({
-            error,
-            attemptedCommand,
-            bootstrapGlobal,
-            emitTelemetryCommandError,
-        });
-        /* c8 ignore stop */
+        await handleRunPmCliError({ error, invocationArgv });
     }
 }
 export const _testOnly = {
@@ -2218,6 +2311,12 @@ export const _testOnly = {
     extensionProvidesTemplatesRuntime,
     hasAnyCapability,
     handleGenericRunPmCliError,
+    handleRunPmCliCommanderError,
+    handleRunPmCliError,
+    handleRunPmCliHelpDisplayError,
+    handleRunPmCliKnownError,
+    handleRunPmCliCommanderUsageError,
+    handleUnknownHelpCommandError,
     inferMissingFieldsFromErrorMessage,
     inferPostActionErrorCode,
     inferPostActionFailureMessage,
@@ -2234,12 +2333,14 @@ export const _testOnly = {
     normalizeTelemetryResolutionStage,
     normalizeThrownExitCode,
     probeUsesAnyFlag,
+    prepareExtensionServicesForRunPmCliError,
     readRecordBoolean,
     readRecordNumber,
     readRecordString,
     registerDynamicExtensionCommandPaths,
     registerRuntimeSchemaFieldFlags,
     resolveCoreCommandRegistrationSelection,
+    resolveUnknownHelpToken,
     readThrownExitCode,
     runAndClearAfterCommandHooks,
     runRequiredExtensionCommand,
@@ -2247,8 +2348,10 @@ export const _testOnly = {
     shouldLogHandledErrorToSentry,
     shouldRegisterDynamicExtensionPaths,
     shouldRegisterRuntimeSchemaFlags,
+    shouldHandleRunPmCliCommanderError,
     setActiveExtensionHookContextForTest,
     setActiveRuntimeExtensionCommandDescriptorsForTest,
+    setRecoveredExtensionServices,
     toLooseFieldDefinitionType,
     isImporterOrExporterCommandPath,
     validateDynamicExtensionCommandInvocation,
@@ -2256,4 +2359,4 @@ export const _testOnly = {
     wrapThrownErrorForSentry,
 };
 //# sourceMappingURL=main.js.map
-//# debugId=9f13a662-73c4-5ffa-99bc-4edee2b7a7fb
+//# debugId=aa682568-77f6-5659-a6dd-3a69dd4e1fc0