@unbrained/pm-cli 2026.10.11 → 2026.10.13

package/dist/cli/help-json-payload.d.ts

@@ -10,33 +10,33 @@ import { type PmPositionalActionContract } from "../sdk/cli-contracts/grammar-co
 import { type PmCommandCapabilityFamily, type PmCommandVisibilityTier } from "../sdk/agent-capability-contracts.js";
 /** Documents the help argument summary payload exchanged by command, SDK, and package integrations. */
 export interface HelpArgumentSummary {
-    /** Value that configures or reports name for this contract. */
-    name: string;
-    /** Value that configures or reports required for this contract. */
-    required: boolean;
-    /** Value that configures or reports variadic for this contract. */
-    variadic: boolean;
-    /** Value that configures or reports description for this contract. */
-    description: string | null;
+/** Value that configures or reports name for this contract. */
+name: string;
+/** Value that configures or reports required for this contract. */
+required: boolean;
+/** Value that configures or reports variadic for this contract. */
+variadic: boolean;
+/** Value that configures or reports description for this contract. */
+description: string | null;
 }
 /** Documents the help subcommand summary payload exchanged by command, SDK, and package integrations. */
 export interface HelpSubcommandSummary {
-    /** Value that configures or reports name for this contract. */
-    name: string;
-    /** Value that configures or reports aliases for this contract. */
-    aliases: string[];
-    /** Value that configures or reports description for this contract. */
-    description: string;
-    /** Shared command visibility tier. */
-    tier: PmCommandVisibilityTier;
-    /** Shared command capability family. */
-    family: PmCommandCapabilityFamily;
-    /** Canonical command path when this row is an executable alias. */
-    alias_for?: string;
-    /** Compatibility lifecycle declared by the canonical alias contract. */
-    alias_lifecycle?: "permanent" | "deprecated";
-    /** True when callers should migrate from this executable spelling. */
-    deprecated?: true;
+/** Value that configures or reports name for this contract. */
+name: string;
+/** Value that configures or reports aliases for this contract. */
+aliases: string[];
+/** Value that configures or reports description for this contract. */
+description: string;
+/** Shared command visibility tier. */
+tier: PmCommandVisibilityTier;
+/** Shared command capability family. */
+family: PmCommandCapabilityFamily;
+/** Canonical command path when this row is an executable alias. */
+alias_for?: string;
+/** Compatibility lifecycle declared by the canonical alias contract. */
+alias_lifecycle?: "permanent" | "deprecated";
+/** True when callers should migrate from this executable spelling. */
+deprecated?: true;
 }
 type ExtensionCommandSurface = Pick<ExtensionCommandHelpDescriptor, "tier" | "family">;
 /** Resolve semantic package metadata, or fold descendant tiers and families for a namespace. */
@@ -51,10 +51,10 @@ declare function buildHelpArgumentSummaries(command: Command): HelpArgumentSumma
 /** Describe discoverable children with semantic tiers and package metadata, retaining hidden public commands for full discovery. */
 declare function buildHelpSubcommandSummaries(command: Command, extensionDescriptors?: ReadonlyMap<string, ExtensionCommandHelpDescriptor>, includeAll?: boolean): HelpSubcommandSummary[];
 interface PositionalActionHelpProjection {
-    arguments: HelpArgumentSummary[];
-    options: HelpOptionSummary[];
-    subcommands: HelpSubcommandSummary[];
-    usage: string;
+arguments: HelpArgumentSummary[];
+options: HelpOptionSummary[];
+subcommands: HelpSubcommandSummary[];
+usage: string;
 }
 /** Build the command/action structural view shared by every JSON help field. */
 declare function buildPositionalActionHelpProjection(action: PmPositionalActionContract | undefined, targetCommand: Command, resolvedPath: string, allOptions: HelpOptionSummary[], extensionDescriptors?: ReadonlyMap<string, ExtensionCommandHelpDescriptor>, includeAll?: boolean): PositionalActionHelpProjection;
