@unbrained/pm-cli 2026.9.7 → 2026.9.9

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

@@ -1,571 +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]="e4324332-da8f-5ae1-b0e3-b6d0e9674f98")}catch(e){}}();
-import { hasSubcommandFlagContractsForCommand, PM_COMMAND_ALIAS_CONTRACTS, PM_CORE_COMMAND_NAMES, } from "../sdk/cli-contracts.js";
-import { commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveTypeDefinition, EXIT_CODE, writeStderr, writeStdout, } from "../sdk/runtime-primitives.js";
-import { buildDynamicExtensionHelpOptionSummaries, mergeHelpOptionSummaries, findCommandByPath, findDirectChildCommand, commandAliases, } from "./extension-command-help.js";
-import { getPmCommandHelpVisibilityTier, isFullHelpDiscovery, normalizeHelpCommandPath, 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";
-import { formatCommanderErrorForJson } from "./error-guidance.js";
-import { BUILTIN_TYPE_HELP_VALUES, buildUnknownCommandGuidanceFromRuntime, isKnownHelpCommandPath, } from "./commander-usage.js";
-import { attachOutputTokenAccounting } from "../sdk/output-token-accounting.js";
-import { resolveCreateExplicitEmptyFlag } from "../sdk/agent/create-option-policy.js";
-import { formatPmPositionalActionFlagTip, PM_POSITIONAL_ACTION_CONTRACTS, resolvePmPositionalActionContract, } from "../sdk/cli-contracts/grammar-contracts.js";
-import { resolvePmCommandCapabilityFamily, resolvePmCommandVisibilityTier, } from "../sdk/agent-capability-contracts.js";
-const EXTENSION_TIER_ORDER = {
-    core: 0,
-    standard: 1,
-    full: 2,
-    internal: 3,
-};
-function resolveExtensionCommandSurface(commandPath, descriptors, allowDescendants = true) {
-    const exact = descriptors.get(commandPath);
-    if (exact)
-        return exact;
-    if (!allowDescendants)
-        return undefined;
-    const descendants = [...descriptors.entries()]
-        .filter(([path]) => path.startsWith(`${commandPath} `))
-        .map(([, descriptor]) => descriptor);
-    if (descendants.length === 0)
-        return undefined;
-    const tier = descendants.reduce((selected, descriptor) => EXTENSION_TIER_ORDER[descriptor.tier] < EXTENSION_TIER_ORDER[selected]
-        ? descriptor.tier
-        : selected, "internal");
-    const families = new Set(descendants.map(({ family }) => family));
-    return {
-        tier,
-        family: families.size === 1 ? descendants[0].family : "extensions",
-    };
-}
-function resolveCommandFromPathTokens(root, pathTokens) {
-    if (pathTokens.length === 0) {
-        return root;
-    }
-    const exactCommand = findCommandByPath(root, pathTokens);
-    if (exactCommand) {
-        return exactCommand;
-    }
-    const requestedPath = pathTokens.join(" ");
-    if (!PM_CORE_COMMAND_NAMES.some((commandName) => commandName === requestedPath) &&
-        !hasSubcommandFlagContractsForCommand(requestedPath) &&
-        !resolvePmPositionalActionContract(requestedPath) &&
-        !isKnownHelpCommandPath(root, pathTokens)) {
-        return null;
-    }
-    for (let length = pathTokens.length - 1; length > 0; length -= 1) {
-        const positionalParent = findCommandByPath(root, pathTokens.slice(0, length));
-        if (positionalParent) {
-            return positionalParent;
-        }
-    }
-    return pathTokens.length === 1 ? root : null;
-}
-function extractOptionValueName(flags) {
-    const match = flags.match(/[<[]([^>\]]+)[>\]]/);
-    if (!match) {
-        return null;
-    }
-    const value = match[1]?.trim();
-    return value && value.length > 0 ? value : null;
-}
-function readOptionAttributeName(option) {
-    const optionRecord = option;
-    if (typeof optionRecord.attributeName === "function") {
-        const value = optionRecord.attributeName();
-        return typeof value === "string" && value.trim().length > 0
-            ? value.trim()
-            : null;
-    }
-    if (typeof optionRecord.attributeName === "string" &&
-        optionRecord.attributeName.trim().length > 0) {
-        return optionRecord.attributeName.trim();
-    }
-    return null;
-}
-function buildOptionAliasMap(options) {
-    const aliasMap = new Map();
-    for (const option of options) {
-        const optionRecord = option;
-        const attributeName = readOptionAttributeName(option);
-        if (!attributeName ||
-            typeof optionRecord.long !== "string" ||
-            optionRecord.long.trim().length === 0) {
-            continue;
-        }
-        const existing = aliasMap.get(attributeName) ?? [];
-        existing.push(optionRecord.long.trim());
-        aliasMap.set(attributeName, existing);
-    }
-    for (const [attributeName, values] of aliasMap.entries()) {
-        aliasMap.set(attributeName, [
-            ...new Set(values
-                .map((value) => value.trim())
-                .filter((value) => value.length > 0)),
-        ].sort((left, right) => left.localeCompare(right)));
-    }
-    return aliasMap;
-}
-function renderAttemptedCommand(argv) {
-    return renderPmCommand(argv);
-}
-function buildHelpOptionSummaries(command) {
-    const options = (command.options ?? []);
-    const optionAliasMap = buildOptionAliasMap(options);
-    return options.map((option) => {
-        const optionRecord = option;
-        const flags = typeof optionRecord.flags === "string" ? optionRecord.flags.trim() : "";
-        const description = typeof optionRecord.description === "string"
-            ? optionRecord.description.trim()
-            : "";
-        const attributeName = readOptionAttributeName(option);
-        const aliasCandidates = attributeName
-            ? (optionAliasMap.get(attributeName) ?? [])
-            : [];
-        const aliases = aliasCandidates
-            .filter((entry) => entry !== optionRecord.long)
-            .map((entry) => entry.trim())
-            .filter((entry) => entry.length > 0);
-        const aliasForMatch = description.match(/^Alias for ([^ ]+)/i);
-        const aliasFor = aliasForMatch && aliasForMatch[1] ? aliasForMatch[1].trim() : null;
-        const required = optionRecord.mandatory === true ||
-            description.includes("[required]") ||
-            description.toLowerCase().includes("required;");
-        const valueRequired = flags.includes("<");
-        const takesValue = valueRequired || flags.includes("[");
-        const summary = {
-            flags,
-            long: typeof optionRecord.long === "string" ? optionRecord.long : null,
-            short: typeof optionRecord.short === "string" ? optionRecord.short : null,
-            description,
-            takes_value: takesValue,
-            value_required: valueRequired,
-            value_name: extractOptionValueName(flags),
-            variadic: optionRecord.variadic === true,
-            required,
-            aliases,
-            alias_for: aliasFor,
-        };
-        if (optionRecord.defaultValue !== undefined) {
-            summary.default_value = optionRecord.defaultValue;
-        }
-        return summary;
-    });
-}
-function compactHelpOptionAliases(options) {
-    const canonicalByLong = new Map();
-    const aliasOptions = [];
-    for (const option of options) {
-        if (option.alias_for && option.long) {
-            aliasOptions.push(option);
-            continue;
-        }
-        if (option.long) {
-            canonicalByLong.set(option.long, option);
-        }
-    }
-    for (const aliasOption of aliasOptions) {
-        const aliasFor = aliasOption.alias_for;
-        const canonical = canonicalByLong.get(aliasFor);
-        if (!canonical) {
-            continue;
-        }
-        const aliasLong = aliasOption.long;
-        const aliases = new Set([...(canonical.aliases ?? []), aliasLong]);
-        canonical.aliases = [...aliases].sort((left, right) => left.localeCompare(right));
-    }
-    return options.filter((option) => {
-        if (!option.alias_for || !option.long) {
-            return true;
-        }
-        return !canonicalByLong.has(option.alias_for);
-    });
-}
-function buildHelpArgumentSummaries(command) {
-    const commandRecord = command;
-    const argumentsList = Array.isArray(commandRecord.registeredArguments)
-        ? commandRecord.registeredArguments
-        : Array.isArray(commandRecord._args)
-            ? commandRecord._args
-            : [];
-    return argumentsList.map((argument) => {
-        const rawName = typeof argument.name === "function"
-            ? argument.name()
-            : typeof argument.name === "string"
-                ? argument.name
-                : "argument";
-        const description = typeof argument.description === "string" &&
-            argument.description.trim().length > 0
-            ? argument.description.trim()
-            : null;
-        return {
-            name: rawName.trim(),
-            required: argument.required === true ||
-                description?.toLowerCase().startsWith("required;") === true,
-            variadic: argument.variadic === true,
-            description,
-        };
-    });
-}
-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 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));
-}
-function buildJsonHelpNarrative(detailMode, fallbackNarrative, extensionDescriptor) {
-    if (!extensionDescriptor) {
-        return fallbackNarrative;
-    }
-    const extensionExamples = extensionDescriptor.examples ?? [];
-    const extensionFailureHints = extensionDescriptor.failure_hints ?? [];
-    return {
-        intent: extensionDescriptor.intent ??
-            extensionDescriptor.description ??
-            fallbackNarrative.intent,
-        examples: detailMode === "detailed"
-            ? extensionExamples.length > 0
-                ? [...extensionExamples]
-                : [...fallbackNarrative.examples]
-            : extensionExamples.length > 0
-                ? [extensionExamples[0]]
-                : [...fallbackNarrative.examples],
-        tips: detailMode === "detailed"
-            ? extensionFailureHints.length > 0
-                ? [...extensionFailureHints]
-                : [...fallbackNarrative.tips]
-            : [],
-        detail_mode: detailMode,
-    };
-}
-function resolveJsonHelpVisibilityTier(rootCommandPath, extensionDescriptor) {
-    if (rootCommandPath === undefined)
-        return null;
-    return (extensionDescriptor?.tier ?? resolvePmCommandVisibilityTier(rootCommandPath));
-}
-function resolveJsonHelpCapabilityFamily(rootCommandPath, extensionDescriptor) {
-    if (rootCommandPath === undefined)
-        return null;
-    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(), includeAll = false) {
-    if (!action) {
-        const argumentsList = buildHelpArgumentSummaries(targetCommand);
-        const registeredSubcommands = buildHelpSubcommandSummaries(targetCommand, extensionDescriptors, includeAll);
-        const registeredSubcommandNames = new Set(registeredSubcommands.map(({ name }) => name));
-        return {
-            arguments: argumentsList,
-            options: allOptions,
-            subcommands: [
-                ...registeredSubcommands,
-                ...PM_POSITIONAL_ACTION_CONTRACTS.filter(({ parent, action: name }) => parent === resolvedPath && !registeredSubcommandNames.has(name)).map(({ action: name, description }) => ({
-                    name,
-                    aliases: [],
-                    description,
-                    tier: resolvePmCommandVisibilityTier(resolvedPath.split(" ")[0]),
-                    family: resolvePmCommandCapabilityFamily(resolvedPath.split(" ")[0]),
-                })),
-            ].sort((left, right) => left.name.localeCompare(right.name)),
-            usage: [
-                resolvedPath,
-                argumentsList.reduce((usage, argument) => argument.required
-                    ? usage.replace(`[${argument.name}${argument.variadic ? "..." : ""}]`, `<${argument.name}${argument.variadic ? "..." : ""}>`)
-                    : usage, targetCommand.usage()),
-            ]
-                .filter((token) => token.length > 0)
-                .join(" "),
-        };
-    }
-    const acceptedFlags = new Set(action.accepted_flags);
-    return {
-        arguments: action.slots.map(({ name, required, variadic, value_kind: valueKind, polymorphic }) => ({
-            name,
-            required,
-            variadic,
-            description: polymorphic
-                ? `Polymorphic ${valueKind} value; inspect the action contract before mutation.`
-                : `${valueKind.replaceAll("_", " ")} value.`,
-        })),
-        options: allOptions.filter(({ long, aliases }) => (long !== null && acceptedFlags.has(long)) ||
-            aliases.some((alias) => acceptedFlags.has(alias))),
-        subcommands: [],
-        usage: [
-            action.command,
-            ...action.slots.map(({ name, required, variadic }) => {
-                const token = variadic ? `${name}...` : name;
-                return required ? `<${token}>` : `[${token}]`;
-            }),
-        ].join(" "),
-    };
-}
-function buildJsonHelpPayload(rootProgram, targetCommand, argv, requestedPath, extensionDescriptors) {
-    const detailMode = resolveHelpDetailMode(argv);
-    const fullDiscovery = isFullHelpDiscovery(argv);
-    const commanderPath = normalizeHelpCommandPath(getCommandPath(targetCommand));
-    const requestedCommandPath = normalizeHelpCommandPath(requestedPath.join(" "));
-    const resolvedPath = requestedCommandPath.length > commanderPath.length
-        ? requestedCommandPath
-        : commanderPath;
-    const positionalAction = resolvePmPositionalActionContract(resolvedPath);
-    const projectedPath = positionalAction?.command ?? commanderPath;
-    const commandPath = projectedPath.length > 0 ? projectedPath : undefined;
-    const rootCommandPath = commandPath?.split(" ")[0];
-    const fallbackNarrative = resolveHelpNarrative(commandPath, detailMode);
-    const extensionDescriptor = commandPath
-        ? extensionDescriptors.get(commandPath)
-        : undefined;
-    const extensionSurface = commandPath
-        ? resolveExtensionCommandSurface(commandPath, extensionDescriptors, getPmCommandHelpVisibilityTier(targetCommand) !== undefined)
-        : undefined;
-    const narrative = buildJsonHelpNarrative(detailMode, fallbackNarrative, extensionDescriptor);
-    const allOptionSummaries = compactHelpOptionAliases(mergeHelpOptionSummaries(buildHelpOptionSummaries(targetCommand), buildDynamicExtensionHelpOptionSummaries(extensionDescriptor)));
-    const projection = buildPositionalActionHelpProjection(positionalAction, targetCommand, projectedPath, allOptionSummaries, extensionDescriptors, fullDiscovery);
-    const fullCommandAliases = projectFullCommandAliases(rootProgram, targetCommand, fullDiscovery);
-    return {
-        format: "pm_help_v1",
-        detail_mode: detailMode,
-        root_command: rootProgram.name(),
-        requested_path: requestedPath,
-        resolved_path: projectedPath.length > 0 ? projectedPath : rootProgram.name(),
-        visibility_tier: resolveJsonHelpVisibilityTier(rootCommandPath, extensionSurface),
-        capability_family: resolveJsonHelpCapabilityFamily(rootCommandPath, extensionSurface),
-        description: positionalAction?.description ?? targetCommand.description(),
-        usage: projection.usage,
-        intent: positionalAction?.description ?? narrative.intent,
-        examples: positionalAction
-            ? [positionalAction.example]
-            : narrative.examples,
-        tips: positionalAction
-            ? [formatPmPositionalActionFlagTip(positionalAction.accepted_flags)]
-            : narrative.tips,
-        arguments: projection.arguments,
-        options: projection.options,
-        subcommands: projection.subcommands,
-        has_subcommands: projection.subcommands.length > 0,
-        ...(fullCommandAliases === undefined
-            ? {}
-            : { command_aliases: fullCommandAliases }),
-    };
-}
-/** Implements maybe render bootstrap json help for the public runtime surface of this module. */
-export async function maybeRenderBootstrapJsonHelp(rootProgram, argv, extensionDescriptors) {
-    const bootstrapGlobal = parseBootstrapGlobalOptions(argv);
-    if (!bootstrapGlobal.json) {
-        return false;
-    }
-    const helpRequest = parseBootstrapHelpRequest(argv);
-    if (!helpRequest.requested) {
-        return false;
-    }
-    const targetCommand = resolveCommandFromPathTokens(rootProgram, helpRequest.commandPathTokens);
-    if (!targetCommand) {
-        if (!bootstrapGlobal.quiet) {
-            const unknownMessage = `unknown command '${helpRequest.commandPathTokens.join(" ")}'`;
-            const runtimeContext = buildUnknownCommandGuidanceFromRuntime(unknownMessage, rootProgram, extensionDescriptors);
-            const envelope = formatCommanderErrorForJson(unknownMessage, "help", BUILTIN_TYPE_HELP_VALUES, EXIT_CODE.USAGE, {
-                ...runtimeContext,
-                attemptedCommand: renderAttemptedCommand(argv),
-                normalizedInvocationArgs: [...argv],
-                providedOptionFlags: extractProvidedOptionFlags(argv),
-            });
-            const output = bootstrapGlobal.tokenAccounting
-                ? attachOutputTokenAccounting(envelope, (value) => `${JSON.stringify(value, null, 2)}\n`)
-                : envelope;
-            writeStderr(`${JSON.stringify(output, null, 2)}\n`);
-        }
-        process.exitCode = EXIT_CODE.USAGE;
-        return true;
-    }
-    if (!bootstrapGlobal.quiet) {
-        const payload = buildJsonHelpPayload(rootProgram, targetCommand, argv, helpRequest.commandPathTokens, extensionDescriptors);
-        writeStdout(`${JSON.stringify(payload, null, 2)}\n`);
-    }
-    process.exitCode = EXIT_CODE.SUCCESS;
-    return true;
-}
-function buildCreateUpdatePolicyIntro(commandName, typeRegistry) {
-    const lines = [
-        "",
-        "Type-aware option policies:",
-        "  pass --type <value> with --help to render required/disabled/hidden option policy details for that type.",
-        `  active type values: ${typeRegistry.types.join("|")}`,
-    ];
-    if (commandName === "create") {
-        lines.push("  scheduling shortcut: use --schedule-preset lightweight for Reminder/Meeting/Event minimal create flows.");
-    }
-    return lines.join("\n");
-}
-function appendTypeOptionHelpLines(lines, typeDefinition) {
-    if (typeDefinition.options.length === 0) {
-        lines.push("  type options: none");
-        return;
-    }
-    lines.push("  type options:");
-    for (const option of typeDefinition.options) {
-        const requiredLabel = option.required ? " (required)" : "";
-        const aliases = option.aliases ?? [];
-        lines.push(`    - ${option.key}${requiredLabel}`);
-        lines.push(`      values: ${option.values.length > 0 ? option.values.join("|") : "any non-empty string"}`);
-        lines.push(`      aliases: ${aliases.length > 0 ? aliases.join("|") : "none"}`);
-        if (option.description && option.description.trim().length > 0) {
-            lines.push(`      description: ${option.description.trim()}`);
-        }
-    }
-}
-function buildCreatePolicyRequiredSets(commandName, typeDefinition) {
-    const progressive = commandName === "create"
-        ? new Set(["title", "type"])
-        : new Set();
-    const strict = new Set(progressive);
-    if (commandName === "create") {
-        for (const option of [
-            ...typeDefinition.required_create_fields,
-            ...typeDefinition.required_create_repeatables,
-        ]) {
-            strict.add(option);
-        }
-    }
-    return { progressive, strict };
-}
-function appendStrictCreatePolicyHelpLines(lines, typeDefinition, progressiveRequired, strictRequired) {
-    const progressive = new Set(progressiveRequired);
-    const strictOnly = strictRequired.filter((option) => !progressive.has(option));
-    const toFlags = (options) => options.length > 0
-        ? options
-            .map((option) => commandOptionFlagLabel("create", option))
-            .join(", ")
-        : "none";
-    lines.push(`  required in strict mode: ${toFlags(strictOnly)}`);
-    const explicitEmptyFlags = strictOnly
-        .map(resolveCreateExplicitEmptyFlag)
-        .filter((flag) => flag !== undefined);
-    lines.push(`  explicit empty assertion: ${explicitEmptyFlags.length > 0 ? explicitEmptyFlags.join(", ") : "none"}`);
-    if (["Reminder", "Meeting", "Event"].includes(typeDefinition.name)) {
-        lines.push("  schedule preset: --schedule-preset lightweight switches schedule artifacts to progressive required-option policy.");
-        lines.push("  strict parity remains available via --create-mode strict.");
-    }
-}
-function buildCreateUpdatePolicyHelpText(commandName, typeRegistry, argv) {
-    const selectedTypeRaw = parseBootstrapTypeValue(argv);
-    if (!selectedTypeRaw) {
-        return buildCreateUpdatePolicyIntro(commandName, typeRegistry);
-    }
-    const typeDefinition = resolveTypeDefinition(selectedTypeRaw, typeRegistry);
-    if (!typeDefinition) {
-        const allowed = typeRegistry.types.join("|");
-        return [
-            "",
-            `Type-aware option policies: type "${selectedTypeRaw}" is not in the active registry.`,
-            `  active type values: ${allowed}`,
-        ].join("\n");
-    }
-    const argumentTerminatorIndex = argv.indexOf("--");
-    const optionArgv = argumentTerminatorIndex < 0 ? argv : argv.slice(0, argumentTerminatorIndex);
-    const createModeTokenIndex = optionArgv.findIndex((token) => token === "--create-mode" || token.startsWith("--create-mode="));
-    const createModeToken = createModeTokenIndex < 0
-        ? undefined
-        : optionArgv[createModeTokenIndex]?.startsWith("--create-mode=")
-            ? optionArgv[createModeTokenIndex]?.slice("--create-mode=".length)
-            : optionArgv[createModeTokenIndex + 1];
-    const strictCreateMode = commandName === "create" && createModeToken?.toLowerCase() === "strict";
-    const requiredSets = buildCreatePolicyRequiredSets(commandName, typeDefinition);
-    const progressivePolicyState = resolveCommandOptionPolicyState(typeDefinition, commandName, requiredSets.progressive);
-    const policyState = resolveCommandOptionPolicyState(typeDefinition, commandName, strictCreateMode ? requiredSets.strict : requiredSets.progressive);
-    const toFlags = (options) => options.length > 0
-        ? options
-            .map((option) => commandOptionFlagLabel(commandName, option))
-            .join(", ")
-        : "none";
-    const lines = [
-        "",
-        `Type-aware option policies for ${typeDefinition.name}:`,
-        `  required: ${toFlags(policyState.required)}`,
-        `  disabled: ${toFlags(policyState.disabled)}`,
-        `  hidden: ${toFlags(policyState.hidden)}`,
-    ];
-    if (commandName === "create") {
-        const strictPolicyState = resolveCommandOptionPolicyState(typeDefinition, commandName, requiredSets.strict);
-        appendStrictCreatePolicyHelpLines(lines, typeDefinition, progressivePolicyState.required, strictPolicyState.required);
-    }
-    appendTypeOptionHelpLines(lines, typeDefinition);
-    if (policyState.errors.length > 0) {
-        lines.push(`  config errors: ${policyState.errors.join("; ")}`);
-    }
-    return lines.join("\n");
-}
-/** Implements attach create update policy help text for the public runtime surface of this module. */
-export function attachCreateUpdatePolicyHelpText(rootProgram, typeRegistry, argv) {
-    const bootstrapCommand = parseBootstrapCommandName(argv);
-    if (bootstrapCommand !== "create" && bootstrapCommand !== "update") {
-        return;
-    }
-    const command = findDirectChildCommand(rootProgram, bootstrapCommand);
-    if (!command) {
-        return;
-    }
-    command.addHelpText("after", buildCreateUpdatePolicyHelpText(bootstrapCommand, typeRegistry, argv));
-}
-/** Public contract for test only, shared by SDK and presentation-layer consumers. */
-export const _testOnly = {
-    attachCreateUpdatePolicyHelpText,
-    buildCreateUpdatePolicyHelpText,
-    buildJsonHelpPayload,
-    buildPositionalActionHelpProjection,
-    buildHelpArgumentSummaries,
-    buildHelpOptionSummaries,
-    buildHelpSubcommandSummaries,
-    buildOptionAliasMap,
-    compactHelpOptionAliases,
-    readOptionAttributeName,
-    resolveCommandFromPathTokens,
-    resolveExtensionCommandSurface,
-};
+!(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]="481ed602-8144-59ae-9ac6-223f7a57ecef")}catch(e2){}})();import{hasSubcommandFlagContractsForCommand,PM_COMMAND_ALIAS_CONTRACTS,PM_CORE_COMMAND_NAMES}from"../sdk/cli-contracts.js";import{commandOptionFlagLabel,resolveCommandOptionPolicyState,resolveTypeDefinition,EXIT_CODE,writeStderr,writeStdout}from"../sdk/runtime-primitives.js";import{buildDynamicExtensionHelpOptionSummaries,mergeHelpOptionSummaries,findCommandByPath,findDirectChildCommand,commandAliases}from"./extension-command-help.js";import{getPmCommandHelpVisibilityTier,isFullHelpDiscovery,normalizeHelpCommandPath,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";import{formatCommanderErrorForJson}from"./error-guidance.js";import{BUILTIN_TYPE_HELP_VALUES,buildUnknownCommandGuidanceFromRuntime,isKnownHelpCommandPath}from"./commander-usage.js";import{attachOutputTokenAccounting}from"../sdk/output-token-accounting.js";import{resolveCreateExplicitEmptyFlag}from"../sdk/agent/create-option-policy.js";import{formatPmPositionalActionFlagTip,PM_POSITIONAL_ACTION_CONTRACTS,resolvePmPositionalActionContract}from"../sdk/cli-contracts/grammar-contracts.js";import{resolvePmCommandCapabilityFamily,resolvePmCommandVisibilityTier}from"../sdk/agent-capability-contracts.js";const EXTENSION_TIER_ORDER={core:0,standard:1,full:2,internal:3};function resolveExtensionCommandSurface(commandPath,descriptors,allowDescendants=true){const exact=descriptors.get(commandPath);if(exact)return exact;if(!allowDescendants)return void 0;const descendants=[...descriptors.entries()].filter(([path])=>path.startsWith(`${commandPath} `)).map(([,descriptor])=>descriptor);if(descendants.length===0)return void 0;const tier=descendants.reduce((selected,descriptor)=>EXTENSION_TIER_ORDER[descriptor.tier]<EXTENSION_TIER_ORDER[selected]?descriptor.tier:selected,"internal");const families=new Set(descendants.map(({family})=>family));return{tier,family:families.size===1?descendants[0].family:"extensions"}}function resolveCommandFromPathTokens(root,pathTokens){if(pathTokens.length===0){return root}const exactCommand=findCommandByPath(root,pathTokens);if(exactCommand){return exactCommand}const requestedPath=pathTokens.join(" ");if(!PM_CORE_COMMAND_NAMES.some(commandName=>commandName===requestedPath)&&!hasSubcommandFlagContractsForCommand(requestedPath)&&!resolvePmPositionalActionContract(requestedPath)&&!isKnownHelpCommandPath(root,pathTokens)){return null}for(let length=pathTokens.length-1;length>0;length-=1){const positionalParent=findCommandByPath(root,pathTokens.slice(0,length));if(positionalParent){return positionalParent}}return pathTokens.length===1?root:null}function extractOptionValueName(flags){const match=flags.match(/[<[]([^>\]]+)[>\]]/);if(!match){return null}const value=match[1]?.trim();return value&&value.length>0?value:null}function readOptionAttributeName(option){const optionRecord=option;if(typeof optionRecord.attributeName==="function"){const value=optionRecord.attributeName();return typeof value==="string"&&value.trim().length>0?value.trim():null}if(typeof optionRecord.attributeName==="string"&&optionRecord.attributeName.trim().length>0){return optionRecord.attributeName.trim()}return null}function buildOptionAliasMap(options){const aliasMap=new Map;for(const option of options){const optionRecord=option;const attributeName=readOptionAttributeName(option);if(!attributeName||typeof optionRecord.long!=="string"||optionRecord.long.trim().length===0){continue}const existing=aliasMap.get(attributeName)??[];existing.push(optionRecord.long.trim());aliasMap.set(attributeName,existing)}for(const[attributeName,values]of aliasMap.entries()){aliasMap.set(attributeName,[...new Set(values.map(value=>value.trim()).filter(value=>value.length>0))].sort((left,right)=>left.localeCompare(right)))}return aliasMap}function renderAttemptedCommand(argv){return renderPmCommand(argv)}function buildHelpOptionSummaries(command){const options=command.options??[];const optionAliasMap=buildOptionAliasMap(options);return options.map(option=>{const optionRecord=option;const flags=typeof optionRecord.flags==="string"?optionRecord.flags.trim():"";const description=typeof optionRecord.description==="string"?optionRecord.description.trim():"";const attributeName=readOptionAttributeName(option);const aliasCandidates=attributeName?optionAliasMap.get(attributeName)??[]:[];const aliases=aliasCandidates.filter(entry=>entry!==optionRecord.long).map(entry=>entry.trim()).filter(entry=>entry.length>0);const aliasForMatch=description.match(/^Alias for ([^ ]+)/i);const aliasFor=aliasForMatch&&aliasForMatch[1]?aliasForMatch[1].trim():null;const required=optionRecord.mandatory===true||description.includes("[required]")||description.toLowerCase().includes("required;");const valueRequired=flags.includes("<");const takesValue=valueRequired||flags.includes("[");const summary={flags,long:typeof optionRecord.long==="string"?optionRecord.long:null,short:typeof optionRecord.short==="string"?optionRecord.short:null,description,takes_value:takesValue,value_required:valueRequired,value_name:extractOptionValueName(flags),variadic:optionRecord.variadic===true,required,aliases,alias_for:aliasFor};if(optionRecord.defaultValue!==void 0){summary.default_value=optionRecord.defaultValue}return summary})}function compactHelpOptionAliases(options){const canonicalByLong=new Map;const aliasOptions=[];for(const option of options){if(option.alias_for&&option.long){aliasOptions.push(option);continue}if(option.long){canonicalByLong.set(option.long,option)}}for(const aliasOption of aliasOptions){const aliasFor=aliasOption.alias_for;const canonical=canonicalByLong.get(aliasFor);if(!canonical){continue}const aliasLong=aliasOption.long;const aliases=new Set([...canonical.aliases??[],aliasLong]);canonical.aliases=[...aliases].sort((left,right)=>left.localeCompare(right))}return options.filter(option=>{if(!option.alias_for||!option.long){return true}return!canonicalByLong.has(option.alias_for)})}function buildHelpArgumentSummaries(command){const commandRecord=command;const argumentsList=Array.isArray(commandRecord.registeredArguments)?commandRecord.registeredArguments:Array.isArray(commandRecord._args)?commandRecord._args:[];return argumentsList.map(argument=>{const rawName=typeof argument.name==="function"?argument.name():typeof argument.name==="string"?argument.name:"argument";const description=typeof argument.description==="string"&&argument.description.trim().length>0?argument.description.trim():null;return{name:rawName.trim(),required:argument.required===true||description?.toLowerCase().startsWith("required;")===true,variadic:argument.variadic===true,description}})}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 declaredTier=getPmCommandHelpVisibilityTier(entry);const extensionDescriptor=resolveExtensionCommandSurface(commandPath,extensionDescriptors,declaredTier!==void 0);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))}function buildJsonHelpNarrative(detailMode,fallbackNarrative,extensionDescriptor){if(!extensionDescriptor){return fallbackNarrative}const extensionExamples=extensionDescriptor.examples??[];const extensionFailureHints=extensionDescriptor.failure_hints??[];return{intent:extensionDescriptor.intent??extensionDescriptor.description??fallbackNarrative.intent,examples:detailMode==="detailed"?extensionExamples.length>0?[...extensionExamples]:[...fallbackNarrative.examples]:extensionExamples.length>0?[extensionExamples[0]]:[...fallbackNarrative.examples],tips:detailMode==="detailed"?extensionFailureHints.length>0?[...extensionFailureHints]:[...fallbackNarrative.tips]:[],detail_mode:detailMode}}function resolveJsonHelpVisibilityTier(rootCommandPath,extensionDescriptor){if(rootCommandPath===void 0)return null;return extensionDescriptor?.tier??resolvePmCommandVisibilityTier(rootCommandPath)}function resolveJsonHelpCapabilityFamily(rootCommandPath,extensionDescriptor){if(rootCommandPath===void 0)return null;return extensionDescriptor?.family??resolvePmCommandCapabilityFamily(rootCommandPath)}function projectFullCommandAliases(rootProgram,targetCommand,fullDiscovery){if(targetCommand!==rootProgram||!fullDiscovery)return void 0;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"}))}function buildPositionalActionHelpProjection(action,targetCommand,resolvedPath,allOptions,extensionDescriptors=new Map,includeAll=false){if(!action){const argumentsList=buildHelpArgumentSummaries(targetCommand);const registeredSubcommands=buildHelpSubcommandSummaries(targetCommand,extensionDescriptors,includeAll);const registeredSubcommandNames=new Set(registeredSubcommands.map(({name})=>name));return{arguments:argumentsList,options:allOptions,subcommands:[...registeredSubcommands,...PM_POSITIONAL_ACTION_CONTRACTS.filter(({parent,action:name})=>parent===resolvedPath&&!registeredSubcommandNames.has(name)).map(({action:name,description})=>({name,aliases:[],description,tier:resolvePmCommandVisibilityTier(resolvedPath.split(" ")[0]),family:resolvePmCommandCapabilityFamily(resolvedPath.split(" ")[0])}))].sort((left,right)=>left.name.localeCompare(right.name)),usage:[resolvedPath,argumentsList.reduce((usage,argument)=>argument.required?usage.replace(`[${argument.name}${argument.variadic?"...":""}]`,`<${argument.name}${argument.variadic?"...":""}>`):usage,targetCommand.usage())].filter(token=>token.length>0).join(" ")}}const acceptedFlags=new Set(action.accepted_flags);return{arguments:action.slots.map(({name,required,variadic,value_kind:valueKind,polymorphic})=>({name,required,variadic,description:polymorphic?`Polymorphic ${valueKind} value; inspect the action contract before mutation.`:`${valueKind.replaceAll("_"," ")} value.`})),options:allOptions.filter(({long,aliases})=>long!==null&&acceptedFlags.has(long)||aliases.some(alias=>acceptedFlags.has(alias))),subcommands:[],usage:[action.command,...action.slots.map(({name,required,variadic})=>{const token=variadic?`${name}...`:name;return required?`<${token}>`:`[${token}]`})].join(" ")}}function buildJsonHelpPayload(rootProgram,targetCommand,argv,requestedPath,extensionDescriptors){const detailMode=resolveHelpDetailMode(argv);const fullDiscovery=isFullHelpDiscovery(argv);const commanderPath=normalizeHelpCommandPath(getCommandPath(targetCommand));const requestedCommandPath=normalizeHelpCommandPath(requestedPath.join(" "));const resolvedPath=requestedCommandPath.length>commanderPath.length?requestedCommandPath:commanderPath;const positionalAction=resolvePmPositionalActionContract(resolvedPath);const projectedPath=positionalAction?.command??commanderPath;const commandPath=projectedPath.length>0?projectedPath:void 0;const rootCommandPath=commandPath?.split(" ")[0];const fallbackNarrative=resolveHelpNarrative(commandPath,detailMode);const extensionDescriptor=commandPath?extensionDescriptors.get(commandPath):void 0;const extensionSurface=commandPath?resolveExtensionCommandSurface(commandPath,extensionDescriptors,getPmCommandHelpVisibilityTier(targetCommand)!==void 0):void 0;const narrative=buildJsonHelpNarrative(detailMode,fallbackNarrative,extensionDescriptor);const allOptionSummaries=compactHelpOptionAliases(mergeHelpOptionSummaries(buildHelpOptionSummaries(targetCommand),buildDynamicExtensionHelpOptionSummaries(extensionDescriptor)));const projection=buildPositionalActionHelpProjection(positionalAction,targetCommand,projectedPath,allOptionSummaries,extensionDescriptors,fullDiscovery);const fullCommandAliases=projectFullCommandAliases(rootProgram,targetCommand,fullDiscovery);return{format:"pm_help_v1",detail_mode:detailMode,root_command:rootProgram.name(),requested_path:requestedPath,resolved_path:projectedPath.length>0?projectedPath:rootProgram.name(),visibility_tier:resolveJsonHelpVisibilityTier(rootCommandPath,extensionSurface),capability_family:resolveJsonHelpCapabilityFamily(rootCommandPath,extensionSurface),description:positionalAction?.description??targetCommand.description(),usage:projection.usage,intent:positionalAction?.description??narrative.intent,examples:positionalAction?[positionalAction.example]:narrative.examples,tips:positionalAction?[formatPmPositionalActionFlagTip(positionalAction.accepted_flags)]:narrative.tips,arguments:projection.arguments,options:projection.options,subcommands:projection.subcommands,has_subcommands:projection.subcommands.length>0,...fullCommandAliases===void 0?{}:{command_aliases:fullCommandAliases}}}async function maybeRenderBootstrapJsonHelp(rootProgram,argv,extensionDescriptors){const bootstrapGlobal=parseBootstrapGlobalOptions(argv);if(!bootstrapGlobal.json){return false}const helpRequest=parseBootstrapHelpRequest(argv);if(!helpRequest.requested){return false}const targetCommand=resolveCommandFromPathTokens(rootProgram,helpRequest.commandPathTokens);if(!targetCommand){if(!bootstrapGlobal.quiet){const unknownMessage=`unknown command '${helpRequest.commandPathTokens.join(" ")}'`;const runtimeContext=buildUnknownCommandGuidanceFromRuntime(unknownMessage,rootProgram,extensionDescriptors);const envelope=formatCommanderErrorForJson(unknownMessage,"help",BUILTIN_TYPE_HELP_VALUES,EXIT_CODE.USAGE,{...runtimeContext,attemptedCommand:renderAttemptedCommand(argv),normalizedInvocationArgs:[...argv],providedOptionFlags:extractProvidedOptionFlags(argv)});const output=bootstrapGlobal.tokenAccounting?attachOutputTokenAccounting(envelope,value=>`${JSON.stringify(value,null,2)}
+`):envelope;writeStderr(`${JSON.stringify(output,null,2)}
+`)}process.exitCode=EXIT_CODE.USAGE;return true}if(!bootstrapGlobal.quiet){const payload=buildJsonHelpPayload(rootProgram,targetCommand,argv,helpRequest.commandPathTokens,extensionDescriptors);writeStdout(`${JSON.stringify(payload,null,2)}
+`)}process.exitCode=EXIT_CODE.SUCCESS;return true}function buildCreateUpdatePolicyIntro(commandName,typeRegistry){const lines=["","Type-aware option policies:","  pass --type <value> with --help to render required/disabled/hidden option policy details for that type.",`  active type values: ${typeRegistry.types.join("|")}`];if(commandName==="create"){lines.push("  scheduling shortcut: use --schedule-preset lightweight for Reminder/Meeting/Event minimal create flows.")}return lines.join("\n")}function appendTypeOptionHelpLines(lines,typeDefinition){if(typeDefinition.options.length===0){lines.push("  type options: none");return}lines.push("  type options:");for(const option of typeDefinition.options){const requiredLabel=option.required?" (required)":"";const aliases=option.aliases??[];lines.push(`    - ${option.key}${requiredLabel}`);lines.push(`      values: ${option.values.length>0?option.values.join("|"):"any non-empty string"}`);lines.push(`      aliases: ${aliases.length>0?aliases.join("|"):"none"}`);if(option.description&&option.description.trim().length>0){lines.push(`      description: ${option.description.trim()}`)}}}function buildCreatePolicyRequiredSets(commandName,typeDefinition){const progressive=commandName==="create"?new Set(["title","type"]):new Set;const strict=new Set(progressive);if(commandName==="create"){for(const option of[...typeDefinition.required_create_fields,...typeDefinition.required_create_repeatables]){strict.add(option)}}return{progressive,strict}}function appendStrictCreatePolicyHelpLines(lines,typeDefinition,progressiveRequired,strictRequired){const progressive=new Set(progressiveRequired);const strictOnly=strictRequired.filter(option=>!progressive.has(option));const toFlags=options=>options.length>0?options.map(option=>commandOptionFlagLabel("create",option)).join(", "):"none";lines.push(`  required in strict mode: ${toFlags(strictOnly)}`);const explicitEmptyFlags=strictOnly.map(resolveCreateExplicitEmptyFlag).filter(flag=>flag!==void 0);lines.push(`  explicit empty assertion: ${explicitEmptyFlags.length>0?explicitEmptyFlags.join(", "):"none"}`);if(["Reminder","Meeting","Event"].includes(typeDefinition.name)){lines.push("  schedule preset: --schedule-preset lightweight switches schedule artifacts to progressive required-option policy.");lines.push("  strict parity remains available via --create-mode strict.")}}function buildCreateUpdatePolicyHelpText(commandName,typeRegistry,argv){const selectedTypeRaw=parseBootstrapTypeValue(argv);if(!selectedTypeRaw){return buildCreateUpdatePolicyIntro(commandName,typeRegistry)}const typeDefinition=resolveTypeDefinition(selectedTypeRaw,typeRegistry);if(!typeDefinition){const allowed=typeRegistry.types.join("|");return["",`Type-aware option policies: type "${selectedTypeRaw}" is not in the active registry.`,`  active type values: ${allowed}`].join("\n")}const argumentTerminatorIndex=argv.indexOf("--");const optionArgv=argumentTerminatorIndex<0?argv:argv.slice(0,argumentTerminatorIndex);const createModeTokenIndex=optionArgv.findIndex(token=>token==="--create-mode"||token.startsWith("--create-mode="));const createModeToken=createModeTokenIndex<0?void 0:optionArgv[createModeTokenIndex]?.startsWith("--create-mode=")?optionArgv[createModeTokenIndex]?.slice("--create-mode=".length):optionArgv[createModeTokenIndex+1];const strictCreateMode=commandName==="create"&&createModeToken?.toLowerCase()==="strict";const requiredSets=buildCreatePolicyRequiredSets(commandName,typeDefinition);const progressivePolicyState=resolveCommandOptionPolicyState(typeDefinition,commandName,requiredSets.progressive);const policyState=resolveCommandOptionPolicyState(typeDefinition,commandName,strictCreateMode?requiredSets.strict:requiredSets.progressive);const toFlags=options=>options.length>0?options.map(option=>commandOptionFlagLabel(commandName,option)).join(", "):"none";const lines=["",`Type-aware option policies for ${typeDefinition.name}:`,`  required: ${toFlags(policyState.required)}`,`  disabled: ${toFlags(policyState.disabled)}`,`  hidden: ${toFlags(policyState.hidden)}`];if(commandName==="create"){const strictPolicyState=resolveCommandOptionPolicyState(typeDefinition,commandName,requiredSets.strict);appendStrictCreatePolicyHelpLines(lines,typeDefinition,progressivePolicyState.required,strictPolicyState.required)}appendTypeOptionHelpLines(lines,typeDefinition);if(policyState.errors.length>0){lines.push(`  config errors: ${policyState.errors.join("; ")}`)}return lines.join("\n")}function attachCreateUpdatePolicyHelpText(rootProgram,typeRegistry,argv){const bootstrapCommand=parseBootstrapCommandName(argv);if(bootstrapCommand!=="create"&&bootstrapCommand!=="update"){return}const command=findDirectChildCommand(rootProgram,bootstrapCommand);if(!command){return}command.addHelpText("after",buildCreateUpdatePolicyHelpText(bootstrapCommand,typeRegistry,argv))}const _testOnly={attachCreateUpdatePolicyHelpText,buildCreateUpdatePolicyHelpText,buildJsonHelpPayload,buildPositionalActionHelpProjection,buildHelpArgumentSummaries,buildHelpOptionSummaries,buildHelpSubcommandSummaries,buildOptionAliasMap,compactHelpOptionAliases,readOptionAttributeName,resolveCommandFromPathTokens,resolveExtensionCommandSurface};export{_testOnly,attachCreateUpdatePolicyHelpText,maybeRenderBootstrapJsonHelp};
 //# sourceMappingURL=help-json-payload.js.map
