@unbrained/pm-cli 2026.10.12 → 2026.10.14

package/dist/cli/extension-command-help.d.ts

@@ -8,89 +8,89 @@ import { type FlagDefinition, type RegisteredExtensionCommandDefinition, type Re
 import type { PmCommandCapabilityFamily, PmCommandVisibilityTier } from "../sdk/agent-capability-contracts.js";
 /** Documents the extension command argument help descriptor payload exchanged by command, SDK, and package integrations. */
 export interface ExtensionCommandArgumentHelpDescriptor {
-    /** 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;
+/** 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;
 }
 /** Documents the extension command help descriptor payload exchanged by command, SDK, and package integrations. */
 export interface ExtensionCommandHelpDescriptor {
-    /** Value that configures or reports command for this contract. */
-    command: string;
-    /** Value that configures or reports action for this contract. */
-    action: string;
-    /** Value that configures or reports description for this contract. */
-    description?: string;
-    /** Value that configures or reports intent for this contract. */
-    intent?: string;
-    /** Value that configures or reports examples for this contract. */
-    examples: string[];
-    /** Value that configures or reports failure hints for this contract. */
-    failure_hints: string[];
-    /** Value that configures or reports arguments for this contract. */
-    arguments: ExtensionCommandArgumentHelpDescriptor[];
-    /** Value that configures or reports flags for this contract. */
-    flags: FlagDefinition[];
-    /** Minimum agent surface tier declared by the package. */
-    tier: PmCommandVisibilityTier;
-    /** Capability family declared by the package. */
-    family: PmCommandCapabilityFamily;
-    /** Value that configures or reports source for this contract. */
-    source?: {
-        layer: "global" | "project";
-        name: string;
-        package?: string;
-    };
+/** Value that configures or reports command for this contract. */
+command: string;
+/** Value that configures or reports action for this contract. */
+action: string;
+/** Value that configures or reports description for this contract. */
+description?: string;
+/** Value that configures or reports intent for this contract. */
+intent?: string;
+/** Value that configures or reports examples for this contract. */
+examples: string[];
+/** Value that configures or reports failure hints for this contract. */
+failure_hints: string[];
+/** Value that configures or reports arguments for this contract. */
+arguments: ExtensionCommandArgumentHelpDescriptor[];
+/** Value that configures or reports flags for this contract. */
+flags: FlagDefinition[];
+/** Minimum agent surface tier declared by the package. */
+tier: PmCommandVisibilityTier;
+/** Capability family declared by the package. */
+family: PmCommandCapabilityFamily;
+/** Value that configures or reports source for this contract. */
+source?: {
+layer: "global" | "project";
+name: string;
+package?: string;
+};
 }
 /** Documents the help option summary payload exchanged by command, SDK, and package integrations. */
 export interface HelpOptionSummary {
-    /** Value that configures or reports flags for this contract. */
-    flags: string;
-    /** Value that configures or reports long for this contract. */
-    long: string | null;
-    /** Value that configures or reports short for this contract. */
-    short: string | null;
-    /** Value that configures or reports description for this contract. */
-    description: string;
-    /** Value that configures or reports takes value for this contract. */
-    takes_value: boolean;
-    /** Value that configures or reports value required for this contract. */
-    value_required: boolean;
-    /** Value that configures or reports value name for this contract. */
-    value_name: string | null;
-    /** Value that configures or reports variadic for this contract. */
-    variadic: boolean;
-    /** Value that configures or reports required for this contract. */
-    required: boolean;
-    /** Value that configures or reports aliases for this contract. */
-    aliases: string[];
-    /** Value that configures or reports alias for for this contract. */
-    alias_for: string | null;
-    /** Fallback value used when callers do not provide an override. */
-    default_value?: unknown;
+/** Value that configures or reports flags for this contract. */
+flags: string;
+/** Value that configures or reports long for this contract. */
+long: string | null;
+/** Value that configures or reports short for this contract. */
+short: string | null;
+/** Value that configures or reports description for this contract. */
+description: string;
+/** Value that configures or reports takes value for this contract. */
+takes_value: boolean;
+/** Value that configures or reports value required for this contract. */
+value_required: boolean;
+/** Value that configures or reports value name for this contract. */
+value_name: string | null;
+/** Value that configures or reports variadic for this contract. */
+variadic: boolean;
+/** Value that configures or reports required for this contract. */
+required: boolean;
+/** Value that configures or reports aliases for this contract. */
+aliases: string[];
+/** Value that configures or reports alias for for this contract. */
+alias_for: string | null;
+/** Fallback value used when callers do not provide an override. */
+default_value?: unknown;
 }
 /** Implements normalize extension command path for the public runtime surface of this module. */
 export declare function normalizeExtensionCommandPath(commandPath: string): string;
 /** Build verified flattened-alias mappings within one extension and layer. */
 export declare function buildCanonicalExtensionAliases(handlers: ReadonlyArray<{
-    command: string;
-    layer: "project" | "global";
-    name: string;
+command: string;
+layer: "project" | "global";
+name: string;
 }>, definitions: ReadonlyArray<{
-    command: string;
-    layer: "project" | "global";
-    name: string;
+command: string;
+layer: "project" | "global";
+name: string;
 }>): Map<string, string>;
 /** Resolve whether a registered extension flag consumes a value. */
 export declare function extensionFlagTakesValueForInvocation(invocationArgv: string[], commandName: string | undefined, normalizedMissing: string | undefined, descriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>): boolean | undefined;
 /** Canonical value-arity contract shared by extension invocation recovery, Commander parsing, and structured help. */
 export declare function resolveExtensionFlagArity(definition: Readonly<FlagDefinition>): {
-    takesValue: boolean;
-    valueName: string | null;
+takesValue: boolean;
+valueName: string | null;
 };
 /** Implements collect dynamic extension flag help by command for the public runtime surface of this module. */
 export declare function collectDynamicExtensionFlagHelpByCommand(registrations: RegisteredExtensionFlagDefinitions[]): Map<string, string>;
@@ -125,8 +125,8 @@ export declare function findCommandByPath(root: Command, pathParts: string[]): C
 export declare function ensureCommandPath(root: Command, pathParts: string[]): Command | null;
 /** Locate core leaves that a path would replace or extend; existing groups can host unique extension leaves. */
 export declare function findExtensionCommandPathCollision(root: Command, pathParts: string[]): {
-    core_path: string;
-    extension_path: string;
+core_path: string;
+extension_path: string;
 } | null;
 /** Build an ownership-rich warning when an extension alias would shadow or graft beneath a core command. */
 export declare function buildExtensionCommandCollisionWarning(root: Command, commandPath: string, aliases: ReadonlyMap<string, string>, descriptor: ExtensionCommandHelpDescriptor | undefined, hasHandler?: boolean): string | null;

package/dist/cli/extension-command-help.js

@@ -1,7 +1,7 @@
-(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]="1f0aec6a-0db1-5a10-b61f-e3b2eb0d9518")}catch{}})();import{Option}from"commander";import{PM_RELOCATED_COMMAND_ALIASES}from"../sdk/cli-contracts/command-aliases.js";function normalizeExtensionCommandPath(commandPath){return commandPath.trim().toLowerCase().split(/\s+/).filter(part=>part.length>0).join(" ")}function buildCanonicalExtensionAliases(handlers,definitions){const aliases=new Map;for(const handler of handlers){const alias=normalizeExtensionCommandPath(handler.command);for(const definition of definitions){if(definition.layer!==handler.layer||definition.name!==handler.name)continue;const canonical=normalizeExtensionCommandPath(definition.command),parts=canonical.split(" "),action=parts.at(-1),suffix=parts.slice(1).join(" "),expectedAlias=suffix?`${parts[0]}-${action} ${suffix}`:`${parts[0]}-${action}`;if(action&&alias===expectedAlias){aliases.set(alias,canonical);break}}}return aliases}function extensionFlagTakesValueForInvocation(invocationArgv,commandName,normalizedMissing,descriptors){if(!commandName||!normalizedMissing)return;let descriptor,matchedTokenCount=0;for(const[index,token]of invocationArgv.entries()){if(token!==commandName)continue;const commandTokens=invocationArgv.slice(index);for(const[path,candidate]of descriptors.entries()){const pathTokens=path.split(" ");pathTokens.length>matchedTokenCount&&pathTokens.every((pathToken,pathIndex)=>commandTokens[pathIndex]===pathToken)&&(descriptor=candidate,matchedTokenCount=pathTokens.length)}}const flag=descriptor?.flags.find(candidate=>candidate.long===normalizedMissing||candidate.short===normalizedMissing);if(flag)return resolveExtensionFlagArity(flag).takesValue}function toNonEmptyFlagString(value){if(typeof value!="string")return null;const trimmed=value.trim();return trimmed.length>0?trimmed:null}function toOptionalBoolean(value){return typeof value=="boolean"?value:void 0}function resolveExtensionFlagArity(definition){const valueType=toNonEmptyFlagString(definition.value_type)??toNonEmptyFlagString(definition.type),declaredValueName=toNonEmptyFlagString(definition.value_name),takesValue=valueType!=="boolean"&&(declaredValueName!==null||valueType!==null||toOptionalBoolean(definition.required)===!0||toOptionalBoolean(definition.list)===!0);return{takesValue,valueName:takesValue?declaredValueName??"value":null}}function formatDynamicExtensionFlagHelpLine(definition){if(toOptionalBoolean(definition.visible)===!1)return null;const longName=toNonEmptyFlagString(definition.long);if(!longName||!longName.startsWith("--")||longName.length<3)return null;const shortName=toNonEmptyFlagString(definition.short),shortPrefix=shortName&&shortName.startsWith("-")&&!shortName.startsWith("--")?`${shortName}, `:"",valueName=toNonEmptyFlagString(definition.value_name),valueSuffix=valueName?` <${valueName}>`:"",description=toNonEmptyFlagString(definition.description)??"Extension-provided option.",markers=[];toOptionalBoolean(definition.required)===!0&&markers.push("required"),toOptionalBoolean(definition.enabled)===!1&&markers.push("disabled");const markerSuffix=markers.length>0?` [${markers.join(", ")}]`:"";return`${shortPrefix}${longName}${valueSuffix}  ${description}${markerSuffix}`}function buildDynamicExtensionFlagHelp(definitions){const lines=[...new Set(definitions.map(formatDynamicExtensionFlagHelpLine).filter(line=>line!==null))].sort((left,right)=>left.localeCompare(right));return lines.length===0?null:`
+(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]="9660f056-6719-5689-b9ad-d0fc689b6a89")}catch{}})();import{Option}from"commander";import{PM_RELOCATED_COMMAND_ALIASES}from"../sdk/cli-contracts/command-aliases.js";import{parseExtensionLongFlagToken,resolveExtensionLongFlagName,resolveFlagValueKind}from"../sdk/runtime-primitives.js";function normalizeExtensionCommandPath(commandPath){return commandPath.trim().toLowerCase().split(/\s+/).filter(part=>part.length>0).join(" ")}function buildCanonicalExtensionAliases(handlers,definitions){const aliases=new Map;for(const handler of handlers){const alias=normalizeExtensionCommandPath(handler.command);for(const definition of definitions){if(definition.layer!==handler.layer||definition.name!==handler.name)continue;const canonical=normalizeExtensionCommandPath(definition.command),parts=canonical.split(" "),action=parts.at(-1),suffix=parts.slice(1).join(" "),expectedAlias=suffix?`${parts[0]}-${action} ${suffix}`:`${parts[0]}-${action}`;if(action&&alias===expectedAlias){aliases.set(alias,canonical);break}}}return aliases}function extensionFlagTakesValueForInvocation(invocationArgv,commandName,normalizedMissing,descriptors){if(!commandName||!normalizedMissing)return;let descriptor,matchedTokenCount=0;for(const[index,token]of invocationArgv.entries()){if(token!==commandName)continue;const commandTokens=invocationArgv.slice(index);for(const[path,candidate]of descriptors.entries()){const pathTokens=path.split(" ");pathTokens.length>matchedTokenCount&&pathTokens.every((pathToken,pathIndex)=>commandTokens[pathIndex]===pathToken)&&(descriptor=candidate,matchedTokenCount=pathTokens.length)}}const flag=descriptor?.flags.find(candidate=>candidate.long===normalizedMissing||candidate.short===normalizedMissing);if(flag)return resolveExtensionFlagArity(flag).takesValue}function toNonEmptyFlagString(value){if(typeof value!="string")return null;const trimmed=value.trim();return trimmed.length>0?trimmed:null}function toOptionalBoolean(value){return typeof value=="boolean"?value:void 0}function resolveExtensionFlagArity(definition){const declaredValueType=toNonEmptyFlagString(definition.value_type)??toNonEmptyFlagString(definition.type),valueType=resolveFlagValueKind(declaredValueType)??declaredValueType,declaredValueName=toNonEmptyFlagString(definition.value_name),inlineValueName=parseExtensionLongFlagToken(definition.long)?.valueName,takesValue=valueType!=="boolean"&&(declaredValueName!==null||inlineValueName!=null||valueType!==null||toOptionalBoolean(definition.required)===!0||toOptionalBoolean(definition.list)===!0);return{takesValue,valueName:takesValue?declaredValueName??inlineValueName??"value":null}}function formatDynamicExtensionFlagHelpLine(definition){const longName=resolveExtensionLongFlagName(definition.long);if(!longName||!longName.startsWith("--")||longName.length<3)return null;const flags=formatDynamicExtensionOptionFlags(definition);if(!flags)return null;const description=toNonEmptyFlagString(definition.description)??"Extension-provided option.",markers=[];toOptionalBoolean(definition.required)===!0&&markers.push("required"),toOptionalBoolean(definition.enabled)===!1&&markers.push("disabled");const markerSuffix=markers.length>0?` [${markers.join(", ")}]`:"";return`${flags}  ${description}${markerSuffix}`}function buildDynamicExtensionFlagHelp(definitions){const lines=[...new Set(definitions.map(formatDynamicExtensionFlagHelpLine).filter(line=>line!==null))].sort((left,right)=>left.localeCompare(right));return lines.length===0?null:`
 Extension-provided flags:
   ${lines.join(`
-  `)}`}function collectDynamicExtensionFlagHelpByCommand(registrations){const grouped=new Map;for(const registration of registrations){const commandPath=normalizeExtensionCommandPath(registration.target_command);if(commandPath.length===0)continue;const existing=grouped.get(commandPath)??[];existing.push(...registration.flags),grouped.set(commandPath,existing)}const entries=[...grouped.entries()].sort(([left],[right])=>left.localeCompare(right)),helpByCommand=new Map;for(const[commandPath,definitions]of entries){const helpText=buildDynamicExtensionFlagHelp(definitions);helpText&&helpByCommand.set(commandPath,helpText)}return helpByCommand}function normalizeExtensionCommandAction(commandPath,action){return typeof action!="string"||action.trim().length===0?commandPath.replace(/\s+/g,"-"):action.trim().toLowerCase()}function normalizeExtensionCommandStringList(values){if(!Array.isArray(values))return[];const normalized=[],seen=new Set;for(const value of values){if(typeof value!="string")continue;const trimmed=value.trim();trimmed.length===0||seen.has(trimmed)||(seen.add(trimmed),normalized.push(trimmed))}return normalized}function normalizeExtensionCommandArguments(values){return Array.isArray(values)?values.map(value=>{const name=typeof value.name=="string"?value.name.trim():"";if(name.length===0)return null;const normalized={name,required:value.required===!0,variadic:value.variadic===!0};return typeof value.description=="string"&&value.description.trim().length>0&&(normalized.description=value.description.trim()),normalized}).filter(entry=>entry!==null):[]}function collectExtensionDefinitionsByCommand(commandDefinitions){const definitionsByCommand=new Map;for(const definition of commandDefinitions){const commandPath=normalizeExtensionCommandPath(definition.command);if(commandPath.length===0)continue;const description=typeof definition.description=="string"&&definition.description.trim().length>0?definition.description.trim():void 0,intent=typeof definition.intent=="string"&&definition.intent.trim().length>0?definition.intent.trim():void 0;definitionsByCommand.set(commandPath,{command:commandPath,action:normalizeExtensionCommandAction(commandPath,definition.action),description,intent,examples:normalizeExtensionCommandStringList(definition.examples),failure_hints:normalizeExtensionCommandStringList(definition.failure_hints),arguments:normalizeExtensionCommandArguments(definition.arguments),flags:[],tier:definition.tier??"standard",family:definition.family??"extensions",source:{layer:definition.layer,name:definition.name,package:definition.source_package}})}return definitionsByCommand}function collectExtensionFlagsByCommand(flagRegistrations){const flagsByCommand=new Map;for(const registration of flagRegistrations){const commandPath=normalizeExtensionCommandPath(registration.target_command);if(commandPath.length===0)continue;const existing=flagsByCommand.get(commandPath)??[];existing.push(...registration.flags),flagsByCommand.set(commandPath,existing)}return flagsByCommand}function collectExtensionHelpCommandSet(commandHandlers,definitionsByCommand,flagsByCommand){const commandSet=new Set;for(const commandPath of commandHandlers){const normalized=normalizeExtensionCommandPath(commandPath);normalized.length>0&&commandSet.add(normalized)}for(const commandPath of definitionsByCommand.keys())commandSet.add(commandPath);for(const commandPath of flagsByCommand.keys())commandSet.add(commandPath);return commandSet}function resolveFlattenedAliasDescriptor(commandPath,definitionsByCommand,canonicalAliases){const canonical=canonicalAliases.get(commandPath);return canonical?definitionsByCommand.get(canonical):void 0}function collectExtensionCommandHelpDescriptors(commandHandlers,commandDefinitions,flagRegistrations,canonicalAliases=new Map){const definitionsByCommand=collectExtensionDefinitionsByCommand(commandDefinitions),flagsByCommand=collectExtensionFlagsByCommand(flagRegistrations),commandSet=collectExtensionHelpCommandSet(commandHandlers,definitionsByCommand,flagsByCommand),descriptors=new Map,sortedCommands=[...commandSet].sort((left,right)=>left.localeCompare(right));for(const commandPath of sortedCommands){const definition=resolveFlattenedAliasDescriptor(commandPath,definitionsByCommand,canonicalAliases)??definitionsByCommand.get(commandPath),flags=flagsByCommand.get(commandPath)??(definition?flagsByCommand.get(definition.command):void 0)??[];if(definition){descriptors.set(commandPath,{...definition,command:commandPath,flags});continue}descriptors.set(commandPath,{command:commandPath,action:normalizeExtensionCommandAction(commandPath,void 0),examples:[],failure_hints:[],arguments:[],flags,tier:"standard",family:"extensions"})}return descriptors}function buildExtensionArgumentToken(argument){const variadicSuffix=argument.variadic?"...":"";return argument.required?`<${argument.name}${variadicSuffix}>`:`[${argument.name}${variadicSuffix}]`}function applyDynamicExtensionArguments(command,descriptor){for(const argument of descriptor.arguments)command.argument(buildExtensionArgumentToken(argument),argument.description??"Extension argument.")}function normalizeDynamicExtensionOptionNames(definition){if(toOptionalBoolean(definition.visible)===!1)return null;const longName=toNonEmptyFlagString(definition.long),shortName=toNonEmptyFlagString(definition.short),normalizedShort=shortName&&shortName.startsWith("-")&&!shortName.startsWith("--")?shortName:null,normalizedLong=longName&&longName.startsWith("--")&&longName.length>2?longName:null,optionNames=[normalizedShort,normalizedLong].filter(entry=>entry!==null);return optionNames.length>0?optionNames:null}function formatDynamicExtensionOptionFlags(definition){const optionNames=normalizeDynamicExtensionOptionNames(definition);if(!optionNames)return null;const{valueName}=resolveExtensionFlagArity(definition),optionValueSuffix=valueName?` <${valueName}>`:"";return`${optionNames.join(", ")}${optionValueSuffix}`}function formatDynamicExtensionParseOptionFlags(definition){const optionNames=normalizeDynamicExtensionOptionNames(definition);if(!optionNames)return null;const{valueName}=resolveExtensionFlagArity(definition),valueSuffix=valueName?` <${valueName}>`:"";return`${optionNames.join(", ")}${valueSuffix}`}function formatDynamicExtensionOptionDescription(definition){const description=toNonEmptyFlagString(definition.description)??"Extension-provided option.",markers=[];toOptionalBoolean(definition.required)===!0&&markers.push("required"),toOptionalBoolean(definition.enabled)===!1&&markers.push("disabled");const markerSuffix=markers.length>0?` [${markers.join(", ")}]`:"";return`${description}${markerSuffix}`}function commandAlreadyHasOption(command,definition){const longName=toNonEmptyFlagString(definition.long),shortName=toNonEmptyFlagString(definition.short);return command.options.some(option=>{const optionWithNames=option;return longName!==null&&optionWithNames.long===longName||shortName!==null&&optionWithNames.short===shortName})}function applyDynamicExtensionFlagOptions(command,definitions){for(const definition of definitions){if(commandAlreadyHasOption(command,definition))continue;const flags=formatDynamicExtensionParseOptionFlags(definition);if(!flags)continue;const description=formatDynamicExtensionOptionDescription(definition),option=new Option(flags,description);if(option.negate=!1,definition.list!==!0){command.addOption(option);continue}command.addOption(option.argParser((value,previous=[])=>[...Array.isArray(previous)?previous:[previous],value]))}}function buildResidualDynamicExtensionFlagHelp(command,definitions){return buildDynamicExtensionFlagHelp(definitions.filter(definition=>!commandAlreadyHasOption(command,definition)))}function buildDynamicExtensionHelpOptionSummary(definition){const flags=formatDynamicExtensionOptionFlags(definition);if(!flags)return null;const longName=toNonEmptyFlagString(definition.long),shortName=toNonEmptyFlagString(definition.short),normalizedLong=longName&&longName.startsWith("--")&&longName.length>2?longName:null,normalizedShort=shortName&&shortName.startsWith("-")&&!shortName.startsWith("--")?shortName:null,{takesValue,valueName}=resolveExtensionFlagArity(definition),required=toOptionalBoolean(definition.required)===!0;return{flags,long:normalizedLong,short:normalizedShort,description:formatDynamicExtensionOptionDescription(definition),takes_value:takesValue,value_required:takesValue,value_name:valueName,variadic:!1,required,aliases:[],alias_for:null}}function buildDynamicExtensionHelpOptionSummaries(descriptor){if(!descriptor)return[];const summaries=[],seen=new Set;for(const definition of descriptor.flags){const summary=buildDynamicExtensionHelpOptionSummary(definition);!summary||seen.has(summary.flags)||(seen.add(summary.flags),summaries.push(summary))}return summaries}function mergeHelpOptionSummaries(base,extension){if(extension.length===0)return base;const merged=[...base],seen=new Set(base.map(entry=>entry.flags));for(const entry of extension)seen.has(entry.flags)||(seen.add(entry.flags),merged.push(entry));return merged}function buildDynamicExtensionCommandMetadataHelp(descriptor){const lines=[];if(descriptor.intent&&lines.push(`Intent: ${descriptor.intent}`),descriptor.action&&lines.push(`Action contract: ${descriptor.action}`),descriptor.examples.length>0){lines.push("Examples:");for(const example of descriptor.examples)lines.push(`  - ${example}`)}if(descriptor.failure_hints.length>0){lines.push("Common failure hints:");for(const hint of descriptor.failure_hints)lines.push(`  - ${hint}`)}return lines.length===0?null:`
+  `)}`}function collectDynamicExtensionFlagHelpByCommand(registrations){const grouped=new Map;for(const registration of registrations){const commandPath=normalizeExtensionCommandPath(registration.target_command);if(commandPath.length===0)continue;const existing=grouped.get(commandPath)??[];existing.push(...registration.flags),grouped.set(commandPath,existing)}const entries=[...grouped.entries()].sort(([left],[right])=>left.localeCompare(right)),helpByCommand=new Map;for(const[commandPath,definitions]of entries){const helpText=buildDynamicExtensionFlagHelp(definitions);helpText&&helpByCommand.set(commandPath,helpText)}return helpByCommand}function normalizeExtensionCommandAction(commandPath,action){return typeof action!="string"||action.trim().length===0?commandPath.replace(/\s+/g,"-"):action.trim().toLowerCase()}function normalizeExtensionCommandStringList(values){if(!Array.isArray(values))return[];const normalized=[],seen=new Set;for(const value of values){if(typeof value!="string")continue;const trimmed=value.trim();trimmed.length===0||seen.has(trimmed)||(seen.add(trimmed),normalized.push(trimmed))}return normalized}function normalizeExtensionCommandArguments(values){return Array.isArray(values)?values.map(value=>{const name=typeof value.name=="string"?value.name.trim():"";if(name.length===0)return null;const normalized={name,required:value.required===!0,variadic:value.variadic===!0};return typeof value.description=="string"&&value.description.trim().length>0&&(normalized.description=value.description.trim()),normalized}).filter(entry=>entry!==null):[]}function collectExtensionDefinitionsByCommand(commandDefinitions){const definitionsByCommand=new Map;for(const definition of commandDefinitions){const commandPath=normalizeExtensionCommandPath(definition.command);if(commandPath.length===0)continue;const description=typeof definition.description=="string"&&definition.description.trim().length>0?definition.description.trim():void 0,intent=typeof definition.intent=="string"&&definition.intent.trim().length>0?definition.intent.trim():void 0;definitionsByCommand.set(commandPath,{command:commandPath,action:normalizeExtensionCommandAction(commandPath,definition.action),description,intent,examples:normalizeExtensionCommandStringList(definition.examples),failure_hints:normalizeExtensionCommandStringList(definition.failure_hints),arguments:normalizeExtensionCommandArguments(definition.arguments),flags:[],tier:definition.tier??"standard",family:definition.family??"extensions",source:{layer:definition.layer,name:definition.name,package:definition.source_package}})}return definitionsByCommand}function collectExtensionFlagsByCommand(flagRegistrations){const flagsByCommand=new Map;for(const registration of flagRegistrations){const commandPath=normalizeExtensionCommandPath(registration.target_command);if(commandPath.length===0)continue;const existing=flagsByCommand.get(commandPath)??[];existing.push(...registration.flags),flagsByCommand.set(commandPath,existing)}return flagsByCommand}function collectExtensionHelpCommandSet(commandHandlers,definitionsByCommand,flagsByCommand){const commandSet=new Set;for(const commandPath of commandHandlers){const normalized=normalizeExtensionCommandPath(commandPath);normalized.length>0&&commandSet.add(normalized)}for(const commandPath of definitionsByCommand.keys())commandSet.add(commandPath);for(const commandPath of flagsByCommand.keys())commandSet.add(commandPath);return commandSet}function resolveFlattenedAliasDescriptor(commandPath,definitionsByCommand,canonicalAliases){const canonical=canonicalAliases.get(commandPath);return canonical?definitionsByCommand.get(canonical):void 0}function collectExtensionCommandHelpDescriptors(commandHandlers,commandDefinitions,flagRegistrations,canonicalAliases=new Map){const definitionsByCommand=collectExtensionDefinitionsByCommand(commandDefinitions),flagsByCommand=collectExtensionFlagsByCommand(flagRegistrations),commandSet=collectExtensionHelpCommandSet(commandHandlers,definitionsByCommand,flagsByCommand),descriptors=new Map,sortedCommands=[...commandSet].sort((left,right)=>left.localeCompare(right));for(const commandPath of sortedCommands){const definition=resolveFlattenedAliasDescriptor(commandPath,definitionsByCommand,canonicalAliases)??definitionsByCommand.get(commandPath),flags=flagsByCommand.get(commandPath)??(definition?flagsByCommand.get(definition.command):void 0)??[];if(definition){descriptors.set(commandPath,{...definition,command:commandPath,flags});continue}descriptors.set(commandPath,{command:commandPath,action:normalizeExtensionCommandAction(commandPath,void 0),examples:[],failure_hints:[],arguments:[],flags,tier:"standard",family:"extensions"})}return descriptors}function buildExtensionArgumentToken(argument){const variadicSuffix=argument.variadic?"...":"";return argument.required?`<${argument.name}${variadicSuffix}>`:`[${argument.name}${variadicSuffix}]`}function applyDynamicExtensionArguments(command,descriptor){for(const argument of descriptor.arguments)command.argument(buildExtensionArgumentToken(argument),argument.description??"Extension argument.")}function normalizeDynamicExtensionOptionNames(definition){if(toOptionalBoolean(definition.visible)===!1)return null;const longName=resolveExtensionLongFlagName(definition.long),shortName=toNonEmptyFlagString(definition.short),normalizedShort=shortName&&shortName.startsWith("-")&&!shortName.startsWith("--")?shortName:null,normalizedLong=longName&&longName.startsWith("--")&&longName.length>2?longName:null,optionNames=[normalizedShort,normalizedLong].filter(entry=>entry!==null);return optionNames.length>0?optionNames:null}function formatDynamicExtensionOptionFlags(definition){const optionNames=normalizeDynamicExtensionOptionNames(definition);if(!optionNames)return null;const{valueName}=resolveExtensionFlagArity(definition),optional=parseExtensionLongFlagToken(definition.long)?.optional===!0,optionValueSuffix=valueName?optional?` [${valueName}]`:` <${valueName}>`:"";return`${optionNames.join(", ")}${optionValueSuffix}`}function formatDynamicExtensionParseOptionFlags(definition){return formatDynamicExtensionOptionFlags(definition)}function formatDynamicExtensionOptionDescription(definition){const description=toNonEmptyFlagString(definition.description)??"Extension-provided option.",markers=[];toOptionalBoolean(definition.required)===!0&&markers.push("required"),toOptionalBoolean(definition.enabled)===!1&&markers.push("disabled");const markerSuffix=markers.length>0?` [${markers.join(", ")}]`:"";return`${description}${markerSuffix}`}function commandAlreadyHasOption(command,definition){const longName=resolveExtensionLongFlagName(definition.long),shortName=toNonEmptyFlagString(definition.short);return command.options.some(option=>{const optionWithNames=option;return longName!==null&&optionWithNames.long===longName||shortName!==null&&optionWithNames.short===shortName})}function applyDynamicExtensionFlagOptions(command,definitions){for(const definition of definitions){if(commandAlreadyHasOption(command,definition))continue;const flags=formatDynamicExtensionParseOptionFlags(definition);if(!flags)continue;const description=formatDynamicExtensionOptionDescription(definition),option=new Option(flags,description);if(option.negate=!1,definition.list!==!0){command.addOption(option);continue}command.addOption(option.argParser((value,previous=[])=>[...Array.isArray(previous)?previous:[previous],value]))}}function buildResidualDynamicExtensionFlagHelp(command,definitions){return buildDynamicExtensionFlagHelp(definitions.filter(definition=>!commandAlreadyHasOption(command,definition)))}function buildDynamicExtensionHelpOptionSummary(definition){const flags=formatDynamicExtensionOptionFlags(definition);if(!flags)return null;const longName=resolveExtensionLongFlagName(definition.long),shortName=toNonEmptyFlagString(definition.short),normalizedLong=longName&&longName.startsWith("--")&&longName.length>2?longName:null,normalizedShort=shortName&&shortName.startsWith("-")&&!shortName.startsWith("--")?shortName:null,{takesValue,valueName}=resolveExtensionFlagArity(definition),required=toOptionalBoolean(definition.required)===!0;return{flags,long:normalizedLong,short:normalizedShort,description:formatDynamicExtensionOptionDescription(definition),takes_value:takesValue,value_required:takesValue&&parseExtensionLongFlagToken(definition.long)?.optional!==!0,value_name:valueName,variadic:!1,required,aliases:[],alias_for:null}}function buildDynamicExtensionHelpOptionSummaries(descriptor){if(!descriptor)return[];const summaries=[],seen=new Set;for(const definition of descriptor.flags){const summary=buildDynamicExtensionHelpOptionSummary(definition);!summary||seen.has(summary.flags)||(seen.add(summary.flags),summaries.push(summary))}return summaries}function mergeHelpOptionSummaries(base,extension){if(extension.length===0)return base;const merged=[...base],seen=new Set(base.map(entry=>entry.flags));for(const entry of extension)seen.has(entry.flags)||(seen.add(entry.flags),merged.push(entry));return merged}function buildDynamicExtensionCommandMetadataHelp(descriptor){const lines=[];if(descriptor.intent&&lines.push(`Intent: ${descriptor.intent}`),descriptor.action&&lines.push(`Action contract: ${descriptor.action}`),descriptor.examples.length>0){lines.push("Examples:");for(const example of descriptor.examples)lines.push(`  - ${example}`)}if(descriptor.failure_hints.length>0){lines.push("Common failure hints:");for(const hint of descriptor.failure_hints)lines.push(`  - ${hint}`)}return lines.length===0?null:`
 Extension command metadata:
   ${lines.join(`
   `)}`}function commandAliases(command){const commandRecord=command;if(typeof commandRecord.aliases=="function")return commandRecord.aliases().map(value=>value.trim().toLowerCase()).filter(value=>value.length>0);if(typeof commandRecord.alias=="function"){const alias=commandRecord.alias();if(typeof alias=="string"&&alias.trim().length>0)return[alias.trim().toLowerCase()]}return Array.isArray(commandRecord._aliases)?commandRecord._aliases.map(value=>value.trim().toLowerCase()).filter(value=>value.length>0):[]}function findDirectChildCommand(parent,name){const normalizedTarget=name.trim().toLowerCase();return parent.commands.find(entry=>entry.name().trim().toLowerCase()===normalizedTarget?!0:commandAliases(entry).includes(normalizedTarget))??null}function findCommandByPath(root,pathParts){let current=root;for(const part of pathParts){const next=findDirectChildCommand(current,part);if(!next)return null;current=next}return current}const extensionCreatedCommands=new WeakSet;function ensureCommandPath(root,pathParts){if(pathParts.length===0)return null;let current=root;for(let index=0;index<pathParts.length;index+=1){const part=pathParts[index];index>0&&PM_RELOCATED_COMMAND_ALIASES.some(entry=>entry.canonical===pathParts.join(" "))&&current.enablePositionalOptions();const existing=findDirectChildCommand(current,part);if(existing){current=existing;continue}const created=current.command(part);extensionCreatedCommands.add(created),index<pathParts.length-1?(created.description("Extension-provided command group."),created.action(()=>{created.help()})):created.description("Extension-provided command path."),current=created}return current}function findExtensionCommandPathCollision(root,pathParts){const extensionPath=pathParts.join(" "),reservedLeaf=PM_RELOCATED_COMMAND_ALIASES.find(entry=>extensionPath===entry.canonical||extensionPath.startsWith(`${entry.canonical} `));if(reservedLeaf)return{core_path:reservedLeaf.canonical,extension_path:extensionPath};let current=root;const traversed=[];for(const part of pathParts){const existing=findDirectChildCommand(current,part);if(!existing)return null;traversed.push(part);const isGroup=existing.commands.length>0||PM_RELOCATED_COMMAND_ALIASES.some(entry=>entry.canonical.startsWith(`${traversed.join(" ")} `));if(!extensionCreatedCommands.has(existing)&&(traversed.length===pathParts.length||!isGroup))return{core_path:traversed.join(" "),extension_path:pathParts.join(" ")};current=existing}return null}function buildExtensionCommandCollisionWarning(root,commandPath,aliases,descriptor,hasHandler=!1){const pathParts=commandPath.split(" ").filter(part=>part.length>0),collision=findExtensionCommandPathCollision(root,pathParts),existingCommand=findCommandByPath(root,pathParts),declaredFacet=PM_RELOCATED_COMMAND_ALIASES.some(alias=>alias.canonical===commandPath&&alias.alias===descriptor?.action&&!root.commands.some(command=>command.name()===alias.alias)&&(existingCommand===null||extensionCreatedCommands.has(existingCommand)));if(!collision||collision.core_path===commandPath&&existingCommand!==null&&!aliases.has(commandPath)&&!hasHandler||declaredFacet&&!aliases.has(commandPath))return null;const extensionOwner=descriptor?.source?.package??descriptor?.source?.name??"unknown-extension";return`extension_command_collision:${collision.extension_path}:core_owner=pm-cli:${collision.core_path}:extension_owner=${extensionOwner}`}function collectSafeExtensionCommandPaths(root,commandHandlers,descriptors,aliases,onCollision){return[...new Set([...commandHandlers,...descriptors.keys()])].filter(commandPath=>commandPath.trim().length>0).sort((left,right)=>left.localeCompare(right)).filter(commandPath=>{const warning=buildExtensionCommandCollisionWarning(root,commandPath,aliases,descriptors.get(commandPath),commandHandlers.includes(commandPath));return warning?(onCollision(warning),!aliases.has(commandPath)&&findCommandByPath(root,commandPath.split(" "))!==null):!0})}function reportExtensionCommandCollision(activationWarnings,report,warning){activationWarnings.push(warning),report(`[pm] warning: ${warning}; core command preserved. Rename or namespace the extension command alias.`)}export{applyDynamicExtensionArguments,applyDynamicExtensionFlagOptions,buildCanonicalExtensionAliases,buildDynamicExtensionCommandMetadataHelp,buildDynamicExtensionHelpOptionSummaries,buildExtensionCommandCollisionWarning,buildResidualDynamicExtensionFlagHelp,collectDynamicExtensionFlagHelpByCommand,collectExtensionCommandHelpDescriptors,collectSafeExtensionCommandPaths,commandAliases,ensureCommandPath,extensionFlagTakesValueForInvocation,findCommandByPath,findDirectChildCommand,findExtensionCommandPathCollision,mergeHelpOptionSummaries,normalizeExtensionCommandPath,reportExtensionCommandCollision,resolveExtensionFlagArity};

