@unbrained/pm-cli 2026.8.25 → 2026.8.27

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

@@ -31,6 +31,12 @@ export interface HelpSubcommandSummary {
     tier: PmCommandVisibilityTier;
     /** Shared command capability family. */
     family: PmCommandCapabilityFamily;
+    /** Canonical command path when this row is an executable alias. */
+    alias_for?: string;
+    /** Compatibility lifecycle declared by the canonical alias contract. */
+    alias_lifecycle?: "permanent" | "deprecated";
+    /** True when callers should migrate from this executable spelling. */
+    deprecated?: true;
 }
 type ExtensionCommandSurface = Pick<ExtensionCommandHelpDescriptor, "tier" | "family">;
 declare function resolveExtensionCommandSurface(commandPath: string, descriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>, allowDescendants?: boolean): ExtensionCommandSurface | undefined;
@@ -40,7 +46,7 @@ declare function buildOptionAliasMap(options: unknown[]): Map<string, string[]>;
 declare function buildHelpOptionSummaries(command: Command): HelpOptionSummary[];
 declare function compactHelpOptionAliases(options: HelpOptionSummary[]): HelpOptionSummary[];
 declare function buildHelpArgumentSummaries(command: Command): HelpArgumentSummary[];
-declare function buildHelpSubcommandSummaries(command: Command, extensionDescriptors?: ReadonlyMap<string, ExtensionCommandHelpDescriptor>): HelpSubcommandSummary[];
+declare function buildHelpSubcommandSummaries(command: Command, extensionDescriptors?: ReadonlyMap<string, ExtensionCommandHelpDescriptor>, includeAll?: boolean): HelpSubcommandSummary[];
 interface PositionalActionHelpProjection {
     arguments: HelpArgumentSummary[];
     options: HelpOptionSummary[];
@@ -48,7 +54,7 @@ interface PositionalActionHelpProjection {
     usage: string;
 }
 /** Build the command/action structural view shared by every JSON help field. */
-declare function buildPositionalActionHelpProjection(action: PmPositionalActionContract | undefined, targetCommand: Command, resolvedPath: string, allOptions: HelpOptionSummary[], extensionDescriptors?: ReadonlyMap<string, ExtensionCommandHelpDescriptor>): PositionalActionHelpProjection;
+declare function buildPositionalActionHelpProjection(action: PmPositionalActionContract | undefined, targetCommand: Command, resolvedPath: string, allOptions: HelpOptionSummary[], extensionDescriptors?: ReadonlyMap<string, ExtensionCommandHelpDescriptor>, includeAll?: boolean): PositionalActionHelpProjection;
 declare function buildJsonHelpPayload(rootProgram: Command, targetCommand: Command, argv: string[], requestedPath: string[], extensionDescriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>): Record<string, unknown>;
 /** Implements maybe render bootstrap json help for the public runtime surface of this module. */
 export declare function maybeRenderBootstrapJsonHelp(rootProgram: Command, argv: string[], extensionDescriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>): Promise<boolean>;

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

@@ -1,9 +1,9 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="26c3efa6-b820-5370-b0ab-65b08bc007ec")}catch(e){}}();
-import { hasSubcommandFlagContractsForCommand, PM_CORE_COMMAND_NAMES, } from "../sdk/cli-contracts.js";
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="43167bb0-7cc0-599f-8587-8583d398f1ad")}catch(e){}}();
+import { hasSubcommandFlagContractsForCommand, PM_COMMAND_ALIAS_CONTRACTS, PM_CORE_COMMAND_NAMES, } from "../sdk/cli-contracts.js";
 import { commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveTypeDefinition, EXIT_CODE, printError, writeStdout, } from "../sdk/runtime-primitives.js";
 import { buildDynamicExtensionHelpOptionSummaries, mergeHelpOptionSummaries, findCommandByPath, findDirectChildCommand, commandAliases, } from "./extension-command-help.js";
-import { getPmCommandHelpVisibilityTier, normalizeHelpCommandPath, resolveHelpDetailMode, resolveHelpNarrative, } from "./help-content.js";
+import { getPmCommandHelpVisibilityTier, isFullHelpDiscovery, normalizeHelpCommandPath, resolveHelpDetailMode, resolveHelpNarrative, } from "./help-content.js";
 import { getCommandPath } from "./registration-helpers.js";
 import { parseBootstrapGlobalOptions, parseBootstrapHelpRequest, parseBootstrapCommandName, parseBootstrapTypeValue, } from "./bootstrap-args.js";
 import { extractProvidedOptionFlags, renderPmCommand } from "./argv-utils.js";
@@ -206,23 +206,40 @@ function buildHelpArgumentSummaries(command) {
         };
     });
 }