-//# debugId=e4324332-da8f-5ae1-b0e3-b6d0e9674f98

package/dist/cli/main.d.ts

@@ -52,6 +52,7 @@ interface RuntimeExtensionActivationProbe {
     allowCommandPrefixMatch?: boolean;
 }
 declare function inferMissingFieldsFromErrorMessage(message: string): string[] | undefined;
+/** Build replayable recovery guidance after removing sensitive matcher values from every invocation representation. */
 declare function buildPmCliRecoveryContext(context: PmCliErrorContext | undefined, invocationArgv: string[], rawMessage: string): PmCliErrorContext;
 declare function readRecordString(record: Record<string, unknown> | null, ...keys: string[]): string | undefined;
 declare function readRecordBoolean(record: Record<string, unknown> | null, ...keys: string[]): boolean | undefined;
@@ -116,6 +117,7 @@ declare function buildRuntimeExtensionSnapshotCacheKey(pmRoot: string, activatio
 declare function bootstrapProfileEnabled(invocationArgv: string[]): boolean;
 declare function buildRuntimeExtensionDiscoverySnapshotCacheKey(pmRoot: string): string;
 declare function collectLeadingCommandArgs(commandArgs: readonly string[] | undefined): string[];
+/** Match leading command paths against both native history spellings and stable extension operation identities. */
 declare function collectActivationCommandCandidates(probe: RuntimeExtensionActivationProbe): string[];
 declare function activationCommandMatchesProbe(command: string, probe: RuntimeExtensionActivationProbe): boolean;
 declare function extensionActivationCommands(extension: ExtensionDiscoveryResult["effective"][number]): string[];
@@ -156,6 +158,7 @@ declare function maybeLoadRuntimeExtensions(command: Command): Promise<{
 declare function loadRuntimeExtensionCommandDescriptorsForRecovery(pmRoot: string): Promise<Map<string, ExtensionCommandHelpDescriptor>>;
 declare function executeRegisteredRuntimeMigrations(migrations: RegisteredExtensionSchemaMigrationDefinition[], pmRoot: string): Promise<string[]>;
 declare function runRequiredExtensionCommand(command: Command, options: Record<string, unknown>, globalOptions: GlobalOptions, extensionFlagDefinitions?: LooseCommandFlagDefinition[]): Promise<unknown>;
+/** Wrap each action once so validated parser overrides and extension handlers precede the original core action. */
 declare function wrapProgramActionsForExtensionHandlers(rootProgram: Command): void;
 /** Apply descendant-derived visibility to every generated extension namespace. */
 declare function applyDynamicExtensionRootHelpVisibility(rootProgram: Command, preexistingTopLevelCommands: ReadonlySet<string>, descriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>): void;
@@ -168,6 +171,7 @@ interface CoreCommandRegistrationSelection {
     targetCommandName?: string;
 }
 declare function invocationRequestsVersion(invocationArgv: string[]): boolean;
+/** Load only the selected core registration family, retaining complete discovery for help and unknown paths. */
 declare function resolveCoreCommandRegistrationSelection(invocationArgv: string[]): CoreCommandRegistrationSelection;
 declare function shouldAttachRichHelpTextForInvocation(invocationArgv: string[]): boolean;
 /**