package/dist/cli/extension-command-options.d.ts

@@ -1,25 +1,25 @@
 /** Flag metadata consumed by loose-option parsing across core and extension commands. */
 export interface LooseCommandFlagDefinition {
-    /** Canonical long option token. */
-    long?: string;
-    /** Optional short option token. */
-    short?: string;
-    /** Backward-compatible aliases emitted by core command contracts. */
-    aliases?: string[];
-    /** Canonical runtime value kind. */
-    value_type?: string;
-    /** Backward-compatible runtime value kind alias. */
-    type?: string;
-    /** Whether the option can be supplied to the command. */
-    enabled?: boolean;
-    /** Whether callers must provide the option. */
-    required?: boolean;
-    /** Whether repeated or comma-delimited values accumulate. */
-    list?: boolean;
-    /** Whether repeated occurrences accumulate without splitting commas. */
-    repeatable?: boolean;
-    /** Value used when callers omit the option. */
-    default?: unknown;
+/** Canonical long option token. */
+long?: string;
+/** Optional short option token. */
+short?: string;
+/** Backward-compatible aliases emitted by core command contracts. */
+aliases?: string[];
+/** Canonical runtime value kind. */
+value_type?: string;
+/** Backward-compatible runtime value kind alias. */
+type?: string;
+/** Whether the option can be supplied to the command. */
+enabled?: boolean;
+/** Whether callers must provide the option. */
+required?: boolean;
+/** Whether repeated or comma-delimited values accumulate. */
+list?: boolean;
+/** Whether repeated occurrences accumulate without splitting commas. */
+repeatable?: boolean;
+/** Value used when callers omit the option. */
+default?: unknown;
 }
 /** Implements collect loose command option keys for definitions for the public runtime surface of this module. */
 export declare function collectLooseCommandOptionKeysForDefinitions(definitions: ReadonlyArray<LooseCommandFlagDefinition>): Set<string>;