-function buildHelpSubcommandSummaries(command, extensionDescriptors = new Map()) {
-    return command
-        .createHelp()
-        .visibleCommands(command)
+function buildHelpSubcommandSummaries(command, extensionDescriptors = new Map(), includeAll = false) {
+    const visible = command.createHelp().visibleCommands(command);
+    const candidates = includeAll
+        ? [...new Set([...visible, ...command.commands])]
+        : visible;
+    return candidates
         .filter((entry) => entry.name() !== "help" || command.parent === null)
+        .filter((entry) => !includeAll ||
+        (getPmCommandHelpVisibilityTier(entry) ??
+            resolvePmCommandVisibilityTier(entry.name())) !== "internal")
         .map((entry) => {
         const commandPath = normalizeHelpCommandPath(getCommandPath(entry));
         const rootCommand = commandPath.split(" ")[0];
-        const extensionDescriptor = resolveExtensionCommandSurface(commandPath, extensionDescriptors, getPmCommandHelpVisibilityTier(entry) !== undefined);
+        const declaredTier = getPmCommandHelpVisibilityTier(entry);
+        const extensionDescriptor = resolveExtensionCommandSurface(commandPath, extensionDescriptors, declaredTier !== undefined);
+        const aliasContract = PM_COMMAND_ALIAS_CONTRACTS.find(({ alias }) => alias === commandPath);
         return {
             name: entry.name().trim(),
             aliases: commandAliases(entry),
             description: entry.description().trim(),
             tier: extensionDescriptor?.tier ??
+                declaredTier ??
                 resolvePmCommandVisibilityTier(rootCommand),
             family: extensionDescriptor?.family ??
                 resolvePmCommandCapabilityFamily(rootCommand),
+            ...(aliasContract
+                ? {
+                    alias_for: aliasContract.canonical,
+                    alias_lifecycle: aliasContract.lifecycle,
+                    ...(aliasContract.lifecycle === "deprecated"
+                        ? { deprecated: true }
+                        : {}),
+                }
+                : {}),
         };
     })
         .sort((left, right) => left.name.localeCompare(right.name));
@@ -263,11 +280,23 @@ function resolveJsonHelpCapabilityFamily(rootCommandPath, extensionDescriptor) {
     return (extensionDescriptor?.family ??
         resolvePmCommandCapabilityFamily(rootCommandPath));
 }
+function projectFullCommandAliases(rootProgram, targetCommand, fullDiscovery) {
+    if (targetCommand !== rootProgram || !fullDiscovery)
+        return undefined;
+    return PM_COMMAND_ALIAS_CONTRACTS.map((contract) => ({
+        alias: contract.alias,
+        canonical: contract.canonical,
+        canonical_argv: [...contract.canonical_argv],
+        lifecycle: contract.lifecycle,
+        hidden: contract.hidden,
+        deprecated: contract.lifecycle === "deprecated",
+    }));
+}
 /** Build the command/action structural view shared by every JSON help field. */
-function buildPositionalActionHelpProjection(action, targetCommand, resolvedPath, allOptions, extensionDescriptors = new Map()) {
+function buildPositionalActionHelpProjection(action, targetCommand, resolvedPath, allOptions, extensionDescriptors = new Map(), includeAll = false) {
     if (!action) {
         const argumentsList = buildHelpArgumentSummaries(targetCommand);
-        const registeredSubcommands = buildHelpSubcommandSummaries(targetCommand, extensionDescriptors);
+        const registeredSubcommands = buildHelpSubcommandSummaries(targetCommand, extensionDescriptors, includeAll);
         const registeredSubcommandNames = new Set(registeredSubcommands.map(({ name }) => name));
         return {
             arguments: argumentsList,
@@ -316,6 +345,7 @@ function buildPositionalActionHelpProjection(action, targetCommand, resolvedPath
 }
 function buildJsonHelpPayload(rootProgram, targetCommand, argv, requestedPath, extensionDescriptors) {
     const detailMode = resolveHelpDetailMode(argv);
+    const fullDiscovery = isFullHelpDiscovery(argv);
     const commanderPath = normalizeHelpCommandPath(getCommandPath(targetCommand));
     const requestedCommandPath = normalizeHelpCommandPath(requestedPath.join(" "));
     const resolvedPath = requestedCommandPath.length > commanderPath.length
@@ -334,7 +364,8 @@ function buildJsonHelpPayload(rootProgram, targetCommand, argv, requestedPath, e
         : undefined;
     const narrative = buildJsonHelpNarrative(detailMode, fallbackNarrative, extensionDescriptor);
     const allOptionSummaries = compactHelpOptionAliases(mergeHelpOptionSummaries(buildHelpOptionSummaries(targetCommand), buildDynamicExtensionHelpOptionSummaries(extensionDescriptor)));
-    const projection = buildPositionalActionHelpProjection(positionalAction, targetCommand, projectedPath, allOptionSummaries, extensionDescriptors);
+    const projection = buildPositionalActionHelpProjection(positionalAction, targetCommand, projectedPath, allOptionSummaries, extensionDescriptors, fullDiscovery);
+    const fullCommandAliases = projectFullCommandAliases(rootProgram, targetCommand, fullDiscovery);
     return {
         format: "pm_help_v1",
         detail_mode: detailMode,
@@ -356,6 +387,9 @@ function buildJsonHelpPayload(rootProgram, targetCommand, argv, requestedPath, e
         options: projection.options,
         subcommands: projection.subcommands,
         has_subcommands: projection.subcommands.length > 0,
+        ...(fullCommandAliases === undefined
+            ? {}
+            : { command_aliases: fullCommandAliases }),
     };
 }
 /** Implements maybe render bootstrap json help for the public runtime surface of this module. */
@@ -529,4 +563,4 @@ export const _testOnly = {
     resolveExtensionCommandSurface,
 };
 //# sourceMappingURL=help-json-payload.js.map
-//# debugId=26c3efa6-b820-5370-b0ab-65b08bc007ec
+//# debugId=43167bb0-7cc0-599f-8587-8583d398f1ad

package/dist/cli/main.js

@@ -3,17 +3,17 @@
  * @module cli/main
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ffd55bde-cc30-529f-a6f9-ec43abe4efba")}catch(e){}}();
-import { Command } from "commander";
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f947c7f0-adf8-59da-8bc7-9cd746b05839")}catch(e){}}();
+import { Command, CommanderError } from "commander";
 import { activateExtensions, clearActiveExtensionHooks, createCoreCommandHookContext, resetActiveExtensionRuntimeState, createEmptyExtensionRegistrationRegistry, discoverExtensions, getActiveCommandResult, getActiveExtensionRegistrations, loadExtensions, consumeAfterCommandAffectedItems, runActiveCommandHandler, runActiveParserOverride, runActivePreflightOverride, runAfterCommandHooks, runBeforeCommandHooks, setActiveCommandResult, setActiveCommandContext, setActiveExtensionCommands, setActiveExtensionHooks, setActiveExtensionParsers, setActiveExtensionPreflight, setActiveExtensionRegistrations, setActiveExtensionRenderers, setActiveExtensionServices, pathExists, resolvePmCliVersion, resolvePmPackageRootFromModule, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, EXIT_CODE, resolveTelemetryErrorCategory, PmCliError, asRecordOrNull, printError, printResult, maybeRunFirstUseTelemetryPrompt, emitTelemetryErrorEvent, startTelemetryCommand, deriveTelemetryCommandResolution, sentryCaptureCliError, sentryFinishCommandSpan, sentryFlush, sentryLogCliUsageError, sentrySetCommandContext, sentryStartCommandSpan, ensureSentryInit, getSettingsPath, resolvePmRoot, readSettings, readSettingsWithMetadata, runWithWorkspaceHarnessSignalDescriptors, createLazyModule, } from "../sdk/runtime-primitives.js";
 import { runWithReproducibleProcessEnvironment } from "../sdk/reproducibility/process.js";
 import { resolveSubcommandFlagContractsForCommand } from "../sdk/cli-contracts.js";
 import { createExtensionCommandSdk } from "../sdk/extension-command-context.js";
 import { PmClient } from "../sdk/runtime.js";
 import { coerceLooseCommandOptionsWithFlagDefinitions, collectLooseCommandOptionKeysForDefinitions, collectLoosePositionalArgs, parseLooseCommandOptions, stripLooseCommandOptionTokens, validateLooseCommandOptionsWithFlagDefinitions, } from "./extension-command-options.js";
-import { attachRichHelpText, setPmCommandHelpVisibilityTier, } from "./help-content.js";
+import { attachRichHelpText, isFullHelpDiscovery, setPmCommandHelpVisibilityTier, } from "./help-content.js";
 import { finishActiveTelemetryCommand, recordAfterCommandContextUsage } from "./after-command-context-usage.js";
-import { extractProvidedOptionFlags, normalizeLongOptionFlag, redactSensitiveCommandArgs, renderPmCommand, } from "./argv-utils.js";
+import { extractProvidedOptionFlags, normalizeLongOptionFlag, redactSensitiveCommandArgs, renderPmCommand } from "./argv-utils.js";
 import { classifyCommanderError, classifyPmCliError, classifyUnknownError, formatPmCliErrorForDisplay, formatPmCliErrorForJson, formatUnknownErrorForJson, projectLeanErrorEnvelope, } from "./error-guidance.js";
 import { describeUnknownError, isCommanderError, normalizeThrownExitCode, readThrownExitCode, wrapThrownErrorForSentry } from "../sdk/error-runtime.js";
 import { applyDefaultOutputFormat, clearResolvedGlobalOptions, collect, formatHookWarnings, getCommandPath, getGlobalOptions, invalidateSearchCachesForMutation, setResolvedGlobalOptions, syncCommanderActionOptions, } from "./registration-helpers.js";
@@ -51,7 +51,7 @@ function recordCliReadOutputInvocationProvenance(actionCommand, commandPath, com
     const rawArgs = rootCommand.rawArgs;
     const providedFlags = new Set(extractProvidedOptionFlags(rawArgs.slice(2)));
     const contract = PM_READ_OUTPUT_SURFACE_CONTRACTS.find((candidate) => candidate.command === surface);
-    const explicitLegacyAliases = Object.values(contract.dimensions).flatMap((dimension) => dimension.legacy_aliases.flatMap((alias) => providedFlags.has(alias.flag) ? [alias.flag] : []));
+    const explicitLegacyAliases = Object.values(contract.dimensions).flatMap((dimension) => dimension.legacy_aliases.flatMap((alias) => (providedFlags.has(alias.flag) ? [alias.flag] : [])));
     const previous = Reflect.get(commandOptions, READ_OUTPUT_INVOCATION_PROVENANCE);
     Reflect.set(commandOptions, READ_OUTPUT_INVOCATION_PROVENANCE, {
         canonical_include_modes: previous?.canonical_include_modes ?? [],
@@ -115,18 +115,14 @@ function inferMissingFieldsFromErrorMessage(message) {
     return normalized.length > 0 ? normalized : undefined;
 }
 function inferMissingFieldsForRecovery(rawMessage, invocationArgv, existingRecovery) {
-    if (existingRecovery?.suggested_retry ||
-        rawMessage.includes("failed in extension handler (") ||
-        !/\b(?:missing|required|requires)\b/i.test(rawMessage)) {
+    if (existingRecovery?.suggested_retry || rawMessage.includes("failed in extension handler (") || !/\b(?:missing|required|requires)\b/i.test(rawMessage)) {
         return undefined;
     }
     const providedFields = extractProvidedOptionFlags(invocationArgv);
     const providedSet = new Set(providedFields.map((flag) => normalizeLongOptionFlag(flag) ?? flag));
     const rawInferred = inferMissingFieldsFromErrorMessage(rawMessage);
     const commandName = invocationArgv.find((token) => program.commands.some((candidate) => candidate.name() === token));
-    const command = commandName
-        ? program.commands.find((candidate) => candidate.name() === commandName)
-        : undefined;
+    const command = commandName ? program.commands.find((candidate) => candidate.name() === commandName) : undefined;
     const declaredFlags = new Set([...program.options, ...(command?.options ?? [])].flatMap((option) => option.flags
         .split(/[ ,|]+/)
         .map((flag) => normalizeLongOptionFlag(flag))
@@ -136,8 +132,7 @@ function inferMissingFieldsForRecovery(rawMessage, invocationArgv, existingRecov
         if (providedSet.has(normalized)) {
             return false;
         }
-        return (declaredFlags.has(normalized) ||
-            extensionFlagTakesValueForInvocation(invocationArgv, commandName, normalized, activeRuntimeExtensionCommandDescriptors) !== undefined);
+        return declaredFlags.has(normalized) || extensionFlagTakesValueForInvocation(invocationArgv, commandName, normalized, activeRuntimeExtensionCommandDescriptors) !== undefined;
     });
     return trulyMissing && trulyMissing.length > 0 ? trulyMissing : undefined;
 }
@@ -151,11 +146,7 @@ function resolveRecoverySuggestedRetry(invocationArgv, attemptedCommand, inferre
     const command = commandName ? program.commands.find((candidate) => candidate.name() === commandName) : undefined;
     const missingOption = normalizedMissing ? command?.options.find((option) => option.flags.split(/[ ,|]+/).includes(normalizedMissing)) : undefined;
     const extensionFlagTakesValue = extensionFlagTakesValueForInvocation(invocationArgv, commandName, normalizedMissing, activeRuntimeExtensionCommandDescriptors);
-    const missingTokens = normalizedMissing
-        ? missingOption?.isBoolean() === true || extensionFlagTakesValue === false
-            ? [normalizedMissing]
-            : [normalizedMissing, "<value>"]
-        : [];
+    const missingTokens = normalizedMissing ? (missingOption?.isBoolean() === true || extensionFlagTakesValue === false ? [normalizedMissing] : [normalizedMissing, "<value>"]) : [];
     const suggestedRetry = normalizedMissing ? renderAttemptedCommand([...invocationArgv, ...missingTokens]) : attemptedCommand;
     return suggestedRetry === attemptedCommand ? undefined : suggestedRetry;
 }
@@ -203,18 +194,10 @@ function buildPmCliRecoveryContext(context, invocationArgv, rawMessage) {
     const existingRecovery = rawExistingRecovery && safeInvocationArgv.includes("history-redact")
         ? {
             ...rawExistingRecovery,
-            ...(rawExistingRecovery.attempted_command
-                ? { attempted_command: renderAttemptedCommand(safeInvocationArgv) }
-                : {}),
-            ...(rawExistingRecovery.normalized_args
-                ? { normalized_args: [...safeInvocationArgv] }
-                : {}),
-            ...(rawExistingRecovery.suggested_retry
-                ? { suggested_retry: renderAttemptedCommand(safeInvocationArgv) }
-                : {}),
-            ...(rawExistingRecovery.suggested_retry_args
-                ? { suggested_retry_args: [...safeInvocationArgv] }
-                : {}),
+            ...(rawExistingRecovery.attempted_command ? { attempted_command: renderAttemptedCommand(safeInvocationArgv) } : {}),
+            ...(rawExistingRecovery.normalized_args ? { normalized_args: [...safeInvocationArgv] } : {}),
+            ...(rawExistingRecovery.suggested_retry ? { suggested_retry: renderAttemptedCommand(safeInvocationArgv) } : {}),
+            ...(rawExistingRecovery.suggested_retry_args ? { suggested_retry_args: [...safeInvocationArgv] } : {}),
         }
         : rawExistingRecovery;
     if (existingRecovery?.recovery_mode === "compact" && !explainRequested) {
@@ -372,8 +355,7 @@ function buildPostActionTelemetryOutcome() {
     const exitCode = processExitCode ?? resultExitCode ?? EXIT_CODE.SUCCESS;
     const ok = isPmSuccessfulExitCode(exitCode);
     const errorCode = readRecordString(result, "error_code", "errorCode") ?? inferPostActionErrorCode(ok, exitCode);
-    const errorCategory = normalizeTelemetryErrorCategory(readRecordString(result, "error_category", "errorCategory")) ??
-        (!ok ? resolveTelemetryErrorCategory(errorCode) : undefined);
+    const errorCategory = normalizeTelemetryErrorCategory(readRecordString(result, "error_category", "errorCategory")) ?? (!ok ? resolveTelemetryErrorCategory(errorCode) : undefined);
     const errorMessage = !ok ? (inferPostActionFailureMessage(result) ?? `command_exit_${exitCode}`) : undefined;
     const commandResolution = normalizeTelemetryCommandResolution(readRecordString(result, "command_resolution", "commandResolution")) ??
         deriveTelemetryCommandResolution({
@@ -546,6 +528,9 @@ function forwardReadOutputIncludeModes(actionCommand, commandPath, globalOptions
     if (requested === undefined)
         return;
     const { selectors, modes } = applyReadOutputIncludeModes(commandPath, requested, commandOptions);
+    if (commandPath === "get" && typeof commandOptions.fields === "string") {
+        actionCommand.setOptionValueWithSource("fields", commandOptions.fields, "cli");
+    }
     if (modes.length === 0)
         return;
     copyReadOutputInvocationProvenance(commandOptions, actionCommand);
@@ -804,9 +789,7 @@ async function registerRuntimeSchemaFieldFlags(rootProgram, invocationArgv) {
     if (!(await pathExists(getSettingsPath(pmRoot)))) {
         return;
     }
-    const cachedDiscovery = runtimeExtensionDiscoverySnapshotCache?.key === buildRuntimeExtensionDiscoverySnapshotCacheKey(pmRoot)
-        ? runtimeExtensionDiscoverySnapshotCache.snapshot
-        : null;
+    const cachedDiscovery = runtimeExtensionDiscoverySnapshotCache?.key === buildRuntimeExtensionDiscoverySnapshotCacheKey(pmRoot) ? runtimeExtensionDiscoverySnapshotCache.snapshot : null;
     const settings = cachedDiscovery === null ? await readSettings(pmRoot) : cachedDiscovery.settings;
     const fieldRegistry = resolveRuntimeFieldRegistry(settings.schema);
     const mappings = [
@@ -995,23 +978,19 @@ function extensionProvidesTemplatesRuntime(commands) {
 }
 /** Match direct command paths plus the built-in create-template bridge. */
 function matchesStaticExtensionCommand(commands, probe) {
-    return (commands.some((command) => activationCommandMatchesProbe(command, probe)) ||
-        (commandPathNeedsTemplateExtensions(probe) &&
-            extensionProvidesTemplatesRuntime(commands)));
+    return commands.some((command) => activationCommandMatchesProbe(command, probe)) || (commandPathNeedsTemplateExtensions(probe) && extensionProvidesTemplatesRuntime(commands));
 }
 /** Identify contribution surfaces that participate in global runtime behavior. */
 function hasGlobalExtensionContributions(contributions) {
     const contributionCounts = [
         entriesOrEmpty(contributions.hooks).length,
-        (contributions.preflight_overrides ?? 0) -
-            entriesOrEmpty(contributions.preflight_ownership).length,
+        (contributions.preflight_overrides ?? 0) - entriesOrEmpty(contributions.preflight_ownership).length,
         entriesOrEmpty(contributions.item_types).length,
         entriesOrEmpty(contributions.item_fields).length,
         entriesOrEmpty(contributions.relationship_kinds).length,
         entriesOrEmpty(contributions.service_overrides).length,
         entriesOrEmpty(contributions.assurance_providers).length,
-        entriesOrEmpty(contributions.renderer_overrides).length -
-            entriesOrEmpty(contributions.renderer_ownership).length,
+        entriesOrEmpty(contributions.renderer_overrides).length - entriesOrEmpty(contributions.renderer_ownership).length,
     ];
     return contributionCounts.some((count) => count > 0);
 }
@@ -1024,8 +1003,7 @@ function resolveStaticExtensionActivationDecision(extension, probe) {
     const commands = extensionActivationCommands(extension);
     if (matchesStaticExtensionCommand(commands, probe))
         return true;
-    if (extensionCapabilities(extension).has("search") &&
-        commandPathNeedsSearchExtensions(probe.commandPath)) {
+    if (extensionCapabilities(extension).has("search") && commandPathNeedsSearchExtensions(probe.commandPath)) {
         return true;
     }
     if (extension.contributions) {
@@ -1220,7 +1198,10 @@ async function loadRuntimeExtensionSnapshot(pmRoot, probe, readSettingsFn = read
             loadedCount: loadResult.loaded.length,
             loadFailedCount: loadResult.failed.length,
             activationFailedCount: activationResult.failed.length,
-            contextIntentPackages: loadResult.loaded.map(({ name, module }) => ({ name, module })),
+            contextIntentPackages: loadResult.loaded.map(({ name, module }) => ({
+                name,
+                module,
+            })),
         };
         runtimeExtensionSnapshotCache = {
             key: cacheKey,
@@ -1353,9 +1334,7 @@ async function runRequiredExtensionCommand(command, options, globalOptions, exte
             const causeSuffix = cause ? ` ${cause}` : "";
             throw new PmCliError(`Command "${commandPath}" failed in extension handler (${warningCode}).${causeSuffix}`, EXIT_CODE.GENERIC_FAILURE, {
                 code: extensionCommandResult.errorCode ?? "command_failed",
-                nextSteps: extensionCommandResult.remediation
-                    ? [extensionCommandResult.remediation]
-                    : undefined,
+                nextSteps: extensionCommandResult.remediation ? [extensionCommandResult.remediation] : undefined,
             });
         }
         throw new PmCliError(`Command "${commandPath}" is provided by extensions and is not currently available.`, EXIT_CODE.NOT_FOUND);
@@ -1513,12 +1492,10 @@ function applyDynamicExtensionRootHelpVisibility(rootProgram, preexistingTopLeve
     const tierRank = { core: 0, standard: 1, full: 2, internal: 3 };
     const applyVisibility = (command, pathParts) => {
         const commandPath = pathParts.join(" ");
-        const matchingDescriptors = [...descriptors.entries()]
-            .filter(([path]) => path === commandPath || path.startsWith(`${commandPath} `))
-            .map(([, descriptor]) => descriptor);
+        const matchingDescriptors = [...descriptors.entries()].filter(([path]) => path === commandPath || path.startsWith(`${commandPath} `)).map(([, descriptor]) => descriptor);
         const tier = matchingDescriptors.length === 0
             ? "standard"
-            : matchingDescriptors.reduce((selected, descriptor) => tierRank[descriptor.tier] < tierRank[selected] ? descriptor.tier : selected, "internal");
+            : matchingDescriptors.reduce((selected, descriptor) => (tierRank[descriptor.tier] < tierRank[selected] ? descriptor.tier : selected), "internal");
         setPmCommandHelpVisibilityTier(command, tier);
         for (const child of command.commands) {
             applyVisibility(child, [...pathParts, child.name()]);
@@ -1942,7 +1919,10 @@ function resolveCoreCommandRegistrationSelection(invocationArgv) {
     return REGISTER_ALL_CORE_COMMAND_FAMILIES;
 }
 function shouldAttachRichHelpTextForInvocation(invocationArgv) {
-    return invocationArgv.length === 0 || parseBootstrapHelpRequest(invocationArgv).requested;
+    return (invocationArgv.length === 0 ||
+        parseBootstrapHelpRequest(invocationArgv).requested ||
+        (invocationArgv.includes("--explain") &&
+            parseBootstrapCommandName(invocationArgv) === undefined));
 }
 const IDEMPOTENT_TOP_LEVEL_REGISTRATION = Symbol("pmCliIdempotentTopLevelRegistration");
 /**
@@ -1988,9 +1968,7 @@ async function registerCoreCommandFamilies(rootProgram, selection) {
     }
     if (selection.listQuery) {
         const { registerListQueryCommands } = await loadListQueryRegistrationModule();
-        const commandFilter = typeof selection.targetCommandName === "string" && LIST_QUERY_COMMAND_NAMES.has(selection.targetCommandName)
-            ? new Set([selection.targetCommandName])
-            : undefined;
+        const commandFilter = typeof selection.targetCommandName === "string" && LIST_QUERY_COMMAND_NAMES.has(selection.targetCommandName) ? new Set([selection.targetCommandName]) : undefined;
         registerListQueryCommands(rootProgram, commandFilter ? { commandFilter } : undefined);
     }
     if (selection.mutation) {
@@ -2008,6 +1986,9 @@ function shouldRegisterDynamicExtensionPaths(_rootProgram, invocationArgv) {
     if (invocationRequestsVersion(invocationArgv)) {
         return false;
     }
+    if (isFullHelpDiscovery(invocationArgv)) {
+        return true;
+    }
     const helpRequest = parseBootstrapHelpRequest(invocationArgv);
     if (helpRequest.requested) {
         return true;
@@ -2046,20 +2027,12 @@ function redactSensitiveFlagTypo(params) {
         ? params.argv.map((token) => {
             const equalsIndex = token.indexOf("=");
             const flag = equalsIndex >= 0 ? token.slice(0, equalsIndex) : token;
-            return flag === rawTypoFlag
-                ? equalsIndex >= 0
-                    ? `${sensitiveCanonicalFlag}${token.slice(equalsIndex)}`
-                    : sensitiveCanonicalFlag
-                : token;
+            return flag === rawTypoFlag ? (equalsIndex >= 0 ? `${sensitiveCanonicalFlag}${token.slice(equalsIndex)}` : sensitiveCanonicalFlag) : token;
         })
         : params.argv;
     const safeArgv = redactSensitiveCommandArgs(typoNormalizedArgv);
-    const safeTypoDisplay = sensitiveCanonicalFlag && rawTypoEqualsIndex >= 0
-        ? `${rawTypoFlag}=[redacted]`
-        : rawTypoToken;
-    const safeNormalizedDisplay = sensitiveCanonicalFlag && params.normalizedDisplay.includes("=")
-        ? `${sensitiveCanonicalFlag}=[redacted]`
-        : params.normalizedDisplay;
+    const safeTypoDisplay = sensitiveCanonicalFlag && rawTypoEqualsIndex >= 0 ? `${rawTypoFlag}=[redacted]` : rawTypoToken;
+    const safeNormalizedDisplay = sensitiveCanonicalFlag && params.normalizedDisplay.includes("=") ? `${sensitiveCanonicalFlag}=[redacted]` : params.normalizedDisplay;
     return {
         argv: safeArgv,
         normalizedDisplay: safeNormalizedDisplay,
@@ -2193,9 +2166,7 @@ async function handleRunPmCliKnownError(context, numericExitCode) {
         ? projectLeanErrorEnvelope(formatPmCliErrorForJson(errorMessage, exitCode, enrichedContext))
         : formatPmCliErrorForJson(errorMessage, exitCode, enrichedContext);
     const renderedError = context.jsonErrors
-        ? JSON.stringify(context.bootstrapGlobal.tokenAccounting
-            ? attachOutputTokenAccounting(jsonErrorPayload, (value) => `${JSON.stringify(value, null, 2)}\n`)
-            : jsonErrorPayload, null, 2)
+        ? JSON.stringify(context.bootstrapGlobal.tokenAccounting ? attachOutputTokenAccounting(jsonErrorPayload, (value) => `${JSON.stringify(value, null, 2)}\n`) : jsonErrorPayload, null, 2)
         : formatPmCliErrorForDisplay(errorMessage, enrichedContext);
     printError(renderedError);
     const { errorCategory, commandResolution } = await context.emitTelemetryCommandError({
@@ -2270,7 +2241,6 @@ async function handleUnknownHelpCommandError(context, code) {
         error_message: classification.detail,
         command_resolution: commandResolution,
         resolution_stage: "parse",
-        source_context: activeTelemetryCommandContext?.source_context,
     });
     const baseRenderedUsage = context.jsonErrors
         ? await formatCommanderUsageJson({ message: unknownMessage }, program, recoveryCommandDescriptors, context.bootstrapGlobal.lean === true, { failedExtensions })
@@ -2463,7 +2433,13 @@ async function runPmCliInReproducibleContext(rawArgv) {
         if (renderedBootstrapJsonHelp) {
             return;
         }
-        if (isBareInvocation) {
+        const helpRequest = parseBootstrapHelpRequest(invocationArgv);
+        if (helpRequest.requested && !isKnownHelpCommandPath(program, helpRequest.commandPathTokens)) {
+            throw new CommanderError(EXIT_CODE.USAGE, "commander.helpDisplayed", "(outputHelp)");
+        }
+        if (isBareInvocation ||
+            (isFullHelpDiscovery(invocationArgv) &&
+                parseBootstrapCommandName(invocationArgv) === undefined)) {
             program.outputHelp();
             return;
         }
@@ -2472,7 +2448,9 @@ async function runPmCliInReproducibleContext(rawArgv) {
         await runWithDiscoveredContextIntentContracts({
             pmRoot: resolvePmRoot(process.cwd(), bootstrapGlobal.path),
             packages: intentSnapshot?.contextIntentPackages,
-        }, () => runWithWorkspaceHarnessSignalDescriptors(invocationSettings.agent_identity.harness_signals, () => program.parseAsync(invocationProcessArgv), { probesEnabled: invocationSettings.agent_identity?.probes_enabled }));
+        }, () => runWithWorkspaceHarnessSignalDescriptors(invocationSettings.agent_identity.harness_signals, () => program.parseAsync(invocationProcessArgv), {
+            probesEnabled: invocationSettings.agent_identity?.probes_enabled,
+        }));
     }
     catch (error) {
         await handleRunPmCliError({ error, invocationArgv });
@@ -2583,4 +2561,4 @@ export const _testOnly = {
     wrapThrownErrorForSentry,
 };
 //# sourceMappingURL=main.js.map
-//# debugId=ffd55bde-cc30-529f-a6f9-ec43abe4efba
+//# debugId=f947c7f0-adf8-59da-8bc7-9cd746b05839

package/dist/cli/register-annotations.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="79bf0b3f-ad63-5d9f-9911-d5a142214ac1")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="263a15b4-5537-5e11-b0c0-3da453ee0357")}catch(e){}}();
 import { EXIT_CODE, PmCliError, } from "../sdk/runtime-primitives.js";
 import { renderPmCommand } from "../sdk/command-line.js";
 import { runComments } from "./commands/comments.js";
@@ -11,6 +11,7 @@ function assertNoTransposedAnnotationAction(collection, id, text, options) {
         return;
     }
     const suppliedText = readOptionString(options, "add") ??
+        readOptionString(options, "text") ??
         readOptionString(options, "note") ??
         readOptionString(options, "body") ??
         readOptionString(options, "comment");
@@ -25,12 +26,7 @@ function assertNoTransposedAnnotationAction(collection, id, text, options) {
     else
         retryArgs.push("--add", "-");
     const suggestedRetry = renderPmCommand(retryArgs);
-    const stdinRetry = renderPmCommand([
-        collection,
-        text.trim(),
-        "--add",
-        "-",
-    ]);
+    const stdinRetry = renderPmCommand([collection, text.trim(), "--add", "-"]);
     throw new PmCliError(`The positional token "add" was parsed as the item id, while "${text.trim()}" was parsed as annotation text. ${collection} does not use an add subcommand.`, EXIT_CODE.USAGE, {
         code: "annotation_transposed_subcommand",
         reason: "noun_verb_object_transposition",
@@ -47,12 +43,26 @@ function assertNoTransposedAnnotationAction(collection, id, text, options) {
         },
     });
 }
+function resolveAnnotationTextAliases(label, options, aliases) {
+    const supplied = aliases.flatMap((alias) => {
+        const value = readOptionString(options, alias);
+        return value === undefined ? [] : [{ alias, value }];
+    });
+    const distinctValues = [...new Set(supplied.map(({ value }) => value))];
+    if (distinctValues.length > 1) {
+        throw new PmCliError(`Specify ${label} text with one alias or the same value across aliases: ${supplied.map(({ alias }) => `--${alias}`).join(", ")}`, EXIT_CODE.USAGE, { code: "annotation_alias_conflict" });
+    }
+    return supplied[0]?.value;
+}
 function resolveCommentSources(text, options) {
     const editIndex = typeof options.edit === "number" ? options.edit : undefined;
     const deleteIndex = typeof options.delete === "number" ? options.delete : undefined;
-    const addFromOption = readOptionString(options, "add") ??
-        readOptionString(options, "body") ??
-        readOptionString(options, "comment");
+    const addFromOption = resolveAnnotationTextAliases("comment", options, [
+        "add",
+        "text",
+        "body",
+        "comment",
+    ]);
     const addFromPositional = typeof text === "string" ? text : undefined;
     const readFromStdin = options.stdin === true;
     const readFromFile = readOptionString(options, "file");
@@ -84,14 +94,7 @@ function resolveCommentSources(text, options) {
     };
 }
 function resolveSingleTextSource(label, positional, options) {
-    const canonicalAdd = readOptionString(options, "add");
-    const aliasAdd = label === "note" ? readOptionString(options, "note") : undefined;
-    if (canonicalAdd !== undefined &&
-        aliasAdd !== undefined &&
-        canonicalAdd !== aliasAdd) {
-        throw new PmCliError("Specify note text with either --add or --note, not conflicting values for both aliases", EXIT_CODE.USAGE, { code: "annotation_alias_conflict" });
-    }
-    const addFromOption = canonicalAdd ?? aliasAdd;
+    const addFromOption = resolveAnnotationTextAliases(label, options, label === "note" ? ["add", "text", "note"] : ["add", "text"]);
     const addFromPositional = typeof positional === "string" ? positional : undefined;
     if (addFromOption !== undefined && addFromPositional !== undefined) {
         throw new PmCliError(`Specify ${label} text either as positional [text] or with --add, not both`, EXIT_CODE.USAGE);
@@ -205,8 +208,9 @@ export function registerAnnotationCommands(program, parsePositiveInteger) {
         .description("List, add, edit, or delete comments for an item.")
         .action(runCommentsAction);
     addHiddenOption(commentsCommand, "--body <text>", "Alias for --add", false);
+    addHiddenOption(commentsCommand, "--text <text>", "Alias for --add", false);
     addHiddenOption(commentsCommand, "--comment <text>", "Alias for --add", false);
-    program
+    const notesCommand = program
         .command("notes")
         .argument("<id>", "Item id")
         .argument("[text]", "Optional note text shorthand (equivalent to --add; use - for stdin)")
@@ -227,7 +231,8 @@ export function registerAnnotationCommands(program, parsePositiveInteger) {
         .option("--force", "Force ownership override")
         .description("Manage merge-safe text notes and JSON context events.")
         .action(runNotesAction);
-    program
+    addHiddenOption(notesCommand, "--text <text>", "Alias for --add", false);
+    const learningsCommand = program
         .command("learnings")
         .argument("<id>", "Item id")
         .argument("[text]", "Optional learning text shorthand (equivalent to --add; use - for stdin)")
@@ -243,6 +248,7 @@ export function registerAnnotationCommands(program, parsePositiveInteger) {
         .option("--force", "Force ownership override")
         .description("List, add, edit, or delete learnings for an item.")
         .action(runLearningsAction);
+    addHiddenOption(learningsCommand, "--text <text>", "Alias for --add", false);
 }
 //# sourceMappingURL=register-annotations.js.map
-//# debugId=79bf0b3f-ad63-5d9f-9911-d5a142214ac1
+//# debugId=263a15b4-5537-5e11-b0c0-3da453ee0357