@unbrained/pm-cli 2026.10.13 → 2026.10.15

package/dist/cli/error-guidance.d.ts

@@ -1,216 +1,216 @@
-import { type PmCliErrorContext, type PmCliErrorRecoveryPayload } from "../sdk/runtime-primitives.js";
-import { type PmDiagnosticOutputReceipt, type PmProjectedDiagnostic } from "../sdk/cli-contracts/agent-output-contracts.js";
+import { type PmCliErrorContext,type PmCliErrorRecoveryPayload } from "../sdk/runtime-primitives.js";
+import { type PmDiagnosticOutputReceipt,type PmProjectedDiagnostic } from "../sdk/cli-contracts/agent-output-contracts.js";
 interface GuidanceMessage {
-policyViolations?: PmCliErrorContext["policy_violations"];
-policyViolationCount?: number;
-itemId?: string;
-transactionOperation?: PmCliErrorContext["transaction_operation"];
-tombstone?: PmCliErrorContext["tombstone"];
-code: string;
-type: string;
-title: string;
-happened: string;
-required: string;
-why?: string;
-examples?: string[];
-nextSteps?: string[];
-verificationErrors?: string[];
-flag?: string;
-value?: string;
-unmatchedSelectors?: NonNullable<PmCliErrorContext["unmatched_selectors"]>;
-availableDependencies?: NonNullable<PmCliErrorContext["available_dependencies"]>;
-recovery?: PmCliErrorRecoveryPayload;
+policyViolations?:PmCliErrorContext["policy_violations"];
+policyViolationCount?:number;
+itemId?:string;
+transactionOperation?:PmCliErrorContext["transaction_operation"];
+tombstone?:PmCliErrorContext["tombstone"];
+code:string;
+type:string;
+title:string;
+happened:string;
+required:string;
+why?:string;
+examples?:string[];
+nextSteps?:string[];
+verificationErrors?:string[];
+flag?:string;
+value?:string;
+unmatchedSelectors?:NonNullable<PmCliErrorContext["unmatched_selectors"]>;
+availableDependencies?:NonNullable<PmCliErrorContext["available_dependencies"]>;
+recovery?:PmCliErrorRecoveryPayload;
 }
 /** Compact refusal identity embedded in every structured error envelope. */
 export interface PmRefusalEnvelope {
 /** Command, flag, or missing operand that rejected the invocation. */
-surface: string;
+surface:string;
 /** Supplied scalar rejected by a closed domain, when available. */
-rejected_value?: string;
+rejected_value?:string;
 /** Complete legal domain advertised by the refusal, when applicable. */
-legal_domain?: string[];
+legal_domain?:string[];
 /** Required metadata paths from the displayed policy violations. */
-missing_fields?: string[];
+missing_fields?:string[];
 /** Policy identity, rule, rationale and missing fields, capped at three policies. */
-policies?: PmCliErrorContext["policy_violations"];
+policies?:PmCliErrorContext["policy_violations"];
 /** Total violated policies, including any omitted from policies. */
-policy_violation_count?: number;
+policy_violation_count?:number;
 /** Process exit code paired with the refusal. */
-exit_code: number;
+exit_code:number;
 }
 /** Documents the json error envelope payload exchanged by command, SDK, and package integrations. */
 export interface JsonErrorEnvelope {
 /** Ordered mutation that failed semantic preview validation. */
-transaction_operation?: PmCliErrorContext["transaction_operation"];
+transaction_operation?:PmCliErrorContext["transaction_operation"];
 /** Exact item identity attached to a storage diagnostic. */
-item_id?: string;
+item_id?:string;
 /** Verified retained deletion and its recoverable version. */
-tombstone?: PmCliErrorContext["tombstone"];
+tombstone?:PmCliErrorContext["tombstone"];
 /** Schema type that determines the shape and validation rules for this value. */
-type: string;
+type:string;
 /** Value that configures or reports code for this contract. */
-code: string;
+code:string;
 /** Value that configures or reports title for this contract. */
-title: string;
+title:string;
 /** Value that configures or reports detail for this contract. */
-detail: string;
+detail:string;
 /** Value that configures or reports required for this contract. */
-required: string;
+required:string;
 /** Value that configures or reports exit code for this contract. */
-exit_code: number;
+exit_code:number;
 /** Value that configures or reports why for this contract. */
-why?: string;
+why?:string;
 /** Value that configures or reports examples for this contract. */
-examples?: string[];
+examples?:string[];
 /** Value that configures or reports next steps for this contract. */
-next_steps?: string[];
+next_steps?:string[];
 /** Exact integrity verifier findings that caused the operation to refuse. */
-verification_errors?: string[];
+verification_errors?:string[];
 /** CLI flag whose supplied value violated a shared mutation grammar. */
-flag?: string;
+flag?:string;
 /** Supplied scalar value that violated a shared mutation grammar. */
-value?: string;
+value?:string;
 /** Dependency selectors that matched no stored edge. */
-unmatched_selectors?: NonNullable<PmCliErrorContext["unmatched_selectors"]>;
+unmatched_selectors?:NonNullable<PmCliErrorContext["unmatched_selectors"]>;
 /** Compact stored dependency identities available when a removal failed. */
-available_dependencies?: NonNullable<PmCliErrorContext["available_dependencies"]>;
+available_dependencies?:NonNullable<PmCliErrorContext["available_dependencies"]>;
 /** Value that configures or reports recovery for this contract. */
-recovery?: PmCliErrorRecoveryPayload;
+recovery?:PmCliErrorRecoveryPayload;
 /** Stable compact identity of the failing surface and legal recovery domain. */
-refusal: PmRefusalEnvelope;
+refusal:PmRefusalEnvelope;
 /** Binding output-budget receipt for this diagnostic. */
-diagnostic_output?: PmDiagnosticOutputReceipt;
+diagnostic_output?:PmDiagnosticOutputReceipt;
 }
 /** Error envelope after deterministic budget projection. */
 export type ProjectedJsonErrorEnvelope = PmProjectedDiagnostic<JsonErrorEnvelope>;
 /** Compact an error envelope to fields that change the caller's next action. */