package/dist/cli/extension-command-options.js

@@ -1,2 +1,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]="c4cd4b1c-7043-53a0-8823-d47339372420")}catch{}})();import{EXIT_CODE,PmCliError,flattenFlagListValue,resolveFlagValueKind}from"../sdk/runtime-primitives.js";const UNSAFE_LOOSE_OPTION_KEYS=new Set(["__proto__","prototype","constructor"]),LOOSE_OPTION_OCCURRENCES=Symbol("looseOptionOccurrences");function toLooseOptionKey(rawKey){return rawKey.trim().toLowerCase().replaceAll(/-([a-z0-9])/g,(_match,group)=>group.toUpperCase())}function setLooseOptionValue(options,key,value){const existing=options[key];if(existing===void 0){options[key]=value;return}if(Array.isArray(existing)){existing.push(value),options[key]=existing;return}options[key]=[existing,value]}function parseLooseOptionToken(args,index){const token=args[index];if(!token.startsWith("-")||token==="-"||token==="--")return null;if(!token.startsWith("--")){const equalsIndex2=token.indexOf("=");if(equalsIndex2>=0)return{consumed:1,key:token.slice(1,equalsIndex2).trim(),value:token.slice(equalsIndex2+1)};const key2=token.slice(1).trim(),next2=args[index+1];return typeof next2=="string"&&!next2.startsWith("-")?{consumed:2,key:key2,value:next2}:{consumed:1,key:key2,value:!0}}const equalsIndex=token.indexOf("=");if(equalsIndex>=0)return{consumed:1,key:token.slice(2,equalsIndex).trim(),value:token.slice(equalsIndex+1)};if(token.startsWith("--no-"))return{consumed:1,key:token.slice(5).trim(),value:!1};const key=token.slice(2).trim(),next=args[index+1];return typeof next=="string"&&!next.startsWith("-")?{consumed:2,key,value:next}:{consumed:1,key,value:!0}}function isUnsafeLooseOptionKey(key){return UNSAFE_LOOSE_OPTION_KEYS.has(key)}function resolveLooseOptionCoercionKind(definition){const raw=(typeof definition.value_type=="string"?definition.value_type:void 0)??(typeof definition.type=="string"?definition.type:void 0);return resolveFlagValueKind(raw)}function collectLooseOptionKeys(definition){const keys=[],long=typeof definition.long=="string"?definition.long.trim():"",short=typeof definition.short=="string"?definition.short.trim():"";if(long.startsWith("--")){const normalized=toLooseOptionKey(long.slice(2));normalized.length>0&&!isUnsafeLooseOptionKey(normalized)&&keys.push(normalized)}if(short.startsWith("-")&&!short.startsWith("--")){const normalized=toLooseOptionKey(short.slice(1));normalized.length>0&&!isUnsafeLooseOptionKey(normalized)&&keys.push(normalized)}return[...new Set(keys)]}function collectLooseCommandOptionKeysForDefinitions(definitions){const keys=new Set;for(const definition of definitions)for(const key of collectLooseOptionKeys(definition))keys.add(key);return keys}function resolveCanonicalLooseOptionKey(definition){const long=typeof definition.long=="string"?definition.long.trim():"";if(long.startsWith("--")){const normalized=toLooseOptionKey(long.slice(2));if(normalized.length>0&&!isUnsafeLooseOptionKey(normalized))return normalized}return collectLooseOptionKeys(definition)[0]??null}function formatLooseOptionLabel(definition){const long=typeof definition.long=="string"?definition.long.trim():"";if(long.startsWith("--")&&long.length>2)return long;const short=typeof definition.short=="string"?definition.short.trim():"";return short.startsWith("-")&&!short.startsWith("--")&&short.length>1?short:null}function validateLooseCommandOptionsWithFlagDefinitions(options,definitions,commandPath){if(definitions.length===0)return;const allowed=new Set,disabled=new Map,required=[],labels=[];for(const definition of definitions){const keys=collectLooseOptionKeys(definition),normalizedLabel=formatLooseOptionLabel(definition);normalizedLabel!==null&&labels.push(normalizedLabel);for(const key of keys)allowed.add(key),definition.enabled===!1&&disabled.set(key,normalizedLabel);definition.required===!0&&definition.enabled!==!1&&keys.length>0&&required.push({keys,label:normalizedLabel})}for(const key of Object.keys(options)){if(!allowed.has(key)){const expected=labels.length>0?` Expected one of: ${[...new Set(labels)].join(", ")}.`:"";throw new PmCliError(`Unknown option '--${key}' for extension command '${commandPath}'.${expected}`,EXIT_CODE.USAGE)}const disabledLabel=disabled.get(key);if(disabledLabel)throw new PmCliError(`Option '${disabledLabel}' is disabled for extension command '${commandPath}'.`,EXIT_CODE.USAGE)}for(const entry of required)if(!entry.keys.some(key=>Object.hasOwn(options,key)))throw new PmCliError(`Missing required option '${entry.label}' for extension command '${commandPath}'.`,EXIT_CODE.USAGE)}function coerceLooseStringOptionValue(value){return typeof value=="string"||value==null?value:String(value)}function coerceLooseNumberOptionValue(value){if(typeof value=="number")return value;if(typeof value=="string"&&value.trim().length>0){const parsed=Number(value);return Number.isFinite(parsed)?parsed:value}return value}function coerceLooseBooleanOptionValue(value){if(typeof value=="boolean")return value;if(typeof value=="string"){const normalized=value.trim().toLowerCase();if(normalized==="true"||normalized==="1")return!0;if(normalized==="false"||normalized==="0")return!1}return value}const LOOSE_OPTION_VALUE_COERCERS={string:coerceLooseStringOptionValue,number:coerceLooseNumberOptionValue,boolean:coerceLooseBooleanOptionValue};function coerceLooseOptionValue(value,kind){return Array.isArray(value)?value.map(entry=>coerceLooseOptionValue(entry,kind)):LOOSE_OPTION_VALUE_COERCERS[kind](value)}function normalizeAccumulatedFlagValue(value,kind,preserveOccurrenceCommas){const entries=preserveOccurrenceCommas?(Array.isArray(value)?value.flat(1/0):[value]).filter(entry=>entry!=null&&entry!==""):flattenFlagListValue(value);return kind?entries.map(entry=>coerceLooseOptionValue(entry,kind)):entries}function applyFlagDefault(defaultValue,kind,isListFlag,preserveOccurrenceCommas){return isListFlag?normalizeAccumulatedFlagValue(defaultValue,kind,preserveOccurrenceCommas):kind?coerceLooseOptionValue(defaultValue,kind):defaultValue}function readOrderedLooseListValues(occurrenceSource,optionKeys,fallback){const occurrences=occurrenceSource[LOOSE_OPTION_OCCURRENCES];if(!occurrences||occurrences.length===0)return fallback;const acceptedKeys=new Set(optionKeys);return occurrences.filter(occurrence=>acceptedKeys.has(occurrence.key)).map(occurrence=>occurrence.value)}function coerceLooseCommandOptionsWithFlagDefinitions(options,definitions,occurrenceSource=options){if(definitions.length===0)return options;const coerced=Object.create(null);for(const[key,value]of Object.entries(options))coerced[key]=value;for(const definition of definitions){const canonical=resolveCanonicalLooseOptionKey(definition);if(!canonical)continue;const isListFlag=definition.list===!0,optionKeys=collectLooseOptionKeys(definition);for(const key of optionKeys)if(!(key===canonical||!Object.hasOwn(coerced,key))){if(Object.hasOwn(coerced,canonical)){if(!isListFlag){delete coerced[key];continue}const canonicalValue=coerced[canonical],aliasValue=coerced[key];coerced[canonical]=[...Array.isArray(canonicalValue)?canonicalValue:[canonicalValue],...Array.isArray(aliasValue)?aliasValue:[aliasValue]].filter(value=>value!=null),delete coerced[key];continue}coerced[canonical]=coerced[key],delete coerced[key]}const kind=resolveLooseOptionCoercionKind(definition),preserveOccurrenceCommas=definition.repeatable===!0;if(!Object.hasOwn(coerced,canonical)){definition.default!==void 0&&(coerced[canonical]=applyFlagDefault(definition.default,kind,isListFlag,preserveOccurrenceCommas));continue}if(isListFlag){coerced[canonical]=normalizeAccumulatedFlagValue(readOrderedLooseListValues(occurrenceSource,optionKeys,coerced[canonical]),kind,preserveOccurrenceCommas);continue}kind&&(coerced[canonical]=coerceLooseOptionValue(coerced[canonical],kind))}return coerced}function parseLooseCommandOptions(args){const options=Object.create(null),occurrences=[];Object.defineProperty(options,LOOSE_OPTION_OCCURRENCES,{value:occurrences});let index=0;for(;index<args.length;){const parsed=parseLooseOptionToken(args,index);if(!parsed){index+=1;continue}const normalizedKey=toLooseOptionKey(parsed.key);if(normalizedKey.length===0||isUnsafeLooseOptionKey(normalizedKey)){index+=parsed.consumed;continue}setLooseOptionValue(options,normalizedKey,parsed.value),occurrences.push({...parsed,key:normalizedKey}),index+=parsed.consumed}return options}function collectLoosePositionalArgs(args){const positionals=[];let index=0;for(;index<args.length;){if(args[index]==="--"){positionals.push(...args.slice(index+1));break}const parsed=parseLooseOptionToken(args,index);if(parsed){index+=Math.max(1,parsed.consumed);continue}positionals.push(args[index]),index+=1}return positionals}function stripLooseCommandOptionTokens(args,definitions){if(definitions.length===0)return[...args];const knownKeys=new Set,booleanKeys=new Set;for(const definition of definitions){const valueKind=resolveLooseOptionCoercionKind(definition);for(const key of collectLooseOptionKeys(definition))knownKeys.add(key),valueKind==="boolean"&&booleanKeys.add(key)}if(knownKeys.size===0)return[...args];const stripped=[];let index=0;for(;index<args.length;){if(args[index]==="--"){stripped.push(...args.slice(index+1));break}const parsed=parseLooseOptionToken(args,index);if(parsed){const normalizedKey=toLooseOptionKey(parsed.key);if(knownKeys.has(normalizedKey)){const token=args[index],consumed=booleanKeys.has(normalizedKey)&&!token.includes("=")?1:parsed.consumed;index+=consumed;continue}}stripped.push(args[index]),index+=1}return stripped}export{coerceLooseCommandOptionsWithFlagDefinitions,collectLooseCommandOptionKeysForDefinitions,collectLoosePositionalArgs,parseLooseCommandOptions,stripLooseCommandOptionTokens,validateLooseCommandOptionsWithFlagDefinitions};
+(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]="0e7ed11b-0194-53e5-8b2d-d7d91f295b8a")}catch{}})();import{resolveExtensionLongFlagName,EXIT_CODE,PmCliError,flattenFlagListValue,resolveFlagValueKind}from"../sdk/runtime-primitives.js";const UNSAFE_LOOSE_OPTION_KEYS=new Set(["__proto__","prototype","constructor"]),LOOSE_OPTION_OCCURRENCES=Symbol("looseOptionOccurrences");function toLooseOptionKey(rawKey){return rawKey.trim().toLowerCase().replaceAll(/-([a-z0-9])/g,(_match,group)=>group.toUpperCase())}function setLooseOptionValue(options,key,value){const existing=options[key];if(existing===void 0){options[key]=value;return}if(Array.isArray(existing)){existing.push(value),options[key]=existing;return}options[key]=[existing,value]}function parseLooseOptionToken(args,index){const token=args[index];if(!token.startsWith("-")||token==="-"||token==="--")return null;if(!token.startsWith("--")){const equalsIndex2=token.indexOf("=");if(equalsIndex2>=0)return{consumed:1,key:token.slice(1,equalsIndex2).trim(),value:token.slice(equalsIndex2+1)};const key2=token.slice(1).trim(),next2=args[index+1];return typeof next2=="string"&&!next2.startsWith("-")?{consumed:2,key:key2,value:next2}:{consumed:1,key:key2,value:!0}}const equalsIndex=token.indexOf("=");if(equalsIndex>=0)return{consumed:1,key:token.slice(2,equalsIndex).trim(),value:token.slice(equalsIndex+1)};if(token.startsWith("--no-"))return{consumed:1,key:token.slice(5).trim(),value:!1};const key=token.slice(2).trim(),next=args[index+1];return typeof next=="string"&&!next.startsWith("-")?{consumed:2,key,value:next}:{consumed:1,key,value:!0}}function isUnsafeLooseOptionKey(key){return UNSAFE_LOOSE_OPTION_KEYS.has(key)}function resolveLooseOptionCoercionKind(definition){const raw=(typeof definition.value_type=="string"?definition.value_type:void 0)??(typeof definition.type=="string"?definition.type:void 0);return resolveFlagValueKind(raw)}function collectLooseOptionKeys(definition){const keys=[],long=resolveExtensionLongFlagName(definition.long)??"",short=typeof definition.short=="string"?definition.short.trim():"";if(long.startsWith("--")){const normalized=toLooseOptionKey(long.slice(2));normalized.length>0&&!isUnsafeLooseOptionKey(normalized)&&keys.push(normalized)}if(short.startsWith("-")&&!short.startsWith("--")){const normalized=toLooseOptionKey(short.slice(1));normalized.length>0&&!isUnsafeLooseOptionKey(normalized)&&keys.push(normalized)}return[...new Set(keys)]}function collectLooseCommandOptionKeysForDefinitions(definitions){const keys=new Set;for(const definition of definitions)for(const key of collectLooseOptionKeys(definition))keys.add(key);return keys}function resolveCanonicalLooseOptionKey(definition){const long=resolveExtensionLongFlagName(definition.long)??"";if(long.startsWith("--")){const normalized=toLooseOptionKey(long.slice(2));if(normalized.length>0&&!isUnsafeLooseOptionKey(normalized))return normalized}return collectLooseOptionKeys(definition)[0]??null}function formatLooseOptionLabel(definition){const long=typeof definition.long=="string"?definition.long.trim():"";if(long.startsWith("--")&&long.length>2)return long;const short=typeof definition.short=="string"?definition.short.trim():"";return short.startsWith("-")&&!short.startsWith("--")&&short.length>1?short:null}function validateLooseCommandOptionsWithFlagDefinitions(options,definitions,commandPath){if(definitions.length===0)return;const allowed=new Set,disabled=new Map,required=[],labels=[];for(const definition of definitions){const keys=collectLooseOptionKeys(definition),normalizedLabel=formatLooseOptionLabel(definition);normalizedLabel!==null&&labels.push(normalizedLabel);for(const key of keys)allowed.add(key),definition.enabled===!1&&disabled.set(key,normalizedLabel);definition.required===!0&&definition.enabled!==!1&&keys.length>0&&required.push({keys,label:normalizedLabel})}for(const key of Object.keys(options)){if(!allowed.has(key)){const expected=labels.length>0?` Expected one of: ${[...new Set(labels)].join(", ")}.`:"";throw new PmCliError(`Unknown option '--${key}' for extension command '${commandPath}'.${expected}`,EXIT_CODE.USAGE)}const disabledLabel=disabled.get(key);if(disabledLabel)throw new PmCliError(`Option '${disabledLabel}' is disabled for extension command '${commandPath}'.`,EXIT_CODE.USAGE)}for(const entry of required)if(!entry.keys.some(key=>Object.hasOwn(options,key)))throw new PmCliError(`Missing required option '${entry.label}' for extension command '${commandPath}'.`,EXIT_CODE.USAGE)}function coerceLooseStringOptionValue(value){return typeof value=="string"||value==null?value:String(value)}function coerceLooseNumberOptionValue(value){if(typeof value=="number")return value;if(typeof value=="string"&&value.trim().length>0){const parsed=Number(value);return Number.isFinite(parsed)?parsed:value}return value}function coerceLooseBooleanOptionValue(value){if(typeof value=="boolean")return value;if(typeof value=="string"){const normalized=value.trim().toLowerCase();if(normalized==="true"||normalized==="1")return!0;if(normalized==="false"||normalized==="0")return!1}return value}const LOOSE_OPTION_VALUE_COERCERS={string:coerceLooseStringOptionValue,number:coerceLooseNumberOptionValue,boolean:coerceLooseBooleanOptionValue};function coerceLooseOptionValue(value,kind){return Array.isArray(value)?value.map(entry=>coerceLooseOptionValue(entry,kind)):LOOSE_OPTION_VALUE_COERCERS[kind](value)}function normalizeAccumulatedFlagValue(value,kind,preserveOccurrenceCommas){const entries=preserveOccurrenceCommas?(Array.isArray(value)?value.flat(1/0):[value]).filter(entry=>entry!=null&&entry!==""):flattenFlagListValue(value);return kind?entries.map(entry=>coerceLooseOptionValue(entry,kind)):entries}function applyFlagDefault(defaultValue,kind,isListFlag,preserveOccurrenceCommas){return isListFlag?normalizeAccumulatedFlagValue(defaultValue,kind,preserveOccurrenceCommas):kind?coerceLooseOptionValue(defaultValue,kind):defaultValue}function readOrderedLooseListValues(occurrenceSource,optionKeys,fallback){const occurrences=occurrenceSource[LOOSE_OPTION_OCCURRENCES];if(!occurrences||occurrences.length===0)return fallback;const acceptedKeys=new Set(optionKeys);return occurrences.filter(occurrence=>acceptedKeys.has(occurrence.key)).map(occurrence=>occurrence.value)}function coerceLooseCommandOptionsWithFlagDefinitions(options,definitions,occurrenceSource=options){if(definitions.length===0)return options;const coerced=Object.create(null);for(const[key,value]of Object.entries(options))coerced[key]=value;for(const definition of definitions){const canonical=resolveCanonicalLooseOptionKey(definition);if(!canonical)continue;const isListFlag=definition.list===!0,optionKeys=collectLooseOptionKeys(definition);for(const key of optionKeys)if(!(key===canonical||!Object.hasOwn(coerced,key))){if(Object.hasOwn(coerced,canonical)){if(!isListFlag){delete coerced[key];continue}const canonicalValue=coerced[canonical],aliasValue=coerced[key];coerced[canonical]=[...Array.isArray(canonicalValue)?canonicalValue:[canonicalValue],...Array.isArray(aliasValue)?aliasValue:[aliasValue]].filter(value=>value!=null),delete coerced[key];continue}coerced[canonical]=coerced[key],delete coerced[key]}const kind=resolveLooseOptionCoercionKind(definition),preserveOccurrenceCommas=definition.repeatable===!0;if(!Object.hasOwn(coerced,canonical)){definition.default!==void 0&&(coerced[canonical]=applyFlagDefault(definition.default,kind,isListFlag,preserveOccurrenceCommas));continue}if(isListFlag){coerced[canonical]=normalizeAccumulatedFlagValue(readOrderedLooseListValues(occurrenceSource,optionKeys,coerced[canonical]),kind,preserveOccurrenceCommas);continue}kind&&(coerced[canonical]=coerceLooseOptionValue(coerced[canonical],kind))}return coerced}function parseLooseCommandOptions(args){const options=Object.create(null),occurrences=[];Object.defineProperty(options,LOOSE_OPTION_OCCURRENCES,{value:occurrences});let index=0;for(;index<args.length;){const parsed=parseLooseOptionToken(args,index);if(!parsed){index+=1;continue}const normalizedKey=toLooseOptionKey(parsed.key);if(normalizedKey.length===0||isUnsafeLooseOptionKey(normalizedKey)){index+=parsed.consumed;continue}setLooseOptionValue(options,normalizedKey,parsed.value),occurrences.push({...parsed,key:normalizedKey}),index+=parsed.consumed}return options}function collectLoosePositionalArgs(args){const positionals=[];let index=0;for(;index<args.length;){if(args[index]==="--"){positionals.push(...args.slice(index+1));break}const parsed=parseLooseOptionToken(args,index);if(parsed){index+=Math.max(1,parsed.consumed);continue}positionals.push(args[index]),index+=1}return positionals}function stripLooseCommandOptionTokens(args,definitions){if(definitions.length===0)return[...args];const knownKeys=new Set,booleanKeys=new Set;for(const definition of definitions){const valueKind=resolveLooseOptionCoercionKind(definition);for(const key of collectLooseOptionKeys(definition))knownKeys.add(key),valueKind==="boolean"&&booleanKeys.add(key)}if(knownKeys.size===0)return[...args];const stripped=[];let index=0;for(;index<args.length;){if(args[index]==="--"){stripped.push(...args.slice(index+1));break}const parsed=parseLooseOptionToken(args,index);if(parsed){const normalizedKey=toLooseOptionKey(parsed.key);if(knownKeys.has(normalizedKey)){const token=args[index],consumed=booleanKeys.has(normalizedKey)&&!token.includes("=")?1:parsed.consumed;index+=consumed;continue}}stripped.push(args[index]),index+=1}return stripped}export{coerceLooseCommandOptionsWithFlagDefinitions,collectLooseCommandOptionKeysForDefinitions,collectLoosePositionalArgs,parseLooseCommandOptions,stripLooseCommandOptionTokens,validateLooseCommandOptionsWithFlagDefinitions};
 //# sourceMappingURL=extension-command-options.js.map