@@ -67,17 +67,17 @@ declare function buildCreateUpdatePolicyHelpText(commandName: "create" | "update
 export declare function attachCreateUpdatePolicyHelpText(rootProgram: Command, typeRegistry: ReturnType<typeof resolveItemTypeRegistry>, argv: string[]): void;
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
 export declare const _testOnly: {
-    attachCreateUpdatePolicyHelpText: typeof attachCreateUpdatePolicyHelpText;
-    buildCreateUpdatePolicyHelpText: typeof buildCreateUpdatePolicyHelpText;
-    buildJsonHelpPayload: typeof buildJsonHelpPayload;
-    buildPositionalActionHelpProjection: typeof buildPositionalActionHelpProjection;
-    buildHelpArgumentSummaries: typeof buildHelpArgumentSummaries;
-    buildHelpOptionSummaries: typeof buildHelpOptionSummaries;
-    buildHelpSubcommandSummaries: typeof buildHelpSubcommandSummaries;
-    buildOptionAliasMap: typeof buildOptionAliasMap;
-    compactHelpOptionAliases: typeof compactHelpOptionAliases;
-    readOptionAttributeName: typeof readOptionAttributeName;
-    resolveCommandFromPathTokens: typeof resolveCommandFromPathTokens;
-    resolveExtensionCommandSurface: typeof resolveExtensionCommandSurface;
+attachCreateUpdatePolicyHelpText: typeof attachCreateUpdatePolicyHelpText;
+buildCreateUpdatePolicyHelpText: typeof buildCreateUpdatePolicyHelpText;
+buildJsonHelpPayload: typeof buildJsonHelpPayload;
+buildPositionalActionHelpProjection: typeof buildPositionalActionHelpProjection;
+buildHelpArgumentSummaries: typeof buildHelpArgumentSummaries;
+buildHelpOptionSummaries: typeof buildHelpOptionSummaries;
+buildHelpSubcommandSummaries: typeof buildHelpSubcommandSummaries;
+buildOptionAliasMap: typeof buildOptionAliasMap;
+compactHelpOptionAliases: typeof compactHelpOptionAliases;
+readOptionAttributeName: typeof readOptionAttributeName;
+resolveCommandFromPathTokens: typeof resolveCommandFromPathTokens;
+resolveExtensionCommandSurface: typeof resolveExtensionCommandSurface;
 };
 export {};

package/dist/cli/help-json-payload.js

@@ -1,4 +1,4 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6bca8bb8-c8f8-5bf5-bd3a-1e3089571238")}catch{}})();import{hasSubcommandFlagContractsForCommand,PM_COMMAND_ALIAS_CONTRACTS,PM_CORE_COMMAND_NAMES,resolvePmCommandAlias,resolvePmCommandOperation}from"../sdk/cli-contracts.js";import{commandOptionFlagLabel,resolveCommandOptionPolicyState,resolveTypeDefinition,EXIT_CODE,writeStderr,writeStdout}from"../sdk/runtime-primitives.js";import{buildDynamicExtensionHelpOptionSummaries,mergeHelpOptionSummaries,findCommandByPath,findDirectChildCommand,commandAliases}from"./extension-command-help.js";import{getPmCommandHelpVisibilityTier,isFullHelpDiscovery,normalizeHelpCommandPath,resolveHelpBundleForPath,resolveHelpDetailMode,resolveHelpNarrative,ROOT_HELP_BUNDLE}from"./help-content.js";import{getCommandPath}from"./registration-helpers.js";import{parseBootstrapGlobalOptions,parseBootstrapHelpRequest,parseBootstrapCommandName,parseBootstrapTypeValue}from"./bootstrap-args.js";import{extractProvidedOptionFlags,renderPmCommand}from"./argv-utils.js";import{formatCommanderErrorForJson}from"./error-guidance.js";import{BUILTIN_TYPE_HELP_VALUES,buildUnknownCommandGuidanceFromRuntime,isKnownHelpCommandPath}from"./commander-usage.js";import{attachOutputTokenAccounting}from"../sdk/output-token-accounting.js";import{resolveCreateExplicitEmptyFlag}from"../sdk/agent/create-option-policy.js";import{formatPmPositionalActionFlagTip,PM_POSITIONAL_ACTION_CONTRACTS,resolvePmPositionalActionContract}from"../sdk/cli-contracts/grammar-contracts.js";import{resolvePmCommandCapabilityFamily,resolvePmCommandVisibilityTier}from"../sdk/agent-capability-contracts.js";const EXTENSION_TIER_ORDER={core:0,standard:1,full:2,internal:3};function resolveExtensionCommandSurface(commandPath,descriptors,allowDescendants=!0){const exact=descriptors.get(resolvePmCommandOperation(commandPath));if(exact)return exact;if(!allowDescendants)return;const descendants=[...descriptors.entries()].filter(([path])=>path.startsWith(`${commandPath} `)).map(([,descriptor])=>descriptor);if(descendants.length===0)return;const tier=descendants.reduce((selected,descriptor)=>EXTENSION_TIER_ORDER[descriptor.tier]<EXTENSION_TIER_ORDER[selected]?descriptor.tier:selected,"internal"),families=new Set(descendants.map(({family})=>family));return{tier,family:families.size===1?descendants[0].family:"extensions"}}function resolveCommandFromPathTokens(root,pathTokens){if(pathTokens.length===0)return root;const exactCommand=findCommandByPath(root,pathTokens);if(exactCommand)return exactCommand;const requestedPath=pathTokens.join(" ");if(resolvePmCommandOperation(requestedPath)!==requestedPath||!PM_CORE_COMMAND_NAMES.some(commandName=>commandName===requestedPath)&&!hasSubcommandFlagContractsForCommand(requestedPath)&&!resolvePmPositionalActionContract(requestedPath)&&!isKnownHelpCommandPath(root,pathTokens))return null;for(let length=pathTokens.length-1;length>0;length-=1){const positionalParent=findCommandByPath(root,pathTokens.slice(0,length));if(positionalParent)return positionalParent}return pathTokens.length===1?root:null}function extractOptionValueName(flags){const match=flags.match(/[<[]([^>\]]+)[>\]]/);if(!match)return null;const value=match[1]?.trim();return value&&value.length>0?value:null}function readOptionAttributeName(option){const optionRecord=option;if(typeof optionRecord.attributeName=="function"){const value=optionRecord.attributeName();return typeof value=="string"&&value.trim().length>0?value.trim():null}return typeof optionRecord.attributeName=="string"&&optionRecord.attributeName.trim().length>0?optionRecord.attributeName.trim():null}function buildOptionAliasMap(options){const aliasMap=new Map;for(const option of options){const optionRecord=option,attributeName=readOptionAttributeName(option);if(!attributeName||typeof optionRecord.long!="string"||optionRecord.long.trim().length===0)continue;const existing=aliasMap.get(attributeName)??[];existing.push(optionRecord.long.trim()),aliasMap.set(attributeName,existing)}for(const[attributeName,values]of aliasMap.entries())aliasMap.set(attributeName,[...new Set(values.map(value=>value.trim()).filter(value=>value.length>0))].sort((left,right)=>left.localeCompare(right)));return aliasMap}function renderAttemptedCommand(argv){return renderPmCommand(argv)}function buildHelpOptionSummaries(command){const options=command.options??[],optionAliasMap=buildOptionAliasMap(options);return options.map(option=>{const optionRecord=option,flags=typeof optionRecord.flags=="string"?optionRecord.flags.trim():"",description=typeof optionRecord.description=="string"?optionRecord.description.trim():"",attributeName=readOptionAttributeName(option),aliases=(attributeName?optionAliasMap.get(attributeName)??[]:[]).filter(entry=>entry!==optionRecord.long).map(entry=>entry.trim()).filter(entry=>entry.length>0),aliasForMatch=description.match(/^Alias for ([^ ]+)/i),aliasFor=aliasForMatch&&aliasForMatch[1]?aliasForMatch[1].trim():null,required=optionRecord.mandatory===!0||description.includes("[required]")||description.toLowerCase().includes("required;"),valueRequired=flags.includes("<"),takesValue=valueRequired||flags.includes("["),summary={flags,long:typeof optionRecord.long=="string"?optionRecord.long:null,short:typeof optionRecord.short=="string"?optionRecord.short:null,description,takes_value:takesValue,value_required:valueRequired,value_name:extractOptionValueName(flags),variadic:optionRecord.variadic===!0,required,aliases,alias_for:aliasFor};return optionRecord.defaultValue!==void 0&&(summary.default_value=optionRecord.defaultValue),summary})}function compactHelpOptionAliases(options){const canonicalByLong=new Map,aliasOptions=[];for(const option of options){if(option.alias_for&&option.long){aliasOptions.push(option);continue}option.long&&canonicalByLong.set(option.long,option)}for(const aliasOption of aliasOptions){const aliasFor=aliasOption.alias_for,canonical=canonicalByLong.get(aliasFor);if(!canonical)continue;const aliasLong=aliasOption.long,aliases=new Set([...canonical.aliases??[],aliasLong]);canonical.aliases=[...aliases].sort((left,right)=>left.localeCompare(right))}return options.filter(option=>!option.alias_for||!option.long?!0:!canonicalByLong.has(option.alias_for))}function buildHelpArgumentSummaries(command){const commandRecord=command;return(Array.isArray(commandRecord.registeredArguments)?commandRecord.registeredArguments:Array.isArray(commandRecord._args)?commandRecord._args:[]).map(argument=>{const rawName=typeof argument.name=="function"?argument.name():typeof argument.name=="string"?argument.name:"argument",description=typeof argument.description=="string"&&argument.description.trim().length>0?argument.description.trim():null;return{name:rawName.trim(),required:argument.required===!0||description?.toLowerCase().startsWith("required;")===!0,variadic:argument.variadic===!0,description}})}function buildHelpSubcommandSummaries(command,extensionDescriptors=new Map,includeAll=!1){const visible=command.createHelp().visibleCommands(command);return(includeAll?[...new Set([...visible,...command.commands])]:visible).filter(entry=>entry.name()!=="help"||command.parent===null).filter(entry=>!includeAll||(getPmCommandHelpVisibilityTier(entry)??resolvePmCommandVisibilityTier(entry.name()))!=="internal").map(entry=>{const commandPath=normalizeHelpCommandPath(getCommandPath(entry)),rootCommand=commandPath,declaredTier=getPmCommandHelpVisibilityTier(entry),extensionDescriptor=resolveExtensionCommandSurface(commandPath,extensionDescriptors,declaredTier!==void 0),aliasContract=PM_COMMAND_ALIAS_CONTRACTS.find(({alias})=>alias===commandPath);return{name:entry.name().trim(),aliases:commandAliases(entry),description:entry.description().trim(),tier:extensionDescriptor?.tier??declaredTier??resolvePmCommandVisibilityTier(rootCommand),family:extensionDescriptor?.family??resolvePmCommandCapabilityFamily(rootCommand),...aliasContract?{alias_for:aliasContract.canonical,alias_lifecycle:aliasContract.lifecycle,...aliasContract.lifecycle==="deprecated"?{deprecated:!0}:{}}:{}}}).sort((left,right)=>left.name.localeCompare(right.name))}function buildJsonHelpNarrative(detailMode,fallbackNarrative,extensionDescriptor){if(!extensionDescriptor)return fallbackNarrative;const extensionExamples=extensionDescriptor.examples??[],extensionFailureHints=extensionDescriptor.failure_hints??[];return{intent:extensionDescriptor.intent??extensionDescriptor.description??fallbackNarrative.intent,examples:detailMode==="detailed"?extensionExamples.length>0?[...extensionExamples]:[...fallbackNarrative.examples]:extensionExamples.length>0?[extensionExamples[0]]:[...fallbackNarrative.examples],tips:detailMode==="detailed"?extensionFailureHints.length>0?[...extensionFailureHints]:[...fallbackNarrative.tips]:[],detail_mode:detailMode}}function resolveJsonHelpNarrative(commandPath,commandDescription,detailMode,extensionDescriptor,hasPositionalAction){const isRootFallback=commandPath!==void 0&&resolveHelpBundleForPath(commandPath)===ROOT_HELP_BUNDLE,fallback=isRootFallback?{intent:commandDescription,examples:[`pm ${commandPath} --help`],tips:[],detail_mode:detailMode}:resolveHelpNarrative(commandPath,detailMode),intentSource=hasPositionalAction?"positional_action":extensionDescriptor?.intent||extensionDescriptor?.description?"extension":isRootFallback?commandDescription?"command_description":"unavailable":commandPath?"help_bundle":"root_help_bundle";return{narrative:buildJsonHelpNarrative(detailMode,fallback,extensionDescriptor),intentSource}}function resolveJsonHelpVisibilityTier(rootCommandPath,extensionDescriptor){return rootCommandPath===void 0?null:extensionDescriptor?.tier??resolvePmCommandVisibilityTier(rootCommandPath)}function resolveJsonHelpCapabilityFamily(rootCommandPath,extensionDescriptor){return rootCommandPath===void 0?null:extensionDescriptor?.family??resolvePmCommandCapabilityFamily(rootCommandPath)}function projectFullCommandAliases(rootProgram,targetCommand,fullDiscovery){if(!(targetCommand!==rootProgram||!fullDiscovery))return PM_COMMAND_ALIAS_CONTRACTS.map(contract=>({alias:contract.alias,canonical:contract.canonical,canonical_argv:[...contract.canonical_argv],available:resolveCommandFromPathTokens(rootProgram,contract.canonical.split(" "))!==null,lifecycle:contract.lifecycle,hidden:contract.hidden,deprecated:contract.lifecycle==="deprecated"}))}function buildPositionalActionHelpProjection(action,targetCommand,resolvedPath,allOptions,extensionDescriptors=new Map,includeAll=!1){if(!action){const argumentsList=buildHelpArgumentSummaries(targetCommand),registeredSubcommands=buildHelpSubcommandSummaries(targetCommand,extensionDescriptors,includeAll),registeredSubcommandNames=new Set(registeredSubcommands.map(({name})=>name));return{arguments:argumentsList,options:allOptions,subcommands:[...registeredSubcommands,...PM_POSITIONAL_ACTION_CONTRACTS.filter(({parent,action:name})=>parent===resolvedPath&&!registeredSubcommandNames.has(name)).map(({action:name,description})=>({name,aliases:[],description,tier:resolvePmCommandVisibilityTier(resolvedPath.split(" ")[0]),family:resolvePmCommandCapabilityFamily(resolvedPath.split(" ")[0])}))].sort((left,right)=>left.name.localeCompare(right.name)),usage:[resolvedPath,argumentsList.reduce((usage,argument)=>argument.required?usage.replace(`[${argument.name}${argument.variadic?"...":""}]`,`<${argument.name}${argument.variadic?"...":""}>`):usage,targetCommand.usage())].filter(token=>token.length>0).join(" ")}}const acceptedFlags=new Set(action.accepted_flags);return{arguments:action.slots.map(({name,required,variadic,value_kind:valueKind,polymorphic})=>({name,required,variadic,description:polymorphic?`Polymorphic ${valueKind} value; inspect the action contract before mutation.`:`${valueKind.replaceAll("_"," ")} value.`})),options:allOptions.filter(({long,aliases})=>long!==null&&acceptedFlags.has(long)||aliases.some(alias=>acceptedFlags.has(alias))),subcommands:[],usage:[action.command,...action.slots.map(({name,required,variadic})=>{const token=variadic?`${name}...`:name;return required?`<${token}>`:`[${token}]`})].join(" ")}}function buildJsonHelpPayload(rootProgram,targetCommand,argv,requestedPath,extensionDescriptors){const detailMode=resolveHelpDetailMode(argv),fullDiscovery=isFullHelpDiscovery(argv),commanderPath=normalizeHelpCommandPath(getCommandPath(targetCommand)),requestedCommandPath=normalizeHelpCommandPath(requestedPath.join(" ")),resolvedPath=requestedCommandPath.length>commanderPath.length?requestedCommandPath:commanderPath,positionalAction=resolvePmPositionalActionContract(resolvedPath),projectedPath=positionalAction?.command??commanderPath,commandPath=projectedPath.length>0?projectedPath:void 0,rootCommandPath=commandPath,extensionDescriptor=commandPath?extensionDescriptors.get(resolvePmCommandOperation(commandPath)):void 0,extensionSurface=commandPath?resolveExtensionCommandSurface(commandPath,extensionDescriptors,getPmCommandHelpVisibilityTier(targetCommand)!==void 0):void 0,{narrative,intentSource}=resolveJsonHelpNarrative(commandPath,targetCommand.description().trim(),detailMode,extensionDescriptor,positionalAction!==void 0),allOptionSummaries=compactHelpOptionAliases(mergeHelpOptionSummaries(buildHelpOptionSummaries(targetCommand),buildDynamicExtensionHelpOptionSummaries(extensionDescriptor))),projection=buildPositionalActionHelpProjection(positionalAction,targetCommand,projectedPath,allOptionSummaries,extensionDescriptors,fullDiscovery),fullCommandAliases=projectFullCommandAliases(rootProgram,targetCommand,fullDiscovery);return{format:"pm_help_v1",detail_mode:detailMode,root_command:rootProgram.name(),requested_path:requestedPath,resolved_path:projectedPath.length>0?projectedPath:rootProgram.name(),visibility_tier:resolveJsonHelpVisibilityTier(rootCommandPath,extensionSurface),capability_family:resolveJsonHelpCapabilityFamily(rootCommandPath,extensionSurface),description:positionalAction?.description??targetCommand.description(),usage:projection.usage,intent:positionalAction?.description??narrative.intent,intent_source:intentSource,examples:positionalAction?[positionalAction.example]:narrative.examples,tips:positionalAction?[formatPmPositionalActionFlagTip(positionalAction.accepted_flags)]:narrative.tips,arguments:projection.arguments,options:projection.options,subcommands:projection.subcommands,has_subcommands:projection.subcommands.length>0,...fullCommandAliases===void 0?{}:{command_aliases:fullCommandAliases}}}async function maybeRenderBootstrapJsonHelp(rootProgram,argv,extensionDescriptors,requestedArgv=argv){const bootstrapGlobal=parseBootstrapGlobalOptions(argv);if(!bootstrapGlobal.json)return!1;const helpRequest=parseBootstrapHelpRequest(argv);if(!helpRequest.requested)return!1;const targetCommand=resolveCommandFromPathTokens(rootProgram,helpRequest.commandPathTokens);if(!targetCommand){if(!bootstrapGlobal.quiet){const unknownMessage=`unknown command '${resolvePmCommandOperation(helpRequest.commandPathTokens.join(" "))}'`,runtimeContext=buildUnknownCommandGuidanceFromRuntime(unknownMessage,rootProgram,extensionDescriptors),envelope=formatCommanderErrorForJson(unknownMessage,"help",BUILTIN_TYPE_HELP_VALUES,EXIT_CODE.USAGE,{...runtimeContext,attemptedCommand:renderAttemptedCommand(argv),normalizedInvocationArgs:[...argv],providedOptionFlags:extractProvidedOptionFlags(argv)}),output=bootstrapGlobal.tokenAccounting?attachOutputTokenAccounting(envelope,value=>`${JSON.stringify(value,null,2)}
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="3f896a8d-2c03-5f9c-9909-4684a187870d")}catch{}})();import{hasSubcommandFlagContractsForCommand,PM_COMMAND_ALIAS_CONTRACTS,PM_CORE_COMMAND_NAMES,resolvePmCommandAlias,resolvePmCommandOperation}from"../sdk/cli-contracts.js";import{commandOptionFlagLabel,resolveCommandOptionPolicyState,resolveTypeDefinition,EXIT_CODE,writeStderr,writeStdout}from"../sdk/runtime-primitives.js";import{buildDynamicExtensionHelpOptionSummaries,mergeHelpOptionSummaries,findCommandByPath,findDirectChildCommand,commandAliases}from"./extension-command-help.js";import{getPmCommandHelpVisibilityTier,isFullHelpDiscovery,normalizeHelpCommandPath,resolveHelpBundleForPath,resolveHelpDetailMode,resolveHelpNarrative,ROOT_HELP_BUNDLE}from"./help-content.js";import{getCommandPath}from"./registration-helpers.js";import{parseBootstrapGlobalOptions,parseBootstrapHelpRequest,parseBootstrapCommandName,parseBootstrapTypeValue}from"./bootstrap-args.js";import{extractProvidedOptionFlags,renderPmCommand}from"./argv-utils.js";import{formatCommanderErrorForJson}from"./error-guidance.js";import{BUILTIN_TYPE_HELP_VALUES,buildUnknownCommandGuidanceFromRuntime,isKnownHelpCommandPath}from"./commander-usage.js";import{attachOutputTokenAccounting}from"../sdk/output-token-accounting.js";import{resolveCreateExplicitEmptyFlag}from"../sdk/agent/create-option-policy.js";import{formatPmPositionalActionFlagTip,PM_POSITIONAL_ACTION_CONTRACTS,resolvePmPositionalActionContract}from"../sdk/cli-contracts/grammar-contracts.js";import{resolvePmCommandCapabilityFamily,resolvePmCommandVisibilityTier}from"../sdk/agent-capability-contracts.js";const EXTENSION_TIER_ORDER={core:0,standard:1,full:2,internal:3};function resolveExtensionCommandSurface(commandPath,descriptors,allowDescendants=!0){const exact=descriptors.get(resolvePmCommandOperation(commandPath));if(exact)return exact;if(!allowDescendants)return;const descendants=[...descriptors.entries()].filter(([path])=>path.startsWith(`${commandPath} `)).map(([,descriptor])=>descriptor);if(descendants.length===0)return;const tier=descendants.reduce((selected,descriptor)=>EXTENSION_TIER_ORDER[descriptor.tier]<EXTENSION_TIER_ORDER[selected]?descriptor.tier:selected,"internal"),families=new Set(descendants.map(({family})=>family));return{tier,family:families.size===1?descendants[0].family:"extensions"}}function resolveCommandFromPathTokens(root,pathTokens){if(pathTokens.length===0)return root;const exactCommand=findCommandByPath(root,pathTokens);if(exactCommand)return exactCommand;const requestedPath=pathTokens.join(" ");if(resolvePmCommandOperation(requestedPath)!==requestedPath||!PM_CORE_COMMAND_NAMES.some(commandName=>commandName===requestedPath)&&!hasSubcommandFlagContractsForCommand(requestedPath)&&!resolvePmPositionalActionContract(requestedPath)&&!isKnownHelpCommandPath(root,pathTokens))return null;for(let length=pathTokens.length-1;length>0;length-=1){const positionalParent=findCommandByPath(root,pathTokens.slice(0,length));if(positionalParent)return positionalParent}return pathTokens.length===1?root:null}function extractOptionValueName(flags){const match=flags.match(/[<[]([^>\]]+)[>\]]/);if(!match)return null;const value=match[1]?.trim();return value&&value.length>0?value:null}function readOptionAttributeName(option){const optionRecord=option;if(typeof optionRecord.attributeName=="function"){const value=optionRecord.attributeName();return typeof value=="string"&&value.trim().length>0?value.trim():null}return typeof optionRecord.attributeName=="string"&&optionRecord.attributeName.trim().length>0?optionRecord.attributeName.trim():null}function buildOptionAliasMap(options){const aliasMap=new Map;for(const option of options){const optionRecord=option,attributeName=readOptionAttributeName(option);if(!attributeName||typeof optionRecord.long!="string"||optionRecord.long.trim().length===0)continue;const existing=aliasMap.get(attributeName)??[];existing.push(optionRecord.long.trim()),aliasMap.set(attributeName,existing)}for(const[attributeName,values]of aliasMap.entries())aliasMap.set(attributeName,[...new Set(values.map(value=>value.trim()).filter(value=>value.length>0))].sort((left,right)=>left.localeCompare(right)));return aliasMap}function renderAttemptedCommand(argv){return renderPmCommand(argv)}function buildHelpOptionSummaries(command){const options=command.options??[],optionAliasMap=buildOptionAliasMap(options);return options.map(option=>{const optionRecord=option,flags=typeof optionRecord.flags=="string"?optionRecord.flags.trim():"",description=typeof optionRecord.description=="string"?optionRecord.description.trim():"",attributeName=readOptionAttributeName(option),aliases=(attributeName?optionAliasMap.get(attributeName)??[]:[]).filter(entry=>entry!==optionRecord.long).map(entry=>entry.trim()).filter(entry=>entry.length>0),aliasForMatch=description.match(/^Alias for ([^ ]+)/i),aliasFor=aliasForMatch&&aliasForMatch[1]?aliasForMatch[1].trim():null,required=optionRecord.mandatory===!0||description.includes("[required]")||description.toLowerCase().includes("required;"),valueRequired=flags.includes("<"),takesValue=valueRequired||flags.includes("["),summary={flags,long:typeof optionRecord.long=="string"?optionRecord.long:null,short:typeof optionRecord.short=="string"?optionRecord.short:null,description,takes_value:takesValue,value_required:valueRequired,value_name:extractOptionValueName(flags),variadic:optionRecord.variadic===!0,required,aliases,alias_for:aliasFor};return optionRecord.defaultValue!==void 0&&(summary.default_value=optionRecord.defaultValue),summary})}function compactHelpOptionAliases(options){const canonicalByLong=new Map,aliasOptions=[];for(const option of options){if(option.alias_for&&option.long){aliasOptions.push(option);continue}option.long&&canonicalByLong.set(option.long,option)}for(const aliasOption of aliasOptions){const aliasFor=aliasOption.alias_for,canonical=canonicalByLong.get(aliasFor);if(!canonical)continue;const aliasLong=aliasOption.long,aliases=new Set([...canonical.aliases??[],aliasLong]);canonical.aliases=[...aliases].sort((left,right)=>left.localeCompare(right))}return options.filter(option=>!option.alias_for||!option.long?!0:!canonicalByLong.has(option.alias_for))}function buildHelpArgumentSummaries(command){const commandRecord=command;return(Array.isArray(commandRecord.registeredArguments)?commandRecord.registeredArguments:Array.isArray(commandRecord._args)?commandRecord._args:[]).map(argument=>{const rawName=typeof argument.name=="function"?argument.name():typeof argument.name=="string"?argument.name:"argument",description=typeof argument.description=="string"&&argument.description.trim().length>0?argument.description.trim():null;return{name:rawName.trim(),required:argument.required===!0||description?.toLowerCase().startsWith("required;")===!0,variadic:argument.variadic===!0,description}})}function buildHelpSubcommandSummaries(command,extensionDescriptors=new Map,includeAll=!1){const visible=command.createHelp().visibleCommands(command);return(includeAll?[...new Set([...visible,...command.commands])]:visible).filter(entry=>entry.name()!=="help"||command.parent===null).filter(entry=>!includeAll||(getPmCommandHelpVisibilityTier(entry)??resolvePmCommandVisibilityTier(entry.name()))!=="internal").map(entry=>{const commandPath=normalizeHelpCommandPath(getCommandPath(entry)),rootCommand=commandPath,declaredTier=getPmCommandHelpVisibilityTier(entry),extensionDescriptor=resolveExtensionCommandSurface(commandPath,extensionDescriptors,declaredTier!==void 0),aliasContract=PM_COMMAND_ALIAS_CONTRACTS.find(({alias})=>alias===commandPath);return{name:entry.name().trim(),aliases:commandAliases(entry),description:entry.description().trim(),tier:extensionDescriptor?.tier??declaredTier??resolvePmCommandVisibilityTier(rootCommand),family:extensionDescriptor?.family??resolvePmCommandCapabilityFamily(rootCommand),...aliasContract?{alias_for:aliasContract.canonical,alias_lifecycle:aliasContract.lifecycle,...aliasContract.lifecycle==="deprecated"?{deprecated:!0}:{}}:{}}}).sort((left,right)=>left.name.localeCompare(right.name))}function buildJsonHelpNarrative(detailMode,fallbackNarrative,extensionDescriptor){if(!extensionDescriptor)return fallbackNarrative;const extensionExamples=extensionDescriptor.examples??[],extensionFailureHints=extensionDescriptor.failure_hints??[];return{intent:extensionDescriptor.intent??extensionDescriptor.description??fallbackNarrative.intent,examples:detailMode==="detailed"?extensionExamples.length>0?[...extensionExamples]:[...fallbackNarrative.examples]:extensionExamples.length>0?[extensionExamples[0]]:[...fallbackNarrative.examples],tips:detailMode==="detailed"?extensionFailureHints.length>0?[...extensionFailureHints]:[...fallbackNarrative.tips]:[],detail_mode:detailMode}}function resolveJsonHelpNarrative(commandPath,commandDescription,detailMode,extensionDescriptor,hasPositionalAction){const isRootFallback=commandPath!==void 0&&resolveHelpBundleForPath(commandPath)===ROOT_HELP_BUNDLE,fallback=isRootFallback?{intent:commandDescription,examples:[`pm ${commandPath} --help`],tips:[],detail_mode:detailMode}:resolveHelpNarrative(commandPath,detailMode),intentSource=hasPositionalAction?"positional_action":extensionDescriptor?.intent||extensionDescriptor?.description?"extension":isRootFallback?commandDescription?"command_description":"unavailable":commandPath?"help_bundle":"root_help_bundle";return{narrative:buildJsonHelpNarrative(detailMode,fallback,extensionDescriptor),intentSource}}function resolveJsonHelpVisibilityTier(rootCommandPath,extensionDescriptor){return rootCommandPath===void 0?null:extensionDescriptor?.tier??resolvePmCommandVisibilityTier(rootCommandPath)}function resolveJsonHelpCapabilityFamily(rootCommandPath,extensionDescriptor){return rootCommandPath===void 0?null:extensionDescriptor?.family??resolvePmCommandCapabilityFamily(rootCommandPath)}function projectFullCommandAliases(rootProgram,targetCommand,fullDiscovery){if(!(targetCommand!==rootProgram||!fullDiscovery))return PM_COMMAND_ALIAS_CONTRACTS.map(contract=>({alias:contract.alias,canonical:contract.canonical,canonical_argv:[...contract.canonical_argv],available:resolveCommandFromPathTokens(rootProgram,contract.canonical.split(" "))!==null,lifecycle:contract.lifecycle,hidden:contract.hidden,deprecated:contract.lifecycle==="deprecated"}))}function buildPositionalActionHelpProjection(action,targetCommand,resolvedPath,allOptions,extensionDescriptors=new Map,includeAll=!1){if(!action){const argumentsList=buildHelpArgumentSummaries(targetCommand),registeredSubcommands=buildHelpSubcommandSummaries(targetCommand,extensionDescriptors,includeAll),registeredSubcommandNames=new Set(registeredSubcommands.map(({name})=>name));return{arguments:argumentsList,options:allOptions,subcommands:[...registeredSubcommands,...PM_POSITIONAL_ACTION_CONTRACTS.filter(({parent,action:name})=>parent===resolvedPath&&!registeredSubcommandNames.has(name)).map(({action:name,description})=>({name,aliases:[],description,tier:resolvePmCommandVisibilityTier(resolvedPath.split(" ")[0]),family:resolvePmCommandCapabilityFamily(resolvedPath.split(" ")[0])}))].sort((left,right)=>left.name.localeCompare(right.name)),usage:[resolvedPath,argumentsList.reduce((usage,argument)=>argument.required?usage.replace(`[${argument.name}${argument.variadic?"...":""}]`,`<${argument.name}${argument.variadic?"...":""}>`):usage,targetCommand.usage())].filter(token=>token.length>0).join(" ")}}const acceptedFlags=new Set(action.accepted_flags);return{arguments:action.slots.map(({name,required,variadic,value_kind:valueKind,polymorphic})=>({name,required,variadic,description:polymorphic?`Polymorphic ${valueKind} value; inspect the action contract before mutation.`:`${valueKind.replaceAll("_"," ")} value.`})),options:allOptions.filter(({long,aliases})=>long!==null&&acceptedFlags.has(long)||aliases.some(alias=>acceptedFlags.has(alias))),subcommands:[],usage:[action.command,...action.slots.map(({name,required,variadic})=>{const token=variadic?`${name}...`:name;return required?`<${token}>`:`[${token}]`})].join(" ")}}function buildJsonHelpPayload(rootProgram,targetCommand,argv,requestedPath,extensionDescriptors){const detailMode=resolveHelpDetailMode(argv),fullDiscovery=isFullHelpDiscovery(argv),commanderPath=normalizeHelpCommandPath(getCommandPath(targetCommand)),requestedCommandPath=normalizeHelpCommandPath(requestedPath.join(" ")),resolvedPath=requestedCommandPath.length>commanderPath.length?requestedCommandPath:commanderPath,positionalAction=resolvePmPositionalActionContract(resolvedPath),projectedPath=positionalAction?.command??commanderPath,commandPath=projectedPath.length>0?projectedPath:void 0,rootCommandPath=commandPath,extensionDescriptor=commandPath?extensionDescriptors.get(resolvePmCommandOperation(commandPath)):void 0,extensionSurface=commandPath?resolveExtensionCommandSurface(commandPath,extensionDescriptors,getPmCommandHelpVisibilityTier(targetCommand)!==void 0):void 0,{narrative,intentSource}=resolveJsonHelpNarrative(commandPath,targetCommand.description().trim(),detailMode,extensionDescriptor,positionalAction!==void 0),allOptionSummaries=compactHelpOptionAliases(mergeHelpOptionSummaries(buildHelpOptionSummaries(targetCommand),buildDynamicExtensionHelpOptionSummaries(extensionDescriptor))),projection=buildPositionalActionHelpProjection(positionalAction,targetCommand,projectedPath,allOptionSummaries,extensionDescriptors,fullDiscovery),fullCommandAliases=projectFullCommandAliases(rootProgram,targetCommand,fullDiscovery);return{format:"pm_help_v1",detail_mode:detailMode,root_command:rootProgram.name(),requested_path:requestedPath,resolved_path:projectedPath.length>0?projectedPath:rootProgram.name(),visibility_tier:resolveJsonHelpVisibilityTier(rootCommandPath,extensionSurface),capability_family:resolveJsonHelpCapabilityFamily(rootCommandPath,extensionSurface),description:positionalAction?.description??targetCommand.description(),usage:projection.usage,intent:positionalAction?.description??narrative.intent,intent_source:intentSource,examples:positionalAction?[positionalAction.example]:narrative.examples,tips:positionalAction?[formatPmPositionalActionFlagTip(positionalAction.accepted_flags)]:narrative.tips,arguments:projection.arguments,options:projection.options,subcommands:projection.subcommands,has_subcommands:projection.subcommands.length>0,...fullCommandAliases===void 0?{}:{command_aliases:fullCommandAliases}}}async function maybeRenderBootstrapJsonHelp(rootProgram,argv,extensionDescriptors,requestedArgv=argv){const bootstrapGlobal=parseBootstrapGlobalOptions(argv);if(!bootstrapGlobal.json)return!1;const helpRequest=parseBootstrapHelpRequest(argv);if(!helpRequest.requested)return!1;const targetCommand=resolveCommandFromPathTokens(rootProgram,helpRequest.commandPathTokens);if(!targetCommand){if(!bootstrapGlobal.quiet){const unknownMessage=`unknown command '${helpRequest.commandPathTokens.join(" ")}'`,runtimeContext=buildUnknownCommandGuidanceFromRuntime(unknownMessage,rootProgram,extensionDescriptors,argv),envelope=formatCommanderErrorForJson(unknownMessage,"help",BUILTIN_TYPE_HELP_VALUES,EXIT_CODE.USAGE,{...runtimeContext,attemptedCommand:renderAttemptedCommand(argv),normalizedInvocationArgs:[...argv],providedOptionFlags:extractProvidedOptionFlags(argv)}),output=bootstrapGlobal.tokenAccounting?attachOutputTokenAccounting(envelope,value=>`${JSON.stringify(value,null,2)}
 `):envelope;writeStderr(`${JSON.stringify(output,null,2)}
 `)}return process.exitCode=EXIT_CODE.USAGE,!0}if(!bootstrapGlobal.quiet){const payload=buildJsonHelpPayload(rootProgram,targetCommand,argv,helpRequest.commandPathTokens,extensionDescriptors),originalPath=parseBootstrapHelpRequest(requestedArgv).commandPathTokens;payload.requested_path=originalPath;const alias=resolvePmCommandAlias(originalPath.join(" "));alias&&(payload.resolved_path=alias.canonical),targetCommand===rootProgram&&!isFullHelpDiscovery(argv)&&(payload.omission_receipt={has_omissions:!0,omitted_field_group_count:1,omitted_field_groups:[{name:"command_aliases",restore_with:"--all"}]}),writeStdout(`${JSON.stringify(payload,null,2)}
 `)}return process.exitCode=EXIT_CODE.SUCCESS,!0}function buildCreateUpdatePolicyIntro(commandName,typeRegistry){const lines=["","Type-aware option policies:","  pass --type <value> with --help to render required/disabled/hidden option policy details for that type.",`  active type values: ${typeRegistry.types.join("|")}`];return commandName==="create"&&lines.push("  scheduling shortcut: use --schedule-preset lightweight for Reminder/Meeting/Event minimal create flows."),lines.join(`

package/dist/cli/invocation-profile.d.ts

@@ -7,14 +7,14 @@
 import type { Writable } from "node:stream";
 /** Minimal process boundary, also usable by embedded executable hosts. */
 interface InvocationProfileHost {
-    /** Register a callback after pending event-loop work and output drain. */
-    once(event: "beforeExit", listener: () => void): unknown;
-    /** Remove an unconsumed callback when an embedding host disposes it. */
-    off(event: "beforeExit", listener: () => void): unknown;
-    /** Monotonic seconds since runtime startup, including module initialization. */
-    uptime(): number;
-    /** Diagnostic destination; command output remains on stdout. */
-    stderr: Pick<Writable, "write">;
+/** Register a callback after pending event-loop work and output drain. */
+once(event: "beforeExit", listener: () => void): unknown;
+/** Remove an unconsumed callback when an embedding host disposes it. */
+off(event: "beforeExit", listener: () => void): unknown;
+/** Monotonic seconds since runtime startup, including module initialization. */
+uptime(): number;
+/** Diagnostic destination; command output remains on stdout. */
+stderr: Pick<Writable, "write">;
 }
 /**
  * Emit exactly one total when the process drains, even for help or refusals.

package/dist/cli/main.d.ts

@@ -18,35 +18,35 @@ import { buildPostActionTelemetryOutcome, inferPostActionErrorCode, inferPostAct
 declare function setActiveExtensionHookContextForTest(context: ActiveExtensionHookContext<MandatoryMigrationBlocker> | null): void;
 declare function setActiveRuntimeExtensionCommandDescriptorsForTest(descriptors: Map<string, ExtensionCommandHelpDescriptor>): void;
 interface RuntimeExtensionSnapshot {
-    hooks: ExtensionHookRegistry;
-    commands: ExtensionCommandRegistry;
-    parsers: ExtensionParserRegistry;
-    preflight: ExtensionPreflightRegistry;
-    services: ExtensionServiceRegistry;
-    renderers: ExtensionRendererRegistry;
-    registrations: ReturnType<typeof createEmptyExtensionRegistrationRegistry>;
-    pmRoot: string;
-    settings: PmSettings;
-    commandHandlers: string[];
-    commandFlagHelp: Map<string, string>;
-    commandDescriptors: Map<string, ExtensionCommandHelpDescriptor>;
-    commandAliases: Map<string, string>;
-    loadWarnings: string[];
-    activationWarnings: string[];
-    loadedCount: number;
-    loadFailedCount: number;
-    activationFailedCount: number;
-    contextIntentPackages: Array<{
-        name: string;
-        module: unknown;
-    }>;
+hooks: ExtensionHookRegistry;
+commands: ExtensionCommandRegistry;
+parsers: ExtensionParserRegistry;
+preflight: ExtensionPreflightRegistry;
+services: ExtensionServiceRegistry;
+renderers: ExtensionRendererRegistry;
+registrations: ReturnType<typeof createEmptyExtensionRegistrationRegistry>;
+pmRoot: string;
+settings: PmSettings;
+commandHandlers: string[];
+commandFlagHelp: Map<string, string>;
+commandDescriptors: Map<string, ExtensionCommandHelpDescriptor>;
+commandAliases: Map<string, string>;
+loadWarnings: string[];
+activationWarnings: string[];
+loadedCount: number;
+loadFailedCount: number;
+activationFailedCount: number;
+contextIntentPackages: Array<{
+name: string;
+module: unknown;
+}>;
 }
 interface RuntimeExtensionDiscoverySnapshot {
-    pmRoot: string;
-    settings: PmSettings;
-    discovery: ExtensionDiscoveryResult;
-    discoveryMs: number;
-    settingsReadWarnings: string[];
+pmRoot: string;
+settings: PmSettings;
+discovery: ExtensionDiscoveryResult;
+discoveryMs: number;
+settingsReadWarnings: string[];
 }
 declare function inferMissingFieldsFromErrorMessage(message: string): string[] | undefined;
 /** Build replayable recovery guidance after removing sensitive matcher values from every invocation representation. */
@@ -55,30 +55,30 @@ declare function runAndClearAfterCommandHooks(outcome: TelemetryCommandOutcome):
 declare function envFlagEnabled(key: string): boolean;
 declare function shouldLogHandledErrorToSentry(exitCode: number): boolean;
 declare function maybeLogHandledCliErrorToSentry(params: {
-    command: string;
-    error_code: string;
-    error_category: TelemetryErrorCategory;
-    exit_code: number;
-    error_message: string;
-    command_resolution?: TelemetryCommandResolution;
-    resolution_stage?: TelemetryResolutionStage;
-    source_context?: string;
+command: string;
+error_code: string;
+error_category: TelemetryErrorCategory;
+exit_code: number;
+error_message: string;
+command_resolution?: TelemetryCommandResolution;
+resolution_stage?: TelemetryResolutionStage;
+source_context?: string;
 }): Promise<boolean>;
 declare function handleGenericRunPmCliError(params: {
-    error: unknown;
-    attemptedCommand: string;
-    bootstrapGlobal: GlobalOptions;
-    emitTelemetryCommandError: (event: {
-        command: string;
-        errorCode: string;
-        errorMessage: string;
-        exitCode: number;
-        options: Record<string, unknown>;
-        resolutionStage: TelemetryResolutionStage;
-    }) => Promise<{
-        errorCategory: TelemetryErrorCategory;
-        commandResolution: TelemetryCommandResolution;
-    }>;
+error: unknown;
+attemptedCommand: string;
+bootstrapGlobal: GlobalOptions;
+emitTelemetryCommandError: (event: {
+command: string;
+errorCode: string;
+errorMessage: string;
+exitCode: number;
+options: Record<string, unknown>;
+resolutionStage: TelemetryResolutionStage;
+}) => Promise<{
+errorCategory: TelemetryErrorCategory;
+commandResolution: TelemetryCommandResolution;
+}>;
 }): Promise<void>;
 declare function toLooseFieldDefinitionType(fieldType: string): "string" | "number" | "boolean";
 declare function commandHasLongOption(command: Command, longFlag: string): boolean;
@@ -98,15 +98,16 @@ declare function emitExtensionSkippedProfile(profileEnabled: boolean | undefined
 declare function loadRuntimeExtensionDiscoverySnapshot(pmRoot: string, readSettingsWithMetadataFn?: typeof readSettingsWithMetadata): Promise<RuntimeExtensionDiscoverySnapshot | null>;
 declare function loadRuntimeExtensionSnapshot(pmRoot: string, probe?: RuntimeExtensionActivationProbe, readSettingsFn?: typeof readSettings): Promise<RuntimeExtensionSnapshot | null>;
 declare function maybeLoadRuntimeExtensions(command: Command): Promise<{
-    hooks: ExtensionHookRegistry;
-    commands: ExtensionCommandRegistry;
-    parsers: ExtensionParserRegistry;
-    preflight: ExtensionPreflightRegistry;
-    services: ExtensionServiceRegistry;
-    renderers: ExtensionRendererRegistry;
-    registrations: ReturnType<typeof createEmptyExtensionRegistrationRegistry>;
-    pmRoot: string;
+hooks: ExtensionHookRegistry;
+commands: ExtensionCommandRegistry;
+parsers: ExtensionParserRegistry;
+preflight: ExtensionPreflightRegistry;
+services: ExtensionServiceRegistry;
+renderers: ExtensionRendererRegistry;
+registrations: ReturnType<typeof createEmptyExtensionRegistrationRegistry>;
+pmRoot: string;
 } | null>;
+/** Load the complete installed registry for recovery without registering guessed command handlers. */
 declare function loadRuntimeExtensionCommandDescriptorsForRecovery(pmRoot: string): Promise<Map<string, ExtensionCommandHelpDescriptor>>;
 declare function executeRegisteredRuntimeMigrations(migrations: RegisteredExtensionSchemaMigrationDefinition[], pmRoot: string): Promise<string[]>;
 declare function runRequiredExtensionCommand(command: Command, options: Record<string, unknown>, globalOptions: GlobalOptions, extensionFlagDefinitions?: LooseCommandFlagDefinition[]): Promise<unknown>;
@@ -134,29 +135,29 @@ declare function registerDynamicExtensionCommandPaths(rootProgram: Command, invo
  */
 declare function ensureIdempotentTopLevelCommandRegistration(rootProgram: Command): void;
 type TelemetryCommandErrorEmitter = (params: {
-    command: string;
-    errorCode: string;
-    errorMessage: string;
-    exitCode: number;
-    options: Record<string, unknown>;
-    resolutionStage: TelemetryResolutionStage;
+command: string;
+errorCode: string;
+errorMessage: string;
+exitCode: number;
+options: Record<string, unknown>;
+resolutionStage: TelemetryResolutionStage;
 }) => Promise<{
-    errorCategory: TelemetryErrorCategory;
-    commandResolution: TelemetryCommandResolution;
+errorCategory: TelemetryErrorCategory;
+commandResolution: TelemetryCommandResolution;
 }>;
 interface RunPmCliErrorContext {
-    error: unknown;
-    invocationArgv: string[];
-    bootstrapGlobal: GlobalOptions;
-    jsonErrors: boolean;
-    bootstrapPmRoot: string;
-    attemptedCommand: string;
-    emitTelemetryCommandError: TelemetryCommandErrorEmitter;
+error: unknown;
+invocationArgv: string[];
+bootstrapGlobal: GlobalOptions;
+jsonErrors: boolean;
+bootstrapPmRoot: string;
+attemptedCommand: string;
+emitTelemetryCommandError: TelemetryCommandErrorEmitter;
 }
 declare function prepareExtensionServicesForRunPmCliError(params: {
-    invocationArgv: string[];
-    bootstrapGlobal: GlobalOptions;
-    bootstrapPmRoot: string;
+invocationArgv: string[];
+bootstrapGlobal: GlobalOptions;
+bootstrapPmRoot: string;
 }): Promise<void>;
 declare function setRecoveredExtensionServices(bootstrapSnapshot: Pick<RuntimeExtensionSnapshot, "services"> | null): void;
 declare function handleRunPmCliKnownError(context: RunPmCliErrorContext, numericExitCode: number | undefined): Promise<boolean>;
@@ -167,100 +168,100 @@ declare function handleRunPmCliCommanderUsageError(context: RunPmCliErrorContext
 declare function shouldHandleRunPmCliCommanderError(error: unknown): boolean;
 declare function handleRunPmCliCommanderError(context: RunPmCliErrorContext): Promise<void>;
 declare function handleRunPmCliError(params: {
-    error: unknown;
-    invocationArgv: string[];
+error: unknown;
+invocationArgv: string[];
 }): Promise<void>;
 /** Implements run pm cli for the public runtime surface of this module. */
 export declare function runPmCli(rawArgv?: string[]): Promise<void>;
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
 export declare const _testOnly: {
-    activationCommandMatchesProbe: typeof activationCommandMatchesProbe;
-    applyDynamicExtensionRootHelpVisibility: typeof applyDynamicExtensionRootHelpVisibility;
-    bootstrapProfileEnabled: typeof bootstrapProfileEnabled;
-    buildBootstrapActivationProbe: typeof buildBootstrapActivationProbe;
-    buildPostActionTelemetryOutcome: typeof buildPostActionTelemetryOutcome;
-    buildPmCliRecoveryContext: typeof buildPmCliRecoveryContext;
-    buildRuntimeExtensionDiscoverySnapshotCacheKey: typeof buildRuntimeExtensionDiscoverySnapshotCacheKey;
-    buildRuntimeExtensionActivationScope: typeof buildRuntimeExtensionActivationScope;
-    buildRuntimeExtensionSnapshotCacheKey: typeof buildRuntimeExtensionSnapshotCacheKey;
-    buildRuntimeExtensionFilterForProbe: typeof buildRuntimeExtensionFilterForProbe;
-    addRuntimeFieldOption: typeof addRuntimeFieldOption;
-    collectActivationCommandCandidates: typeof collectActivationCommandCandidates;
-    collectExtensionFlagDefinitionsForCommand: typeof collectExtensionFlagDefinitionsForCommand;
-    collectExtensionFlagDefinitionsForInvocation: typeof collectExtensionFlagDefinitionsForInvocation;
-    collectLeadingCommandArgs: typeof collectLeadingCommandArgs;
-    collectParsedActivationCommandArgs: typeof collectParsedActivationCommandArgs;
-    collectRuntimeFieldLooseFlagDefinitionsForCommand: typeof collectRuntimeFieldLooseFlagDefinitionsForCommand;
-    commandHasLongOption: typeof commandHasLongOption;
-    commandHasShortOption: typeof commandHasShortOption;
-    commandPathNeedsSearchExtensions: typeof commandPathNeedsSearchExtensions;
-    commandPathNeedsTemplateExtensions: typeof commandPathNeedsTemplateExtensions;
-    describeUnknownError: typeof describeUnknownError;
-    defaultPreflightDecision: typeof defaultPreflightDecision;
-    discoveryNeedsActivationForProbe: typeof discoveryNeedsActivationForProbe;
-    emitExtensionProfile: typeof emitExtensionProfile;
-    emitExtensionSkippedProfile: typeof emitExtensionSkippedProfile;
-    emitSettingsReadWarnings: typeof emitSettingsReadWarnings;
-    ensureIdempotentTopLevelCommandRegistration: typeof ensureIdempotentTopLevelCommandRegistration;
-    enforceExplicitRetryForFlagTypos: typeof enforceExplicitRetryForFlagTypos;
-    envFlagEnabled: typeof envFlagEnabled;
-    executeRegisteredRuntimeMigrations: typeof executeRegisteredRuntimeMigrations;
-    extractCommandScopedOptions: typeof extractCommandScopedOptions;
-    extensionActivationCommands: typeof extensionActivationCommands;
-    extensionCapabilities: typeof extensionCapabilities;
-    extensionNeedsActivationForProbe: typeof extensionNeedsActivationForProbe;
-    extensionProvidesTemplatesRuntime: typeof extensionProvidesTemplatesRuntime;
-    hasAnyCapability: typeof hasAnyCapability;
-    hasGlobalExtensionContributions: typeof hasGlobalExtensionContributions;
-    handleGenericRunPmCliError: typeof handleGenericRunPmCliError;
-    handleRunPmCliCommanderError: typeof handleRunPmCliCommanderError;
-    handleRunPmCliError: typeof handleRunPmCliError;
-    handleRunPmCliHelpDisplayError: typeof handleRunPmCliHelpDisplayError;
-    handleRunPmCliKnownError: typeof handleRunPmCliKnownError;
-    handleRunPmCliCommanderUsageError: typeof handleRunPmCliCommanderUsageError;
-    handleUnknownHelpCommandError: typeof handleUnknownHelpCommandError;
-    inferMissingFieldsFromErrorMessage: typeof inferMissingFieldsFromErrorMessage;
-    inferPostActionErrorCode: typeof inferPostActionErrorCode;
-    inferPostActionFailureMessage: typeof inferPostActionFailureMessage;
-    invocationRequestsVersion: typeof invocationRequestsVersion;
-    isCommanderError: typeof isCommanderError;
-    loadRuntimeExtensionCommandDescriptorsForRecovery: typeof loadRuntimeExtensionCommandDescriptorsForRecovery;
-    loadRuntimeExtensionDiscoverySnapshot: typeof loadRuntimeExtensionDiscoverySnapshot;
-    loadRuntimeExtensionSnapshot: typeof loadRuntimeExtensionSnapshot;
-    maybeLoadRuntimeExtensions: typeof maybeLoadRuntimeExtensions;
-    maybeAttachCreateUpdatePolicyHelpText: typeof maybeAttachCreateUpdatePolicyHelpText;
-    maybeLogHandledCliErrorToSentry: typeof maybeLogHandledCliErrorToSentry;
-    matchesStaticExtensionCommand: typeof matchesStaticExtensionCommand;
-    normalizeTelemetryCommandResolution: typeof normalizeTelemetryCommandResolution;
-    normalizeTelemetryErrorCategory: typeof normalizeTelemetryErrorCategory;
-    normalizeTelemetryResolutionStage: typeof normalizeTelemetryResolutionStage;
-    normalizeThrownExitCode: typeof normalizeThrownExitCode;
-    probeUsesAnyFlag: typeof probeUsesAnyFlag;
-    prepareExtensionServicesForRunPmCliError: typeof prepareExtensionServicesForRunPmCliError;
-    readRecordBoolean: typeof readRecordBoolean;
-    readRecordNumber: typeof readRecordNumber;
-    readRecordString: typeof readRecordString;
-    recordCliReadOutputInvocationProvenance: typeof recordCliReadOutputInvocationProvenance;
-    registerDynamicExtensionCommandPaths: typeof registerDynamicExtensionCommandPaths;
-    registerRuntimeSchemaFieldFlags: typeof registerRuntimeSchemaFieldFlags;
-    resolveCoreCommandRegistrationSelection: typeof resolveCoreCommandRegistrationSelection;
-    resolveStaticExtensionActivationDecision: typeof resolveStaticExtensionActivationDecision;
-    resolveUnknownHelpToken: typeof resolveUnknownCommanderToken;
-    readThrownExitCode: typeof readThrownExitCode;
-    runAndClearAfterCommandHooks: typeof runAndClearAfterCommandHooks;
-    runRequiredExtensionCommand: typeof runRequiredExtensionCommand;
-    shouldAttachRichHelpTextForInvocation: typeof shouldAttachRichHelpTextForInvocation;
-    shouldLogHandledErrorToSentry: typeof shouldLogHandledErrorToSentry;
-    shouldRegisterDynamicExtensionPaths: typeof shouldRegisterDynamicExtensionPaths;
-    shouldRegisterRuntimeSchemaFlags: typeof shouldRegisterRuntimeSchemaFlags;
-    shouldHandleRunPmCliCommanderError: typeof shouldHandleRunPmCliCommanderError;
-    setActiveExtensionHookContextForTest: typeof setActiveExtensionHookContextForTest;
-    setActiveRuntimeExtensionCommandDescriptorsForTest: typeof setActiveRuntimeExtensionCommandDescriptorsForTest;
-    setRecoveredExtensionServices: typeof setRecoveredExtensionServices;
-    toLooseFieldDefinitionType: typeof toLooseFieldDefinitionType;
-    isImporterOrExporterCommandPath: typeof isImporterOrExporterCommandPath;
-    validateDynamicExtensionCommandInvocation: typeof validateDynamicExtensionCommandInvocation;
-    wrapProgramActionsForExtensionHandlers: typeof wrapProgramActionsForExtensionHandlers;
-    wrapThrownErrorForSentry: typeof wrapThrownErrorForSentry;
+activationCommandMatchesProbe: typeof activationCommandMatchesProbe;
+applyDynamicExtensionRootHelpVisibility: typeof applyDynamicExtensionRootHelpVisibility;
+bootstrapProfileEnabled: typeof bootstrapProfileEnabled;
+buildBootstrapActivationProbe: typeof buildBootstrapActivationProbe;
+buildPostActionTelemetryOutcome: typeof buildPostActionTelemetryOutcome;
+buildPmCliRecoveryContext: typeof buildPmCliRecoveryContext;
+buildRuntimeExtensionDiscoverySnapshotCacheKey: typeof buildRuntimeExtensionDiscoverySnapshotCacheKey;
+buildRuntimeExtensionActivationScope: typeof buildRuntimeExtensionActivationScope;
+buildRuntimeExtensionSnapshotCacheKey: typeof buildRuntimeExtensionSnapshotCacheKey;
+buildRuntimeExtensionFilterForProbe: typeof buildRuntimeExtensionFilterForProbe;
+addRuntimeFieldOption: typeof addRuntimeFieldOption;
+collectActivationCommandCandidates: typeof collectActivationCommandCandidates;
+collectExtensionFlagDefinitionsForCommand: typeof collectExtensionFlagDefinitionsForCommand;
+collectExtensionFlagDefinitionsForInvocation: typeof collectExtensionFlagDefinitionsForInvocation;
+collectLeadingCommandArgs: typeof collectLeadingCommandArgs;
+collectParsedActivationCommandArgs: typeof collectParsedActivationCommandArgs;
+collectRuntimeFieldLooseFlagDefinitionsForCommand: typeof collectRuntimeFieldLooseFlagDefinitionsForCommand;
+commandHasLongOption: typeof commandHasLongOption;
+commandHasShortOption: typeof commandHasShortOption;
+commandPathNeedsSearchExtensions: typeof commandPathNeedsSearchExtensions;
+commandPathNeedsTemplateExtensions: typeof commandPathNeedsTemplateExtensions;
+describeUnknownError: typeof describeUnknownError;
+defaultPreflightDecision: typeof defaultPreflightDecision;
+discoveryNeedsActivationForProbe: typeof discoveryNeedsActivationForProbe;
+emitExtensionProfile: typeof emitExtensionProfile;
+emitExtensionSkippedProfile: typeof emitExtensionSkippedProfile;
+emitSettingsReadWarnings: typeof emitSettingsReadWarnings;
+ensureIdempotentTopLevelCommandRegistration: typeof ensureIdempotentTopLevelCommandRegistration;
+enforceExplicitRetryForFlagTypos: typeof enforceExplicitRetryForFlagTypos;
+envFlagEnabled: typeof envFlagEnabled;
+executeRegisteredRuntimeMigrations: typeof executeRegisteredRuntimeMigrations;
+extractCommandScopedOptions: typeof extractCommandScopedOptions;
+extensionActivationCommands: typeof extensionActivationCommands;
+extensionCapabilities: typeof extensionCapabilities;
+extensionNeedsActivationForProbe: typeof extensionNeedsActivationForProbe;
+extensionProvidesTemplatesRuntime: typeof extensionProvidesTemplatesRuntime;
+hasAnyCapability: typeof hasAnyCapability;
+hasGlobalExtensionContributions: typeof hasGlobalExtensionContributions;
+handleGenericRunPmCliError: typeof handleGenericRunPmCliError;
+handleRunPmCliCommanderError: typeof handleRunPmCliCommanderError;
+handleRunPmCliError: typeof handleRunPmCliError;
+handleRunPmCliHelpDisplayError: typeof handleRunPmCliHelpDisplayError;
+handleRunPmCliKnownError: typeof handleRunPmCliKnownError;
+handleRunPmCliCommanderUsageError: typeof handleRunPmCliCommanderUsageError;
+handleUnknownHelpCommandError: typeof handleUnknownHelpCommandError;
+inferMissingFieldsFromErrorMessage: typeof inferMissingFieldsFromErrorMessage;
+inferPostActionErrorCode: typeof inferPostActionErrorCode;
+inferPostActionFailureMessage: typeof inferPostActionFailureMessage;
+invocationRequestsVersion: typeof invocationRequestsVersion;
+isCommanderError: typeof isCommanderError;
+loadRuntimeExtensionCommandDescriptorsForRecovery: typeof loadRuntimeExtensionCommandDescriptorsForRecovery;
+loadRuntimeExtensionDiscoverySnapshot: typeof loadRuntimeExtensionDiscoverySnapshot;
+loadRuntimeExtensionSnapshot: typeof loadRuntimeExtensionSnapshot;
+maybeLoadRuntimeExtensions: typeof maybeLoadRuntimeExtensions;
+maybeAttachCreateUpdatePolicyHelpText: typeof maybeAttachCreateUpdatePolicyHelpText;
+maybeLogHandledCliErrorToSentry: typeof maybeLogHandledCliErrorToSentry;
+matchesStaticExtensionCommand: typeof matchesStaticExtensionCommand;
+normalizeTelemetryCommandResolution: typeof normalizeTelemetryCommandResolution;
+normalizeTelemetryErrorCategory: typeof normalizeTelemetryErrorCategory;
+normalizeTelemetryResolutionStage: typeof normalizeTelemetryResolutionStage;
+normalizeThrownExitCode: typeof normalizeThrownExitCode;
+probeUsesAnyFlag: typeof probeUsesAnyFlag;
+prepareExtensionServicesForRunPmCliError: typeof prepareExtensionServicesForRunPmCliError;
+readRecordBoolean: typeof readRecordBoolean;
+readRecordNumber: typeof readRecordNumber;
+readRecordString: typeof readRecordString;
+recordCliReadOutputInvocationProvenance: typeof recordCliReadOutputInvocationProvenance;
+registerDynamicExtensionCommandPaths: typeof registerDynamicExtensionCommandPaths;
+registerRuntimeSchemaFieldFlags: typeof registerRuntimeSchemaFieldFlags;
+resolveCoreCommandRegistrationSelection: typeof resolveCoreCommandRegistrationSelection;
+resolveStaticExtensionActivationDecision: typeof resolveStaticExtensionActivationDecision;
+resolveUnknownHelpToken: typeof resolveUnknownCommanderToken;
+readThrownExitCode: typeof readThrownExitCode;
+runAndClearAfterCommandHooks: typeof runAndClearAfterCommandHooks;
+runRequiredExtensionCommand: typeof runRequiredExtensionCommand;
+shouldAttachRichHelpTextForInvocation: typeof shouldAttachRichHelpTextForInvocation;
+shouldLogHandledErrorToSentry: typeof shouldLogHandledErrorToSentry;
+shouldRegisterDynamicExtensionPaths: typeof shouldRegisterDynamicExtensionPaths;
+shouldRegisterRuntimeSchemaFlags: typeof shouldRegisterRuntimeSchemaFlags;
+shouldHandleRunPmCliCommanderError: typeof shouldHandleRunPmCliCommanderError;
+setActiveExtensionHookContextForTest: typeof setActiveExtensionHookContextForTest;
+setActiveRuntimeExtensionCommandDescriptorsForTest: typeof setActiveRuntimeExtensionCommandDescriptorsForTest;
+setRecoveredExtensionServices: typeof setRecoveredExtensionServices;
+toLooseFieldDefinitionType: typeof toLooseFieldDefinitionType;
+isImporterOrExporterCommandPath: typeof isImporterOrExporterCommandPath;
+validateDynamicExtensionCommandInvocation: typeof validateDynamicExtensionCommandInvocation;
+wrapProgramActionsForExtensionHandlers: typeof wrapProgramActionsForExtensionHandlers;
+wrapThrownErrorForSentry: typeof wrapThrownErrorForSentry;
 };
 export {};