-export declare function projectLeanErrorEnvelope(envelope: ProjectedJsonErrorEnvelope): ProjectedJsonErrorEnvelope;
+export declare function projectLeanErrorEnvelope(envelope:ProjectedJsonErrorEnvelope):ProjectedJsonErrorEnvelope;
 /** Documents the error classification payload exchanged by command, SDK, and package integrations. */
 export interface ErrorClassification {
 /** Ordered mutation that failed semantic preview validation. */
-transaction_operation?: PmCliErrorContext["transaction_operation"];
+transaction_operation?:PmCliErrorContext["transaction_operation"];
 /** Exact item identity attached to a storage diagnostic. */
-item_id?: string;
+item_id?:string;
 /** Verified retained deletion and its recoverable version. */
-tombstone?: PmCliErrorContext["tombstone"];
+tombstone?:PmCliErrorContext["tombstone"];
 /** Schema type that determines the shape and validation rules for this value. */
-type: string;
+type:string;
 /** Value that configures or reports code for this contract. */
-code: string;
+code:string;
 /** Value that configures or reports title for this contract. */
-title: string;
+title:string;
 /** Value that configures or reports detail for this contract. */
-detail: string;
+detail:string;
 /** Value that configures or reports required for this contract. */
-required: string;
+required:string;
 /** Value that configures or reports why for this contract. */
-why?: string;
+why?:string;
 /** Value that configures or reports examples for this contract. */
-examples?: string[];
+examples?:string[];
 /** Value that configures or reports next steps for this contract. */
-next_steps?: string[];
+next_steps?:string[];
 /** Exact integrity verifier findings that caused the operation to refuse. */
-verification_errors?: string[];
+verification_errors?:string[];
 /** CLI flag whose supplied value violated a shared mutation grammar. */
-flag?: string;
+flag?:string;
 /** Supplied scalar value that violated a shared mutation grammar. */
-value?: string;
+value?:string;
 /** Dependency selectors that matched no stored edge. */
-unmatched_selectors?: NonNullable<PmCliErrorContext["unmatched_selectors"]>;
+unmatched_selectors?:NonNullable<PmCliErrorContext["unmatched_selectors"]>;
 /** Compact stored dependency identities available when a removal failed. */
-available_dependencies?: NonNullable<PmCliErrorContext["available_dependencies"]>;
+available_dependencies?:NonNullable<PmCliErrorContext["available_dependencies"]>;
 /** Value that configures or reports recovery for this contract. */
-recovery?: PmCliErrorRecoveryPayload;
+recovery?:PmCliErrorRecoveryPayload;
 }
 /** Documents the commander guidance context payload exchanged by command, SDK, and package integrations. */
 export interface CommanderGuidanceContext {
 /** Value that configures or reports unknown command examples for this contract. */
-unknownCommandExamples?: string[];
+unknownCommandExamples?:string[];
 /** Value that configures or reports unknown command next steps for this contract. */
-unknownCommandNextSteps?: string[];
+unknownCommandNextSteps?:string[];
 /** Value that configures or reports attempted command for this contract. */
-attemptedCommand?: string;
+attemptedCommand?:string;
 /** Value that configures or reports normalized invocation args for this contract. */
-normalizedInvocationArgs?: string[];
+normalizedInvocationArgs?:string[];
 /** Value that configures or reports provided option flags for this contract. */
-providedOptionFlags?: string[];
+providedOptionFlags?:string[];
 /** Value that configures or reports unknown option suggestions for this contract. */
-unknownOptionSuggestions?: string[];
+unknownOptionSuggestions?:string[];
 /** Value that configures or reports unknown option other commands for this contract. */
-unknownOptionOtherCommands?: string[];
+unknownOptionOtherCommands?:string[];
 /** Complete number of commands accepting the unknown option. */
-unknownOptionOtherCommandsTotal?: number;
+unknownOptionOtherCommandsTotal?:number;
 /** Whether the structured command candidates reached their own ceiling. */
-unknownOptionOtherCommandsTruncated?: boolean;
+unknownOptionOtherCommandsTruncated?:boolean;
 /** Declared lexicon membership of the rejected option spelling. */
-unknownOptionScope?: PmCliErrorRecoveryPayload["option_scope"];
+unknownOptionScope?:PmCliErrorRecoveryPayload["option_scope"];
 /** Command family whose positional subcommand was split into invalid tokens. */
-unknownSubcommandPath?: string;
+unknownSubcommandPath?:string;
 /** Rejected positional subcommand token or token sequence. */
-unknownSubcommandToken?: string;
+unknownSubcommandToken?:string;
 /** Complete declared subcommand vocabulary for the command family. */
-unknownSubcommandAllowedValues?: string[];
+unknownSubcommandAllowedValues?:string[];
 /** Value that configures or reports suggested retry command for this contract. */
-suggestedRetryCommand?: string;
+suggestedRetryCommand?:string;
 /** Tokenized inspection retry that preserves a refusal without executing the guessed operation. */
-suggestedRetryArgs?: string[];
+suggestedRetryArgs?:string[];
 /** Existing item id verified against the selected tracker for collection recovery. */
-verifiedCollectionItemId?: string;
+verifiedCollectionItemId?:string;
 /** Installed extensions whose activation failed for this invocation. */
-failedExtensions?: Array<{
-name: string;
+failedExtensions?:Array<{
+name:string;
 }>;
 }
 interface PackageCommandHint {
 /** Published package name shown to the user (e.g. @unbrained/pm-guide-shell). */
-packageName: string;
+packageName:string;
 /** Exact CLI command that installs the bundled package by its install alias. */
-installCommand: string;
+installCommand:string;
 }
-declare function resolveKnownPackageCommandHint(commandToken: string): PackageCommandHint | undefined;
-declare function renderList(title: string, entries: string[]): string[];
-declare function normalizeRecoveryPayload(payload: PmCliErrorRecoveryPayload | undefined): PmCliErrorRecoveryPayload | undefined;
+declare function resolveKnownPackageCommandHint(commandToken:string):PackageCommandHint | undefined;
+declare function renderList(title:string,entries:string[]):string[];
+declare function normalizeRecoveryPayload(payload:PmCliErrorRecoveryPayload | undefined):PmCliErrorRecoveryPayload | undefined;
 /** Implements render guidance message for the public runtime surface of this module. */
-export declare function renderGuidanceMessage(message: GuidanceMessage): string;
-declare function guidanceToJsonEnvelope(message: GuidanceMessage, exitCode: number): JsonErrorEnvelope;
-declare function guidanceToClassification(message: GuidanceMessage): ErrorClassification;
-declare function dedupeStrings(values: string[]): string[];
-declare function buildFallbackTitleFromMessage(message: string): string | undefined;
+export declare function renderGuidanceMessage(message:GuidanceMessage):string;
+declare function guidanceToJsonEnvelope(message:GuidanceMessage,exitCode:number):JsonErrorEnvelope;
+declare function guidanceToClassification(message:GuidanceMessage):ErrorClassification;
+declare function dedupeStrings(values:string[]):string[];
+declare function buildFallbackTitleFromMessage(message:string):string | undefined;
 /** Merge SDK error evidence with CLI fallback guidance without discarding typed recovery or policy diagnostics. */
-declare function applyPmCliErrorContext(guidance: GuidanceMessage, rawMessage: string, context: PmCliErrorContext | undefined): GuidanceMessage;
-declare function commandExampleForRequiredOption(commandName: string | undefined, optionFlag: string, allowedTypes: string): string[];
-declare function buildCommanderRecoveryPayload(context: CommanderGuidanceContext | undefined, overrides?: Partial<PmCliErrorRecoveryPayload>): PmCliErrorRecoveryPayload | undefined;
-declare function appendIfMissing(entries: string[], value: string | undefined): string[];
+declare function applyPmCliErrorContext(guidance:GuidanceMessage,rawMessage:string,context:PmCliErrorContext | undefined):GuidanceMessage;
+declare function commandExampleForRequiredOption(commandName:string | undefined,optionFlag:string,allowedTypes:string):string[];
+declare function buildCommanderRecoveryPayload(context:CommanderGuidanceContext | undefined,overrides?:Partial<PmCliErrorRecoveryPayload>):PmCliErrorRecoveryPayload | undefined;
+declare function appendIfMissing(entries:string[],value:string | undefined):string[];
 /** Synthesize a copy-pasteable retry for the unquoted linked-test value shape `pm test <id> --add command npm test -- parser` by re-joining the shell-split value tokens into the documented quoted `key=value` form. Only fires when the item id already precedes the flag (so trailing tokens unambiguously belong to the value) and the token after `--add`/`--remove` is an entry-identity key. */
-export declare function buildLinkedTestQuotedRetryCommand(argv: string[] | undefined): string | undefined;
+export declare function buildLinkedTestQuotedRetryCommand(argv:string[] | undefined):string | undefined;
 /** Render concise initialization recovery or the bounded diagnostic for other failures. */
-export declare function formatPmCliErrorForDisplay(rawMessage: string, context?: PmCliErrorContext): string;
+export declare function formatPmCliErrorForDisplay(rawMessage:string,context?:PmCliErrorContext):string;
 /** Implements classify pm cli error for the public runtime surface of this module. */
-export declare function classifyPmCliError(rawMessage: string, context?: PmCliErrorContext): ErrorClassification;
+export declare function classifyPmCliError(rawMessage:string,context?:PmCliErrorContext):ErrorClassification;
 /** Implements format pm cli error for json for the public runtime surface of this module. */
-export declare function formatPmCliErrorForJson(rawMessage: string, exitCode: number, context?: PmCliErrorContext): ProjectedJsonErrorEnvelope;
+export declare function formatPmCliErrorForJson(rawMessage:string,exitCode:number,context?:PmCliErrorContext):ProjectedJsonErrorEnvelope;
 /** Implements format commander error for display for the public runtime surface of this module. */
-export declare function formatCommanderErrorForDisplay(rawMessage: string, commandName: string | undefined, allowedTypes: string, context?: CommanderGuidanceContext): string;
+export declare function formatCommanderErrorForDisplay(rawMessage:string,commandName:string | undefined,allowedTypes:string,context?:CommanderGuidanceContext):string;
 /** Implements classify commander error for the public runtime surface of this module. */
-export declare function classifyCommanderError(rawMessage: string, commandName: string | undefined, allowedTypes: string, context?: CommanderGuidanceContext): ErrorClassification;
+export declare function classifyCommanderError(rawMessage:string,commandName:string | undefined,allowedTypes:string,context?:CommanderGuidanceContext):ErrorClassification;
 /** Implements format commander error for json for the public runtime surface of this module. */
-export declare function formatCommanderErrorForJson(rawMessage: string, commandName: string | undefined, allowedTypes: string, exitCode: number, context?: CommanderGuidanceContext): ProjectedJsonErrorEnvelope;
+export declare function formatCommanderErrorForJson(rawMessage:string,commandName:string | undefined,allowedTypes:string,exitCode:number,context?:CommanderGuidanceContext):ProjectedJsonErrorEnvelope;
 /** Implements format unknown error for json for the public runtime surface of this module. */
-export declare function formatUnknownErrorForJson(rawMessage: string, exitCode: number): ProjectedJsonErrorEnvelope;
+export declare function formatUnknownErrorForJson(rawMessage:string,exitCode:number):ProjectedJsonErrorEnvelope;
 /** Implements classify unknown error for the public runtime surface of this module. */
-export declare function classifyUnknownError(rawMessage: string): ErrorClassification;
+export declare function classifyUnknownError(rawMessage:string):ErrorClassification;
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
-export declare const _testOnly: {
-applyPmCliErrorContext: typeof applyPmCliErrorContext;
-appendIfMissing: typeof appendIfMissing;
-buildCommanderRecoveryPayload: typeof buildCommanderRecoveryPayload;
-buildFallbackTitleFromMessage: typeof buildFallbackTitleFromMessage;
-commandExampleForRequiredOption: typeof commandExampleForRequiredOption;
-dedupeStrings: typeof dedupeStrings;
-guidanceToClassification: typeof guidanceToClassification;
-guidanceToJsonEnvelope: typeof guidanceToJsonEnvelope;
-normalizeRecoveryPayload: typeof normalizeRecoveryPayload;
-renderList: typeof renderList;
-resolveKnownPackageCommandHint: typeof resolveKnownPackageCommandHint;
+export declare const _testOnly:{
+applyPmCliErrorContext:typeof applyPmCliErrorContext;
+appendIfMissing:typeof appendIfMissing;
+buildCommanderRecoveryPayload:typeof buildCommanderRecoveryPayload;
+buildFallbackTitleFromMessage:typeof buildFallbackTitleFromMessage;
+commandExampleForRequiredOption:typeof commandExampleForRequiredOption;
+dedupeStrings:typeof dedupeStrings;
+guidanceToClassification:typeof guidanceToClassification;
+guidanceToJsonEnvelope:typeof guidanceToJsonEnvelope;
+normalizeRecoveryPayload:typeof normalizeRecoveryPayload;
+renderList:typeof renderList;
+resolveKnownPackageCommandHint:typeof resolveKnownPackageCommandHint;
 };
 export {};

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

@@ -4,102 +4,102 @@
  * Provides CLI runtime support for Extension Command Help.
  */
 import { Command } from "commander";
-import { type FlagDefinition, type RegisteredExtensionCommandDefinition, type RegisteredExtensionFlagDefinitions } from "../sdk/runtime-primitives.js";
-import type { PmCommandCapabilityFamily, PmCommandVisibilityTier } from "../sdk/agent-capability-contracts.js";
+import { type FlagDefinition,type RegisteredExtensionCommandDefinition,type RegisteredExtensionFlagDefinitions } from "../sdk/runtime-primitives.js";
+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;
+name:string;
 /** Value that configures or reports required for this contract. */
-required: boolean;
+required:boolean;
 /** Value that configures or reports variadic for this contract. */
-variadic: boolean;
+variadic:boolean;
 /** Value that configures or reports description for this contract. */
-description?: string;
+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;
+command:string;
 /** Value that configures or reports action for this contract. */
-action: string;
+action:string;
 /** Value that configures or reports description for this contract. */
-description?: string;
+description?:string;
 /** Value that configures or reports intent for this contract. */
-intent?: string;
+intent?:string;
 /** Value that configures or reports examples for this contract. */
-examples: string[];
+examples:string[];
 /** Value that configures or reports failure hints for this contract. */
-failure_hints: string[];
+failure_hints:string[];
 /** Value that configures or reports arguments for this contract. */
-arguments: ExtensionCommandArgumentHelpDescriptor[];
+arguments:ExtensionCommandArgumentHelpDescriptor[];
 /** Value that configures or reports flags for this contract. */
-flags: FlagDefinition[];
+flags:FlagDefinition[];
 /** Minimum agent surface tier declared by the package. */
-tier: PmCommandVisibilityTier;
+tier:PmCommandVisibilityTier;
 /** Capability family declared by the package. */
-family: PmCommandCapabilityFamily;
+family:PmCommandCapabilityFamily;
 /** Value that configures or reports source for this contract. */
-source?: {
-layer: "global" | "project";
-name: string;
-package?: string;
+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;
+flags:string;
 /** Value that configures or reports long for this contract. */
-long: string | null;
+long:string | null;
 /** Value that configures or reports short for this contract. */
-short: string | null;
+short:string | null;
 /** Value that configures or reports description for this contract. */
-description: string;
+description:string;
 /** Value that configures or reports takes value for this contract. */
-takes_value: boolean;
+takes_value:boolean;
 /** Value that configures or reports value required for this contract. */
-value_required: boolean;
+value_required:boolean;
 /** Value that configures or reports value name for this contract. */
-value_name: string | null;
+value_name:string | null;
 /** Value that configures or reports variadic for this contract. */
-variadic: boolean;
+variadic:boolean;
 /** Value that configures or reports required for this contract. */
-required: boolean;
+required:boolean;
 /** Value that configures or reports aliases for this contract. */
-aliases: string[];
+aliases:string[];
 /** Value that configures or reports alias for for this contract. */
-alias_for: string | null;
+alias_for:string | null;
 /** Fallback value used when callers do not provide an override. */
-default_value?: unknown;
+default_value?:unknown;
 }
 /** Implements normalize extension command path for the public runtime surface of this module. */
-export declare function normalizeExtensionCommandPath(commandPath: string): string;
+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;
-}>, definitions: ReadonlyArray<{
-command: string;
-layer: "project" | "global";
-name: string;
-}>): Map<string, string>;
+export declare function buildCanonicalExtensionAliases(handlers:ReadonlyArray<{
+command:string;
+layer:"project" | "global";
+name:string;
+}>,definitions:ReadonlyArray<{
+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;
+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;
+export declare function resolveExtensionFlagArity(definition:Readonly<FlagDefinition>):{
+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>;
+export declare function collectDynamicExtensionFlagHelpByCommand(registrations:RegisteredExtensionFlagDefinitions[]):Map<string,string>;
 /** Implements collect extension command help descriptors for the public runtime surface of this module. */
-export declare function collectExtensionCommandHelpDescriptors(commandHandlers: string[], commandDefinitions: RegisteredExtensionCommandDefinition[], flagRegistrations: RegisteredExtensionFlagDefinitions[], canonicalAliases?: ReadonlyMap<string, string>): Map<string, ExtensionCommandHelpDescriptor>;
+export declare function collectExtensionCommandHelpDescriptors(commandHandlers:string[],commandDefinitions:RegisteredExtensionCommandDefinition[],flagRegistrations:RegisteredExtensionFlagDefinitions[],canonicalAliases?:ReadonlyMap<string,string>):Map<string,ExtensionCommandHelpDescriptor>;
 /** Implements apply dynamic extension arguments for the public runtime surface of this module. */
-export declare function applyDynamicExtensionArguments(command: Command, descriptor: ExtensionCommandHelpDescriptor): void;
+export declare function applyDynamicExtensionArguments(command:Command,descriptor:ExtensionCommandHelpDescriptor):void;
 /** Implements apply dynamic extension flag options for the public runtime surface of this module. */
-export declare function applyDynamicExtensionFlagOptions(command: Command, definitions: FlagDefinition[]): void;
+export declare function applyDynamicExtensionFlagOptions(command:Command,definitions:FlagDefinition[]):void;
 /**
  * Builds the "Extension-provided flags" help block for only the definitions that
  * are NOT already rendered as real commander options on {@link command}. After
@@ -108,29 +108,29 @@ export declare function applyDynamicExtensionFlagOptions(command: Command, defin
  * flag in `--help` output; this filters those already-listed flags out so the
  * block is emitted only when it carries flags the Options section does not.
  */
-export declare function buildResidualDynamicExtensionFlagHelp(command: Command, definitions: FlagDefinition[]): string | null;
+export declare function buildResidualDynamicExtensionFlagHelp(command:Command,definitions:FlagDefinition[]):string | null;
 /** Implements build dynamic extension help option summaries for the public runtime surface of this module. */
-export declare function buildDynamicExtensionHelpOptionSummaries(descriptor: ExtensionCommandHelpDescriptor | undefined): HelpOptionSummary[];
+export declare function buildDynamicExtensionHelpOptionSummaries(descriptor:ExtensionCommandHelpDescriptor | undefined):HelpOptionSummary[];
 /** Implements merge help option summaries for the public runtime surface of this module. */
-export declare function mergeHelpOptionSummaries(base: HelpOptionSummary[], extension: HelpOptionSummary[]): HelpOptionSummary[];
+export declare function mergeHelpOptionSummaries(base:HelpOptionSummary[],extension:HelpOptionSummary[]):HelpOptionSummary[];
 /** Implements build dynamic extension command metadata help for the public runtime surface of this module. */
-export declare function buildDynamicExtensionCommandMetadataHelp(descriptor: ExtensionCommandHelpDescriptor): string | null;
+export declare function buildDynamicExtensionCommandMetadataHelp(descriptor:ExtensionCommandHelpDescriptor):string | null;
 /** Implements command aliases for the public runtime surface of this module. */
-export declare function commandAliases(command: Command): string[];
+export declare function commandAliases(command:Command):string[];
 /** Implements find direct child command for the public runtime surface of this module. */
-export declare function findDirectChildCommand(parent: Command, name: string): Command | null;
+export declare function findDirectChildCommand(parent:Command,name:string):Command | null;
 /** Implements find command by path for the public runtime surface of this module. */
-export declare function findCommandByPath(root: Command, pathParts: string[]): Command | null;
+export declare function findCommandByPath(root:Command,pathParts:string[]):Command | null;
 /** Implements ensure command path for the public runtime surface of this module. */
-export declare function ensureCommandPath(root: Command, pathParts: string[]): Command | null;
+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;
+export declare function findExtensionCommandPathCollision(root:Command,pathParts: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;
+export declare function buildExtensionCommandCollisionWarning(root:Command,commandPath:string,aliases:ReadonlyMap<string,string>,descriptor:ExtensionCommandHelpDescriptor | undefined,hasHandler?:boolean):string | null;
 /** Collect deterministic extension command paths while reporting and excluding aliases that collide with core ownership. */
-export declare function collectSafeExtensionCommandPaths(root: Command, commandHandlers: readonly string[], descriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>, aliases: ReadonlyMap<string, string>, onCollision: (warning: string) => void): string[];
+export declare function collectSafeExtensionCommandPaths(root:Command,commandHandlers:readonly string[],descriptors:ReadonlyMap<string,ExtensionCommandHelpDescriptor>,aliases:ReadonlyMap<string,string>,onCollision:(warning:string) => void):string[];
 /** Record and surface one extension collision with stable recovery guidance. */
-export declare function reportExtensionCommandCollision(activationWarnings: string[], report: (message: string) => void, warning: string): void;
+export declare function reportExtensionCommandCollision(activationWarnings:string[],report:(message:string) => void,warning:string):void;

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]="c077f66e-bac4-58af-92cd-a19c30ada04d")}catch{}})();import{Option}from"commander";import{PM_RELOCATED_COMMAND_ALIASES}from"../sdk/cli-contracts/command-aliases.js";import{resolveExtensionFlagValueContract,resolveExtensionLongFlagName}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 value=resolveExtensionFlagValueContract(definition);return{takesValue:value.value_arity!=="none",valueName:value.value_name}}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{value_name:valueName,value_arity:arity}=resolveExtensionFlagValueContract(definition),optionValueSuffix=valueName?arity==="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,value=resolveExtensionFlagValueContract(definition),required=toOptionalBoolean(definition.required)===!0;return{flags,long:normalizedLong,short:normalizedShort,description:formatDynamicExtensionOptionDescription(definition),takes_value:value.value_arity!=="none",value_required:value.value_arity==="required",value_name:value.value_name,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};