package/dist/cli/extension-recovery.d.ts

@@ -1,29 +1,29 @@
 import { activateExtensions, loadExtensions, readSettings, resolveImplicitPmRoot } from "../sdk/runtime-primitives.js";
 /** Extension failure safe to append to unknown-command output. */
 export interface ExtensionRecoveryFailure {
-    /** Extension resolution layer that failed. */
-    layer: string;
-    /** Installed extension identity. */
-    name: string;
-    /** Actionable loader or activation error. */
-    error: string;
-    /** Command paths declared statically for this extension. */
-    declared_commands?: string[];
-    /** Whether the failed extension declares the attempted command path. */
-    declared_command_match?: boolean;
-    /** Bounded commands that repair or diagnose the failed installation. */
-    recovery_commands?: string[];
+/** Extension resolution layer that failed. */
+layer: string;
+/** Installed extension identity. */
+name: string;
+/** Actionable loader or activation error. */
+error: string;
+/** Command paths declared statically for this extension. */
+declared_commands?: string[];
+/** Whether the failed extension declares the attempted command path. */
+declared_command_match?: boolean;
+/** Bounded commands that repair or diagnose the failed installation. */
+recovery_commands?: string[];
 }
 /** Injectable recovery dependencies used to exercise loader failure boundaries. */
 export interface ExtensionRecoveryDependencies {
-    /** Reads active tracker settings. */
-    readSettings: typeof readSettings;
-    /** Loads installed extension modules. */
-    loadExtensions: typeof loadExtensions;
-    /** Activates loaded extension modules. */
-    activateExtensions: typeof activateExtensions;
-    /** Resolves the ordinary cwd tracker independently from an explicit CLI path. */
-    resolveImplicitPmRoot: typeof resolveImplicitPmRoot;
+/** Reads active tracker settings. */
+readSettings: typeof readSettings;
+/** Loads installed extension modules. */
+loadExtensions: typeof loadExtensions;
+/** Activates loaded extension modules. */
+activateExtensions: typeof activateExtensions;
+/** Resolves the ordinary cwd tracker independently from an explicit CLI path. */
+resolveImplicitPmRoot: typeof resolveImplicitPmRoot;
 }
 /** Reload extensions and return bounded load plus activation failures. */
 export declare function loadExtensionRecoveryFailures(pmRoot: string, overrides?: Partial<ExtensionRecoveryDependencies>, attemptedCommandPaths?: readonly string[]): Promise<ExtensionRecoveryFailure[]>;

package/dist/cli/help-content.d.ts

@@ -11,23 +11,23 @@ export declare function setPmCommandHelpVisibilityTier(command: Command, tier: P
 export declare function getPmCommandHelpVisibilityTier(command: Command): PmCommandVisibilityTier | undefined;
 /** Documents the help bundle payload exchanged by command, SDK, and package integrations. */
 export interface HelpBundle {
-    /** Value that configures or reports why for this contract. */
-    why: string;
-    /** Value that configures or reports examples for this contract. */
-    examples: string[];
-    /** Value that configures or reports tips for this contract. */
-    tips?: string[];
+/** Value that configures or reports why for this contract. */
+why: string;
+/** Value that configures or reports examples for this contract. */
+examples: string[];
+/** Value that configures or reports tips for this contract. */
+tips?: string[];
 }
 /** Documents the help narrative payload exchanged by command, SDK, and package integrations. */
 export interface HelpNarrative {
-    /** Value that configures or reports intent for this contract. */
-    intent: string;
-    /** Value that configures or reports examples for this contract. */
-    examples: string[];
-    /** Value that configures or reports tips for this contract. */
-    tips: string[];
-    /** Strategy used to control detail behavior. */
-    detail_mode: HelpDetailMode;
+/** Value that configures or reports intent for this contract. */
+intent: string;
+/** Value that configures or reports examples for this contract. */
+examples: string[];
+/** Value that configures or reports tips for this contract. */
+tips: string[];
+/** Strategy used to control detail behavior. */
+detail_mode: HelpDetailMode;
 }
 /** Restricts help detail mode values accepted by command, SDK, and storage contracts. */
 export type HelpDetailMode = "compact" | "detailed";
@@ -51,7 +51,7 @@ export declare function resolveHelpNarrative(commandPath: string | undefined, de
 export declare function attachRichHelpText(program: Command, argv?: string[]): void;
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
 export declare const _testOnly: {
-    renderCompactHelpBundle: typeof renderCompactHelpBundle;
-    renderDetailedHelpBundle: typeof renderDetailedHelpBundle;
+renderCompactHelpBundle: typeof renderCompactHelpBundle;
+renderDetailedHelpBundle: typeof renderDetailedHelpBundle;
 };
 export {};