@unbrained/pm-cli 2026.9.6 → 2026.9.8

package/dist/cli/commander-usage.js

@@ -1,773 +1,13 @@
+!(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]="61341599-3083-5e96-b455-65290be67c1b")}catch(e2){}})();import{pathExists,resolveItemTypeRegistry,EXIT_CODE,getSettingsPath,resolvePmRoot,readSettings,getActiveExtensionRegistrations,locateItem,runActiveServiceOverride,levenshteinDistanceWithinLimit}from"../sdk/runtime-primitives.js";import{BUILTIN_ITEM_TYPE_VALUES}from"../types/index.js";import{PM_CORE_COMMAND_NAMES,resolveSubcommandFlagContractsForCommand}from"../sdk/cli-contracts.js";import{formatCommanderErrorForDisplay,formatCommanderErrorForJson,projectLeanErrorEnvelope}from"./error-guidance.js";import{normalizeHelpCommandPath}from"./help-content.js";import{getCommandPath}from"./registration-helpers.js";import{EXECUTABLE_COMMAND_ALIASES,findBootstrapCommandTokenIndex,normalizeBootstrapInvocation,parseBootstrapHelpRequest,parseBootstrapGlobalOptions,parseBootstrapCommandName}from"./bootstrap-args.js";import{extractProvidedOptionFlags,normalizeLongFlag,renderPmCommand}from"./argv-utils.js";import{normalizeExtensionNameForMatch}from"./commands/extension/shared.js";import{rankCommandPaths}from"../sdk/agent/command-suggestions.js";import{renderMissingOptionRetry}from"../sdk/agent/command-recovery.js";import{attachOutputTokenAccounting}from"../sdk/output-token-accounting.js";const BUILTIN_TYPE_HELP_VALUES=BUILTIN_ITEM_TYPE_VALUES.join("|");const OPTIONAL_PACKAGE_INSTALL_HINTS={calendar:"calendar",cal:"calendar",reindex:"search-advanced","search-advanced":"search-advanced",guide:"guide-shell",completion:"guide-shell",templates:"templates","test-runs":"linked-test-adapters",beads:"beads",todos:"todos"};const SEMANTIC_UNKNOWN_OPTION_SUGGESTIONS={comments:{"--body":["--add"],"--text":["--add"],"--comment":["--add"]},notes:{"--body":["--add"],"--text":["--add"],"--note":["--add"]},learnings:{"--body":["--add"],"--text":["--add"],"--learning":["--add"]},update:{"--add-tag":["--add-tags"],"--remove-tag":["--remove-tags"],"--tag":["--tags"]},create:{"--add-tag":["--add-tags"],"--tag":["--tags"]}};const SCHEMA_SUBCOMMAND_VALUES=["add-field","add-status","add-type","apply-preset","list","list-fields","remap-status","remove-field","remove-status","remove-type","rename-field","rename-type","show","show-field","show-status"];function getSemanticUnknownOptionSuggestions(commandName,unknownOption){const commandSuggestions=SEMANTIC_UNKNOWN_OPTION_SUGGESTIONS[commandName];if(!commandSuggestions){return[]}const normalizedUnknown=normalizeLongFlag(unknownOption);for(const[flag,suggestions]of Object.entries(commandSuggestions)){if(normalizeLongFlag(flag)===normalizedUnknown){return suggestions}}return[]}function appendCommanderExtensionFailures(renderedUsage,json,failures){if(failures.length===0){return renderedUsage}if(json){const primaryFailure2=failures.find(entry=>entry.declared_command_match===true);const{token_accounting:priorAccounting,...usage}=JSON.parse(renderedUsage);const enriched={...usage,...primaryFailure2?{extension_command_failure:{code:"extension_command_activation_failed",extension:primaryFailure2.name,layer:primaryFailure2.layer,error:primaryFailure2.error,recovery_commands:primaryFailure2.recovery_commands??[]}}:{},failed_extensions:failures};return JSON.stringify(priorAccounting===void 0?enriched:attachOutputTokenAccounting(enriched,value=>`${JSON.stringify(value,null,2)}
+`),null,2)}const details=failures.map(entry=>`- ${entry.layer}:${entry.name}: ${entry.error}`).join("\n");const primaryFailure=failures.find(entry=>entry.declared_command_match===true);if(!primaryFailure){return`${renderedUsage}
+Extension activation failures:
+${details}`}const recovery=(primaryFailure.recovery_commands??[]).map(command=>`- ${command}`).join("\n");return`Extension command unavailable: ${primaryFailure.layer}:${primaryFailure.name}
+${primaryFailure.error}${recovery.length>0?`
+Recovery:
+${recovery}`:""}
 
-!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]="18758585-648f-5422-80e4-fbc7478c3cf3")}catch(e){}}();
-import { pathExists, resolveItemTypeRegistry, EXIT_CODE, getSettingsPath, resolvePmRoot, readSettings, getActiveExtensionRegistrations, locateItem, runActiveServiceOverride, levenshteinDistanceWithinLimit, } from "../sdk/runtime-primitives.js";
-import { BUILTIN_ITEM_TYPE_VALUES } from "../types/index.js";
-import { PM_CORE_COMMAND_NAMES, resolveSubcommandFlagContractsForCommand, } from "../sdk/cli-contracts.js";
-import { formatCommanderErrorForDisplay, formatCommanderErrorForJson, projectLeanErrorEnvelope, } from "./error-guidance.js";
-import { normalizeHelpCommandPath } from "./help-content.js";
-import { getCommandPath } from "./registration-helpers.js";
-import { EXECUTABLE_COMMAND_ALIASES, findBootstrapCommandTokenIndex, normalizeBootstrapInvocation, parseBootstrapHelpRequest, parseBootstrapGlobalOptions, parseBootstrapCommandName, } from "./bootstrap-args.js";
-import { extractProvidedOptionFlags, normalizeLongFlag, renderPmCommand, } from "./argv-utils.js";
-import { normalizeExtensionNameForMatch } from "./commands/extension/shared.js";
-import { rankCommandPaths } from "../sdk/agent/command-suggestions.js";
-import { renderMissingOptionRetry } from "../sdk/agent/command-recovery.js";
-import { attachOutputTokenAccounting } from "../sdk/output-token-accounting.js";
-/** Supported values accepted by the builtin type help contract. */
-export const BUILTIN_TYPE_HELP_VALUES = BUILTIN_ITEM_TYPE_VALUES.join("|");
-const OPTIONAL_PACKAGE_INSTALL_HINTS = {
-    calendar: "calendar",
-    cal: "calendar",
-    reindex: "search-advanced",
-    "search-advanced": "search-advanced",
-    guide: "guide-shell",
-    completion: "guide-shell",
-    templates: "templates",
-    "test-runs": "linked-test-adapters",
-    beads: "beads",
-    todos: "todos",
-};
-const SEMANTIC_UNKNOWN_OPTION_SUGGESTIONS = {
-    comments: {
-        "--body": ["--add"],
-        "--text": ["--add"],
-        "--comment": ["--add"],
-    },
-    notes: {
-        "--body": ["--add"],
-        "--text": ["--add"],
-        "--note": ["--add"],
-    },
-    learnings: {
-        "--body": ["--add"],
-        "--text": ["--add"],
-        "--learning": ["--add"],
-    },
-    // pm update / pm create now accept --add-tags natively, so the singular
-    // --add-tag and the old "--tag" mistype still need to be redirected at the
-    // canonical additive flag (not at --tags, which would silently replace).
-    update: {
-        "--add-tag": ["--add-tags"],
-        "--remove-tag": ["--remove-tags"],
-        "--tag": ["--tags"],
-    },
-    create: {
-        "--add-tag": ["--add-tags"],
-        "--tag": ["--tags"],
-    },
-};
-const SCHEMA_SUBCOMMAND_VALUES = [
-    "add-field",
-    "add-status",
-    "add-type",
-    "apply-preset",
-    "list",
-    "list-fields",
-    "remap-status",
-    "remove-field",
-    "remove-status",
-    "remove-type",
-    "rename-field",
-    "rename-type",
-    "show",
-    "show-field",
-    "show-status",
-];
-function getSemanticUnknownOptionSuggestions(commandName, unknownOption) {
-    const commandSuggestions = SEMANTIC_UNKNOWN_OPTION_SUGGESTIONS[commandName];
-    if (!commandSuggestions) {
-        return [];
-    }
-    const normalizedUnknown = normalizeLongFlag(unknownOption);
-    for (const [flag, suggestions] of Object.entries(commandSuggestions)) {
-        if (normalizeLongFlag(flag) === normalizedUnknown) {
-            return suggestions;
-        }
-    }
-    return [];
-}
-/** Append extension activation failures to text or JSON Commander usage output. */
-export function appendCommanderExtensionFailures(renderedUsage, json, failures) {
-    if (failures.length === 0) {
-        return renderedUsage;
-    }
-    if (json) {
-        const primaryFailure = failures.find((entry) => entry.declared_command_match === true);
-        const { token_accounting: priorAccounting, ...usage } = JSON.parse(renderedUsage);
-        const enriched = {
-            ...usage,
-            ...(primaryFailure
-                ? {
-                    extension_command_failure: {
-                        code: "extension_command_activation_failed",
-                        extension: primaryFailure.name,
-                        layer: primaryFailure.layer,
-                        error: primaryFailure.error,
-                        recovery_commands: primaryFailure.recovery_commands ?? [],
-                    },
-                }
-                : {}),
-            failed_extensions: failures,
-        };
-        return JSON.stringify(priorAccounting === undefined ? enriched : attachOutputTokenAccounting(enriched, (value) => `${JSON.stringify(value, null, 2)}\n`), null, 2);
-    }
-    const details = failures
-        .map((entry) => `- ${entry.layer}:${entry.name}: ${entry.error}`)
-        .join("\n");
-    const primaryFailure = failures.find((entry) => entry.declared_command_match === true);
-    if (!primaryFailure) {
-        return `${renderedUsage}\nExtension activation failures:\n${details}`;
-    }
-    const recovery = (primaryFailure.recovery_commands ?? [])
-        .map((command) => `- ${command}`)
-        .join("\n");
-    return `Extension command unavailable: ${primaryFailure.layer}:${primaryFailure.name}\n${primaryFailure.error}${recovery.length > 0 ? `\nRecovery:\n${recovery}` : ""}\n\n${renderedUsage}\nExtension activation failures:\n${details}`;
-}
-/** Resolve the unknown command token from help or ordinary invocation syntax. */
-export function resolveUnknownCommanderToken(invocationArgv) {
-    const helpRequest = parseBootstrapHelpRequest(invocationArgv);
-    return (helpRequest.commandPathTokens[0] ??
-        parseBootstrapCommandName(invocationArgv) ??
-        "<command>");
-}
-/** Implements collect runtime command paths for the public runtime surface of this module. */
-export function collectRuntimeCommandPaths(root, extensionDescriptors) {
-    const commandPaths = new Set();
-    const queue = [...root.commands];
-    while (queue.length > 0) {
-        const current = queue.shift();
-        if (!current) {
-            continue;
-        }
-        const normalizedPath = normalizeHelpCommandPath(getCommandPath(current));
-        const hasInternalSegment = normalizedPath
-            .split(" ")
-            .some((segment) => segment.startsWith("_"));
-        if (normalizedPath.length > 0 && !hasInternalSegment) {
-            commandPaths.add(normalizedPath);
-        }
-        queue.push(...current.commands);
-    }
-    for (const descriptorPath of extensionDescriptors.keys()) {
-        const normalizedPath = normalizeHelpCommandPath(descriptorPath);
-        const hasInternalSegment = normalizedPath
-            .split(" ")
-            .some((segment) => segment.startsWith("_"));
-        if (normalizedPath.length > 0 && !hasInternalSegment) {
-            commandPaths.add(normalizedPath);
-        }
-    }
-    return [...commandPaths].sort((left, right) => left.localeCompare(right));
-}
-/** Implements score command path match for the public runtime surface of this module. */
-export function scoreCommandPathMatch(commandPath, queryToken) {
-    const normalizedPath = commandPath.trim().toLowerCase();
-    const normalizedToken = queryToken.trim().toLowerCase();
-    if (normalizedToken.length === 0) {
-        return Number.POSITIVE_INFINITY;
-    }
-    const pathSegments = normalizedPath.split(" ");
-    if (normalizedPath === normalizedToken) {
-        return 0;
-    }
-    if (pathSegments.includes(normalizedToken)) {
-        return 1;
-    }
-    if (pathSegments.some((segment) => segment.startsWith(normalizedToken))) {
-        return 2;
-    }
-    if (normalizedPath.includes(normalizedToken)) {
-        return 3;
-    }
-    // Fall back to edit distance so transposition/typo cases (e.g. "lst" -> "list") still rank.
-    const maxDistance = normalizedToken.length >= 5 ? 2 : 1;
-    let bestDistance = Number.POSITIVE_INFINITY;
-    for (const segment of pathSegments) {
-        const distance = levenshteinDistanceWithinLimit(segment, normalizedToken, maxDistance);
-        if (distance !== null) {
-            bestDistance = Math.min(bestDistance, distance);
-        }
-    }
-    if (Number.isFinite(bestDistance)) {
-        return 4 + bestDistance;
-    }
-    return Number.POSITIVE_INFINITY;
-}
-function toComparableFlag(flag) {
-    return normalizeLongFlag(flag).slice(2).replace(/-/g, "");
-}
-function renderAttemptedCommand(argv) {
-    return renderPmCommand(argv);
-}
-function resolveOptionalPackageInstallHint(commandPath) {
-    const topLevel = commandPath.split(" ")[0]?.trim().toLowerCase();
-    if (!topLevel) {
-        return null;
-    }
-    const packageAlias = OPTIONAL_PACKAGE_INSTALL_HINTS[topLevel];
-    if (!packageAlias) {
-        return null;
-    }
-    return `If this command comes from an optional package, install it with: pm install ${packageAlias}`;
-}
-function normalizePackageCommandAliasToken(value) {
-    let normalized = normalizeExtensionNameForMatch(value);
-    // Strip outer package/source prefixes and then the pm- package stem so scoped
-    // and builtin package guesses converge on the exported command alias.
-    for (const prefix of ["@unbrained/", "builtin-", "pm-"]) {
-        if (normalized.startsWith(prefix)) {
-            normalized = normalized.slice(prefix.length);
-        }
-    }
-    return normalized;
-}
-function collectInstalledPackageCommandPathHints(unknownToken, extensionDescriptors) {
-    const normalizedUnknown = normalizePackageCommandAliasToken(unknownToken);
-    if (normalizedUnknown.length === 0) {
-        return [];
-    }
-    const hints = [];
-    for (const descriptor of extensionDescriptors.values()) {
-        const identifiers = new Set();
-        const source = descriptor.source;
-        if (source) {
-            for (const identifier of [source.name, source.package]) {
-                const normalizedIdentifier = normalizePackageCommandAliasToken(identifier ?? "");
-                if (normalizedIdentifier.length > 0) {
-                    identifiers.add(normalizedIdentifier);
-                }
-            }
-        }
-        if (identifiers.size === 0) {
-            continue;
-        }
-        const matches = [...identifiers].some((identifier) => identifier === normalizedUnknown ||
-            identifier.includes(normalizedUnknown) ||
-            normalizedUnknown.includes(identifier));
-        if (matches) {
-            hints.push(descriptor.command);
-        }
-    }
-    return [...new Set(hints)].sort((left, right) => left.localeCompare(right));
-}
-function collectKnownLongFlags(commandName, contractsOverride) {
-    const flags = new Set();
-    const contracts = contractsOverride ?? resolveSubcommandFlagContractsForCommand(commandName);
-    for (const contract of contracts) {
-        if (contract.flag.startsWith("--")) {
-            flags.add(normalizeLongFlag(contract.flag));
-        }
-        for (const alias of contract.aliases ?? []) {
-            if (alias.startsWith("--")) {
-                flags.add(normalizeLongFlag(alias));
-            }
-        }
-    }
-    return [...flags].sort((left, right) => left.localeCompare(right));
-}
-function suggestNearestLongFlags(unknownOption, knownFlags) {
-    if (!unknownOption.startsWith("--")) {
-        return [];
-    }
-    const unknownComparable = toComparableFlag(unknownOption);
-    if (unknownComparable.length === 0) {
-        return [];
-    }
-    const maxDistance = unknownComparable.length >= 8 ? 2 : 1;
-    // rank 0 = abbreviation/prefix match (e.g. --desc -> --description), rank 1 = edit-distance typo.
-    const candidates = [];
-    for (const flag of knownFlags) {
-        const flagComparable = toComparableFlag(flag);
-        if (flagComparable === unknownComparable) {
-            continue;
-        }
-        if (unknownComparable.length >= 3 &&
-            flagComparable.startsWith(unknownComparable)) {
-            candidates.push({
-                flag,
-                rank: 0,
-                distance: flagComparable.length - unknownComparable.length,
-            });
-            continue;
-        }
-        const distance = levenshteinDistanceWithinLimit(unknownComparable, flagComparable, maxDistance);
-        if (distance === null || distance <= 0) {
-            continue;
-        }
-        candidates.push({ flag, rank: 1, distance });
-    }
-    return candidates
-        .sort((left, right) => {
-        if (left.rank !== right.rank) {
-            return left.rank - right.rank;
-        }
-        if (left.distance !== right.distance) {
-            return left.distance - right.distance;
-        }
-        return left.flag.localeCompare(right.flag);
-    })
-        .map((entry) => entry.flag)
-        .slice(0, 3);
-}
-let crossCommandFlagIndexCache;
-// Alias/shortcut command names that duplicate a canonical command. Excluding them
-// keeps cross-command flag hints focused on the primary commands an agent should use.
-const CROSS_COMMAND_FLAG_EXCLUSIONS = new Set([
-    "ctx",
-    "packages",
-    "list-draft",
-    "list-open",
-    "list-in-progress",
-    "list-blocked",
-    "list-closed",
-    "list-canceled",
-    "start-task",
-    "pause-task",
-    "close-task",
-    "help",
-]);
-// Index of long flag -> command names that accept it (in declaration order), so an
-// unknown flag on one command can be recognised as valid elsewhere (e.g. --type is
-// rejected on test-all but valid on create/list). Built once from core command contracts.
-function getCrossCommandFlagIndex() {
-    if (crossCommandFlagIndexCache) {
-        return crossCommandFlagIndexCache;
-    }
-    const index = new Map();
-    for (const command of PM_CORE_COMMAND_NAMES) {
-        if (CROSS_COMMAND_FLAG_EXCLUSIONS.has(command)) {
-            continue;
-        }
-        for (const flag of collectKnownLongFlags(command)) {
-            const commands = index.get(flag) ?? [];
-            commands.push(command);
-            index.set(flag, commands);
-        }
-    }
-    crossCommandFlagIndexCache = index;
-    return crossCommandFlagIndexCache;
-}
-function findOtherCommandsForFlag(unknownOption, currentCommand) {
-    if (!unknownOption.startsWith("--")) {
-        return [];
-    }
-    const commands = getCrossCommandFlagIndex().get(normalizeLongFlag(unknownOption));
-    if (!commands) {
-        return [];
-    }
-    const normalizedCurrent = currentCommand?.trim().toLowerCase();
-    const currentFlags = new Set(collectKnownLongFlags(normalizedCurrent));
-    return commands
-        .filter((command) => command !== normalizedCurrent)
-        .map((command) => ({
-        command,
-        sharedFlagCount: collectKnownLongFlags(command).filter((flag) => currentFlags.has(flag)).length,
-    }))
-        .sort((left, right) => left.sharedFlagCount !== right.sharedFlagCount
-        ? right.sharedFlagCount - left.sharedFlagCount
-        : left.command.localeCompare(right.command))
-        .map(({ command }) => command);
-}
-function rewriteUnknownOptionArgv(argv, unknownOption, replacementFlag) {
-    for (let index = 0; index < argv.length; index += 1) {
-        const token = argv[index];
-        if (!token.startsWith("--")) {
-            continue;
-        }
-        const equalsIndex = token.indexOf("=");
-        const key = equalsIndex >= 0 ? token.slice(0, equalsIndex) : token;
-        if (normalizeLongFlag(key) !== normalizeLongFlag(unknownOption)) {
-            continue;
-        }
-        const next = [...argv];
-        next[index] =
-            equalsIndex >= 0
-                ? `${replacementFlag}${token.slice(equalsIndex)}`
-                : replacementFlag;
-        return next;
-    }
-    return undefined;
-}
-function scoreRuntimeCommandCandidates(params) {
-    const commandPathSet = new Set(params.commandPaths);
-    const scoreAgainstUnknown = (candidatePath) => Math.min(scoreCommandPathMatch(candidatePath, params.normalizedUnknown), params.primaryToken !== params.normalizedUnknown
-        ? scoreCommandPathMatch(candidatePath, params.primaryToken)
-        : Number.POSITIVE_INFINITY);
-    const scoresByCommandPath = new Map();
-    const recordCandidateScore = (commandPath, score) => {
-        if (!Number.isFinite(score) || !commandPathSet.has(commandPath)) {
-            return;
-        }
-        const existing = scoresByCommandPath.get(commandPath);
-        if (existing === undefined || score < existing) {
-            scoresByCommandPath.set(commandPath, score);
-        }
-    };
-    for (const commandPath of params.commandPaths) {
-        recordCandidateScore(commandPath, scoreAgainstUnknown(commandPath));
-    }
-    for (const [aliasToken, canonicalPath] of Object.entries(EXECUTABLE_COMMAND_ALIASES)) {
-        if (aliasToken === "read") {
-            continue;
-        }
-        recordCandidateScore(canonicalPath, scoreAgainstUnknown(aliasToken));
-    }
-    return [...scoresByCommandPath.entries()]
-        .sort(([leftPath, leftScore], [rightPath, rightScore]) => leftScore !== rightScore
-        ? leftScore - rightScore
-        : leftPath.localeCompare(rightPath))
-        .map(([commandPath]) => commandPath);
-}
-function resolveUnknownCommandCandidates(params) {
-    const semanticCandidates = rankCommandPaths(params.commandPaths, params.primaryToken);
-    const rankedCandidates = scoreRuntimeCommandCandidates(params);
-    const installedPackageCandidates = collectInstalledPackageCommandPathHints(params.primaryToken, params.extensionDescriptors).filter((commandPath) => params.commandPaths.includes(commandPath));
-    return dedupeStrings([
-        ...semanticCandidates,
-        ...rankedCandidates,
-        ...installedPackageCandidates,
-    ]);
-}
-function resolveUnknownCommandFallbacks(commandPaths) {
-    const topLevel = [
-        ...new Set(commandPaths
-            .map((commandPath) => commandPath.split(" ")[0])
-            .filter((segment) => segment.length > 0)),
-    ];
-    return topLevel.sort((left, right) => left.localeCompare(right));
-}
-function buildUnknownCommandExamples(suggestedPaths, hasConcreteCandidates) {
-    const suggestedExamples = suggestedPaths.map((path) => `pm ${path} --help`);
-    if (hasConcreteCandidates) {
-        return [...new Set([...suggestedExamples, "pm --help --all"])];
-    }
-    return [...new Set(["pm --help --all", ...suggestedExamples])];
-}
-/** Implements build unknown command guidance from runtime for the public runtime surface of this module. */
-export function buildUnknownCommandGuidanceFromRuntime(rawMessage, root, extensionDescriptors) {
-    const unknownCommandMatch = rawMessage.match(/unknown command '([^']+)'/i);
-    if (!unknownCommandMatch || typeof unknownCommandMatch[1] !== "string") {
-        return undefined;
-    }
-    const normalizedUnknown = normalizeHelpCommandPath(unknownCommandMatch[1]);
-    if (normalizedUnknown.length === 0) {
-        return undefined;
-    }
-    const commandPaths = collectRuntimeCommandPaths(root, extensionDescriptors);
-    if (commandPaths.length === 0) {
-        return undefined;
-    }
-    const primaryToken = normalizedUnknown.split(" ")[0];
-    // Executable aliases are scored against their canonical runtime command, so a
-    // typo of an alias still points at the command path that would actually run.
-    const combinedCandidates = resolveUnknownCommandCandidates({
-        commandPaths,
-        normalizedUnknown,
-        primaryToken,
-        extensionDescriptors,
-    });
-    const fallbackTopLevel = resolveUnknownCommandFallbacks(commandPaths);
-    const suggestedPaths = (combinedCandidates.length > 0 ? combinedCandidates : fallbackTopLevel).slice(0, 3);
-    const examples = buildUnknownCommandExamples(suggestedPaths, combinedCandidates.length > 0);
-    const optionalPackageHint = resolveOptionalPackageInstallHint(normalizedUnknown);
-    const didYouMean = combinedCandidates.length > 0
-        ? `Did you mean: ${suggestedPaths.join(", ")}?`
-        : null;
-    return {
-        unknownCommandExamples: examples,
-        unknownCommandNextSteps: [
-            ...(didYouMean ? [didYouMean] : []),
-            'Run "pm --help --all" to list every command available in this runtime, including active extensions.',
-            "Use one of the suggested command paths above with --help to inspect valid flags and usage.",
-            ...(optionalPackageHint ? [optionalPackageHint] : []),
-        ],
-    };
-}
-function dedupeStrings(values) {
-    return Array.from(new Set(values));
-}
-function firstWhitespaceSeparatedToken(input) {
-    let token = "";
-    for (const character of input) {
-        if (character === " " ||
-            character === "\t" ||
-            character === "\n" ||
-            character === "\r" ||
-            character === "\f" ||
-            character === "\v") {
-            break;
-        }
-        token += character;
-    }
-    return token;
-}
-function trimTrailingPunctuationToken(token) {
-    let end = token.length;
-    while (end > 0) {
-        const character = token[end - 1];
-        if (character !== "," && character !== ":" && character !== ";") {
-            break;
-        }
-        end -= 1;
-    }
-    return token.slice(0, end);
-}
-/** Implements resolve child command by token for the public runtime surface of this module. */
-export function resolveChildCommandByToken(parent, token) {
-    const normalizedToken = token.trim().toLowerCase();
-    return parent.commands.find((candidate) => {
-        if (candidate.name().trim().toLowerCase() === normalizedToken) {
-            return true;
-        }
-        const aliases = typeof candidate.aliases === "function" ? candidate.aliases() : [];
-        return aliases.some((alias) => alias.trim().toLowerCase() === normalizedToken);
-    });
-}
-/** Implements check whether known help command path for the public runtime surface of this module. */
-export function isKnownHelpCommandPath(root, commandPathTokens) {
-    if (commandPathTokens.length === 0) {
-        return true;
-    }
-    let current = root;
-    for (const [tokenIndex, token] of commandPathTokens.entries()) {
-        const next = resolveChildCommandByToken(current, token);
-        if (!next) {
-            const declaredArguments = current.registeredArguments;
-            return (declaredArguments.length > 0 &&
-                (current.commands.length === 0 || declaredArguments[0]?.required === true) &&
-                (declaredArguments.at(-1)?.variadic === true ||
-                    commandPathTokens.length - tokenIndex <= declaredArguments.length));
-        }
-        current = next;
-    }
-    return true;
-}
-async function resolveWorkspaceUsageContext(bootstrapGlobal, message, invocationArgv, commandName) {
-    try {
-        const pmRoot = resolvePmRoot(process.cwd(), bootstrapGlobal.path);
-        if (!(await pathExists(getSettingsPath(pmRoot)))) {
-            return { allowedTypes: BUILTIN_TYPE_HELP_VALUES };
-        }
-        const settings = await readSettings(pmRoot);
-        const extensionRegistrations = bootstrapGlobal.noExtensions
-            ? undefined
-            : getActiveExtensionRegistrations();
-        const typeRegistry = resolveItemTypeRegistry(settings, extensionRegistrations);
-        let verifiedCollectionItemId;
-        if (/too many arguments/i.test(message) &&
-            ["comments", "docs", "files", "learnings", "notes", "test"].includes(commandName ?? "")) {
-            const commandIndex = invocationArgv.findIndex((token) => token === commandName);
-            const candidate = invocationArgv[commandIndex + 2];
-            if (invocationArgv[commandIndex + 1]?.toLowerCase() === "add" &&
-                candidate !== undefined &&
-                !candidate.startsWith("-")) {
-                try {
-                    verifiedCollectionItemId = (await locateItem(pmRoot, candidate, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder))?.id;
-                }
-                catch {
-                    // Usage rendering remains available when tracker storage is unreadable.
-                }
-            }
-        }
-        return {
-            allowedTypes: typeRegistry.types.length > 0
-                ? typeRegistry.types.join("|")
-                : BUILTIN_TYPE_HELP_VALUES,
-            pmRoot,
-            settings,
-            typeToFolder: typeRegistry.type_to_folder,
-            verifiedCollectionItemId,
-        };
-    }
-    catch {
-        /* v8 ignore start -- defensive fallback for corrupted settings during usage-error rendering; command behavior is covered through normal settings paths */
-        return { allowedTypes: BUILTIN_TYPE_HELP_VALUES };
-        /* v8 ignore stop */
-    }
-}
-function resolveUnknownOptionSuggestions(message, commandName) {
-    const match = message.match(/unknown option '([^']+)'/i);
-    const suggestions = match && commandName
-        ? dedupeStrings([
-            ...getSemanticUnknownOptionSuggestions(commandName, match[1]),
-            ...suggestNearestLongFlags(match[1], collectKnownLongFlags(commandName)),
-        ])
-        : undefined;
-    const otherCommands = match
-        ? findOtherCommandsForFlag(match[1], commandName)
-        : [];
-    const declaredOnPath = match !== null &&
-        collectKnownLongFlags(commandName).includes(normalizeLongFlag(match[1]));
-    return {
-        match,
-        suggestions,
-        otherCommands,
-        scope: declaredOnPath
-            ? "declared_on_path"
-            : otherCommands.length > 0
-                ? "declared_elsewhere"
-                : "declared_nowhere",
-    };
-}
-function resolveSuggestedRetryForUnknownOption(invocationArgv, unknownOptionMatch, unknownOptionSuggestions) {
-    if (!unknownOptionMatch ||
-        !unknownOptionSuggestions ||
-        unknownOptionSuggestions.length === 0) {
-        return undefined;
-    }
-    const rewritten = rewriteUnknownOptionArgv(invocationArgv, unknownOptionMatch[1], unknownOptionSuggestions[0]);
-    return rewritten ? renderAttemptedCommand(rewritten) : undefined;
-}
-function resolveSuggestedRetryForMissingOption(message, invocationArgv) {
-    const missingRequiredOption = message.match(/required option '([^']+)' not specified/i);
-    const requiredOptionToken = missingRequiredOption?.[1]
-        ? trimTrailingPunctuationToken(firstWhitespaceSeparatedToken(missingRequiredOption[1].trim()))
-        : undefined;
-    if (!requiredOptionToken?.startsWith("--")) {
-        return undefined;
-    }
-    const commandName = parseBootstrapCommandName(invocationArgv);
-    if (!commandName) {
-        return undefined;
-    }
-    return renderMissingOptionRetry(invocationArgv, commandName, [
-        requiredOptionToken,
-    ]);
-}
-function resolveSplitSchemaSubcommand(message, invocationArgv) {
-    if (!/too many arguments/i.test(message)) {
-        return undefined;
-    }
-    if (parseBootstrapCommandName(invocationArgv) !== "schema") {
-        return undefined;
-    }
-    const schemaIndex = findBootstrapCommandTokenIndex(invocationArgv);
-    const verb = invocationArgv[schemaIndex + 1]?.trim().toLowerCase();
-    const noun = invocationArgv[schemaIndex + 2]?.trim().toLowerCase();
-    if (!verb || !noun) {
-        return undefined;
-    }
-    const joined = `${verb}-${noun}`;
-    if (!SCHEMA_SUBCOMMAND_VALUES.includes(joined)) {
-        return undefined;
-    }
-    const rewritten = [
-        ...invocationArgv.slice(0, schemaIndex + 1),
-        joined,
-        ...invocationArgv.slice(schemaIndex + 3),
-    ];
-    return {
-        unknownSubcommandPath: "schema",
-        unknownSubcommandToken: `${verb} ${noun}`,
-        unknownSubcommandAllowedValues: [...SCHEMA_SUBCOMMAND_VALUES],
-        suggestedRetryCommand: renderAttemptedCommand(rewritten),
-    };
-}
-/** Implements resolve commander usage context for the public runtime surface of this module. */
-export async function resolveCommanderUsageContext(error, rootProgram, extensionDescriptors, guidanceOverrides = {}) {
-    const rawMessage = typeof error === "object" && error !== null
-        ? error.message
-        : undefined;
-    const message = rawMessage ?? "Invalid command usage";
-    const invocationArgv = normalizeBootstrapInvocation(process.argv.slice(2)).argv;
-    const bootstrapGlobal = parseBootstrapGlobalOptions(invocationArgv);
-    const commandName = parseBootstrapCommandName(invocationArgv);
-    const attemptedCommand = renderAttemptedCommand(invocationArgv);
-    const providedOptionFlags = extractProvidedOptionFlags(invocationArgv);
-    const workspaceUsage = await resolveWorkspaceUsageContext(bootstrapGlobal, message, invocationArgv, commandName);
-    const allowedTypes = workspaceUsage.allowedTypes;
-    const unknownCommandGuidance = buildUnknownCommandGuidanceFromRuntime(message, rootProgram, extensionDescriptors);
-    const unknownOption = resolveUnknownOptionSuggestions(message, commandName);
-    const splitSchemaSubcommand = resolveSplitSchemaSubcommand(message, invocationArgv);
-    const suggestedRetryCommand = splitSchemaSubcommand?.suggestedRetryCommand ??
-        resolveSuggestedRetryForUnknownOption(invocationArgv, unknownOption.match, unknownOption.suggestions) ??
-        resolveSuggestedRetryForMissingOption(message, invocationArgv);
-    return {
-        message,
-        commandName,
-        allowedTypes,
-        attemptedCommand,
-        normalizedInvocationArgs: [...invocationArgv],
-        providedOptionFlags,
-        unknownOptionSuggestions: unknownOption.suggestions,
-        unknownOptionOtherCommands: unknownOption.otherCommands.length > 0
-            ? unknownOption.otherCommands.slice(0, 12)
-            : undefined,
-        unknownOptionOtherCommandsTotal: unknownOption.otherCommands.length > 0
-            ? unknownOption.otherCommands.length
-            : undefined,
-        unknownOptionOtherCommandsTruncated: unknownOption.otherCommands.length > 12 || undefined,
-        unknownOptionScope: unknownOption.scope,
-        suggestedRetryCommand,
-        verifiedCollectionItemId: workspaceUsage.verifiedCollectionItemId,
-        ...splitSchemaSubcommand,
-        ...unknownCommandGuidance,
-        ...guidanceOverrides,
-    };
-}
-/** Implements format commander usage message for the public runtime surface of this module. */
-export async function formatCommanderUsageMessage(error, rootProgram, extensionDescriptors, guidanceOverrides = {}) {
-    const usageContext = await resolveCommanderUsageContext(error, rootProgram, extensionDescriptors, guidanceOverrides);
-    const { message, commandName, allowedTypes, unknownCommandExamples, unknownCommandNextSteps, attemptedCommand, normalizedInvocationArgs, providedOptionFlags, unknownOptionSuggestions, unknownOptionOtherCommands, unknownOptionOtherCommandsTotal, unknownOptionOtherCommandsTruncated, unknownOptionScope, unknownSubcommandPath, unknownSubcommandToken, unknownSubcommandAllowedValues, suggestedRetryCommand, verifiedCollectionItemId, failedExtensions, } = usageContext;
-    const formatted = formatCommanderErrorForDisplay(message, commandName, allowedTypes, {
-        unknownCommandExamples,
-        unknownCommandNextSteps,
-        attemptedCommand,
-        normalizedInvocationArgs,
-        providedOptionFlags,
-        unknownOptionSuggestions,
-        unknownOptionOtherCommands,
-        unknownOptionOtherCommandsTotal,
-        unknownOptionOtherCommandsTruncated,
-        unknownOptionScope,
-        unknownSubcommandPath,
-        unknownSubcommandToken,
-        unknownSubcommandAllowedValues,
-        suggestedRetryCommand,
-        verifiedCollectionItemId,
-        failedExtensions,
-    });
-    const serviceOverride = await runActiveServiceOverride("help_format", {
-        message: formatted,
-        command: commandName,
-        allowed_types: allowedTypes,
-    });
-    if (serviceOverride.handled && typeof serviceOverride.result === "string") {
-        return serviceOverride.result;
-    }
-    return formatted;
-}
-/** Implements format commander usage json for the public runtime surface of this module. */
-export async function formatCommanderUsageJson(error, rootProgram, extensionDescriptors, lean = false, guidanceOverrides = {}) {
-    const usageContext = await resolveCommanderUsageContext(error, rootProgram, extensionDescriptors, guidanceOverrides);
-    const envelope = formatCommanderErrorForJson(usageContext.message, usageContext.commandName, usageContext.allowedTypes, EXIT_CODE.USAGE, {
-        unknownCommandExamples: usageContext.unknownCommandExamples,
-        unknownCommandNextSteps: usageContext.unknownCommandNextSteps,
-        attemptedCommand: usageContext.attemptedCommand,
-        normalizedInvocationArgs: usageContext.normalizedInvocationArgs,
-        providedOptionFlags: usageContext.providedOptionFlags,
-        unknownOptionSuggestions: usageContext.unknownOptionSuggestions,
-        unknownOptionOtherCommands: usageContext.unknownOptionOtherCommands,
-        unknownOptionOtherCommandsTotal: usageContext.unknownOptionOtherCommandsTotal,
-        unknownOptionOtherCommandsTruncated: usageContext.unknownOptionOtherCommandsTruncated,
-        unknownOptionScope: usageContext.unknownOptionScope,
-        unknownSubcommandPath: usageContext.unknownSubcommandPath,
-        unknownSubcommandToken: usageContext.unknownSubcommandToken,
-        unknownSubcommandAllowedValues: usageContext.unknownSubcommandAllowedValues,
-        suggestedRetryCommand: usageContext.suggestedRetryCommand,
-        verifiedCollectionItemId: usageContext.verifiedCollectionItemId,
-        failedExtensions: usageContext.failedExtensions,
-    });
-    const projected = lean ? projectLeanErrorEnvelope(envelope) : envelope;
-    const accountingRequested = parseBootstrapGlobalOptions(usageContext.normalizedInvocationArgs).tokenAccounting === true;
-    return JSON.stringify(accountingRequested ? attachOutputTokenAccounting(projected, (value) => `${JSON.stringify(value, null, 2)}\n`) : projected, null, 2);
-}
-/** Public contract for test only, shared by SDK and presentation-layer consumers. */
-export const _testOnly = {
-    collectKnownLongFlags,
-    collectInstalledPackageCommandPathHints,
-    resolveOptionalPackageInstallHint,
-    resolveSuggestedRetryForMissingOption,
-    suggestNearestLongFlags,
-};
+${renderedUsage}
+Extension activation failures:
+${details}`}function resolveUnknownCommanderToken(invocationArgv){const helpRequest=parseBootstrapHelpRequest(invocationArgv);return helpRequest.commandPathTokens[0]??parseBootstrapCommandName(invocationArgv)??"<command>"}function collectRuntimeCommandPaths(root,extensionDescriptors){const commandPaths=new Set;const queue=[...root.commands];while(queue.length>0){const current=queue.shift();if(!current){continue}const normalizedPath=normalizeHelpCommandPath(getCommandPath(current));const hasInternalSegment=normalizedPath.split(" ").some(segment=>segment.startsWith("_"));if(normalizedPath.length>0&&!hasInternalSegment){commandPaths.add(normalizedPath)}queue.push(...current.commands)}for(const descriptorPath of extensionDescriptors.keys()){const normalizedPath=normalizeHelpCommandPath(descriptorPath);const hasInternalSegment=normalizedPath.split(" ").some(segment=>segment.startsWith("_"));if(normalizedPath.length>0&&!hasInternalSegment){commandPaths.add(normalizedPath)}}return[...commandPaths].sort((left,right)=>left.localeCompare(right))}function scoreCommandPathMatch(commandPath,queryToken){const normalizedPath=commandPath.trim().toLowerCase();const normalizedToken=queryToken.trim().toLowerCase();if(normalizedToken.length===0){return Number.POSITIVE_INFINITY}const pathSegments=normalizedPath.split(" ");if(normalizedPath===normalizedToken){return 0}if(pathSegments.includes(normalizedToken)){return 1}if(pathSegments.some(segment=>segment.startsWith(normalizedToken))){return 2}if(normalizedPath.includes(normalizedToken)){return 3}const maxDistance=normalizedToken.length>=5?2:1;let bestDistance=Number.POSITIVE_INFINITY;for(const segment of pathSegments){const distance=levenshteinDistanceWithinLimit(segment,normalizedToken,maxDistance);if(distance!==null){bestDistance=Math.min(bestDistance,distance)}}if(Number.isFinite(bestDistance)){return 4+bestDistance}return Number.POSITIVE_INFINITY}function toComparableFlag(flag){return normalizeLongFlag(flag).slice(2).replace(/-/g,"")}function renderAttemptedCommand(argv){return renderPmCommand(argv)}function resolveOptionalPackageInstallHint(commandPath){const topLevel=commandPath.split(" ")[0]?.trim().toLowerCase();if(!topLevel){return null}const packageAlias=OPTIONAL_PACKAGE_INSTALL_HINTS[topLevel];if(!packageAlias){return null}return`If this command comes from an optional package, install it with: pm install ${packageAlias}`}function normalizePackageCommandAliasToken(value){let normalized=normalizeExtensionNameForMatch(value);for(const prefix of["@unbrained/","builtin-","pm-"]){if(normalized.startsWith(prefix)){normalized=normalized.slice(prefix.length)}}return normalized}function collectInstalledPackageCommandPathHints(unknownToken,extensionDescriptors){const normalizedUnknown=normalizePackageCommandAliasToken(unknownToken);if(normalizedUnknown.length===0){return[]}const hints=[];for(const descriptor of extensionDescriptors.values()){const identifiers=new Set;const source=descriptor.source;if(source){for(const identifier of[source.name,source.package]){const normalizedIdentifier=normalizePackageCommandAliasToken(identifier??"");if(normalizedIdentifier.length>0){identifiers.add(normalizedIdentifier)}}}if(identifiers.size===0){continue}const matches=[...identifiers].some(identifier=>identifier===normalizedUnknown||identifier.includes(normalizedUnknown)||normalizedUnknown.includes(identifier));if(matches){hints.push(descriptor.command)}}return[...new Set(hints)].sort((left,right)=>left.localeCompare(right))}function collectKnownLongFlags(commandName,contractsOverride){const flags=new Set;const contracts=contractsOverride??resolveSubcommandFlagContractsForCommand(commandName);for(const contract of contracts){if(contract.flag.startsWith("--")){flags.add(normalizeLongFlag(contract.flag))}for(const alias of contract.aliases??[]){if(alias.startsWith("--")){flags.add(normalizeLongFlag(alias))}}}return[...flags].sort((left,right)=>left.localeCompare(right))}function suggestNearestLongFlags(unknownOption,knownFlags){if(!unknownOption.startsWith("--")){return[]}const unknownComparable=toComparableFlag(unknownOption);if(unknownComparable.length===0){return[]}const maxDistance=unknownComparable.length>=8?2:1;const candidates=[];for(const flag of knownFlags){const flagComparable=toComparableFlag(flag);if(flagComparable===unknownComparable){continue}if(unknownComparable.length>=3&&flagComparable.startsWith(unknownComparable)){candidates.push({flag,rank:0,distance:flagComparable.length-unknownComparable.length});continue}const distance=levenshteinDistanceWithinLimit(unknownComparable,flagComparable,maxDistance);if(distance===null||distance<=0){continue}candidates.push({flag,rank:1,distance})}return candidates.sort((left,right)=>{if(left.rank!==right.rank){return left.rank-right.rank}if(left.distance!==right.distance){return left.distance-right.distance}return left.flag.localeCompare(right.flag)}).map(entry=>entry.flag).slice(0,3)}let crossCommandFlagIndexCache;const CROSS_COMMAND_FLAG_EXCLUSIONS=new Set(["ctx","packages","list-draft","list-open","list-in-progress","list-blocked","list-closed","list-canceled","start-task","pause-task","close-task","help"]);function getCrossCommandFlagIndex(){if(crossCommandFlagIndexCache){return crossCommandFlagIndexCache}const index=new Map;for(const command of PM_CORE_COMMAND_NAMES){if(CROSS_COMMAND_FLAG_EXCLUSIONS.has(command)){continue}for(const flag of collectKnownLongFlags(command)){const commands=index.get(flag)??[];commands.push(command);index.set(flag,commands)}}crossCommandFlagIndexCache=index;return crossCommandFlagIndexCache}function findOtherCommandsForFlag(unknownOption,currentCommand){if(!unknownOption.startsWith("--")){return[]}const commands=getCrossCommandFlagIndex().get(normalizeLongFlag(unknownOption));if(!commands){return[]}const normalizedCurrent=currentCommand?.trim().toLowerCase();const currentFlags=new Set(collectKnownLongFlags(normalizedCurrent));return commands.filter(command=>command!==normalizedCurrent).map(command=>({command,sharedFlagCount:collectKnownLongFlags(command).filter(flag=>currentFlags.has(flag)).length})).sort((left,right)=>left.sharedFlagCount!==right.sharedFlagCount?right.sharedFlagCount-left.sharedFlagCount:left.command.localeCompare(right.command)).map(({command})=>command)}function rewriteUnknownOptionArgv(argv,unknownOption,replacementFlag){for(let index=0;index<argv.length;index+=1){const token=argv[index];if(!token.startsWith("--")){continue}const equalsIndex=token.indexOf("=");const key=equalsIndex>=0?token.slice(0,equalsIndex):token;if(normalizeLongFlag(key)!==normalizeLongFlag(unknownOption)){continue}const next=[...argv];next[index]=equalsIndex>=0?`${replacementFlag}${token.slice(equalsIndex)}`:replacementFlag;return next}return void 0}function scoreRuntimeCommandCandidates(params){const commandPathSet=new Set(params.commandPaths);const scoreAgainstUnknown=candidatePath=>Math.min(scoreCommandPathMatch(candidatePath,params.normalizedUnknown),params.primaryToken!==params.normalizedUnknown?scoreCommandPathMatch(candidatePath,params.primaryToken):Number.POSITIVE_INFINITY);const scoresByCommandPath=new Map;const recordCandidateScore=(commandPath,score)=>{if(!Number.isFinite(score)||!commandPathSet.has(commandPath)){return}const existing=scoresByCommandPath.get(commandPath);if(existing===void 0||score<existing){scoresByCommandPath.set(commandPath,score)}};for(const commandPath of params.commandPaths){recordCandidateScore(commandPath,scoreAgainstUnknown(commandPath))}for(const[aliasToken,canonicalPath]of Object.entries(EXECUTABLE_COMMAND_ALIASES)){if(aliasToken==="read"){continue}recordCandidateScore(canonicalPath,scoreAgainstUnknown(aliasToken))}return[...scoresByCommandPath.entries()].sort(([leftPath,leftScore],[rightPath,rightScore])=>leftScore!==rightScore?leftScore-rightScore:leftPath.localeCompare(rightPath)).map(([commandPath])=>commandPath)}function resolveUnknownCommandCandidates(params){const semanticCandidates=rankCommandPaths(params.commandPaths,params.primaryToken);const rankedCandidates=scoreRuntimeCommandCandidates(params);const installedPackageCandidates=collectInstalledPackageCommandPathHints(params.primaryToken,params.extensionDescriptors).filter(commandPath=>params.commandPaths.includes(commandPath));return dedupeStrings([...semanticCandidates,...rankedCandidates,...installedPackageCandidates])}function resolveUnknownCommandFallbacks(commandPaths){const topLevel=[...new Set(commandPaths.map(commandPath=>commandPath.split(" ")[0]).filter(segment=>segment.length>0))];return topLevel.sort((left,right)=>left.localeCompare(right))}function buildUnknownCommandExamples(suggestedPaths,hasConcreteCandidates){const suggestedExamples=suggestedPaths.map(path=>`pm ${path} --help`);if(hasConcreteCandidates){return[...new Set([...suggestedExamples,"pm --help --all"])]}return[...new Set(["pm --help --all",...suggestedExamples])]}function buildUnknownCommandGuidanceFromRuntime(rawMessage,root,extensionDescriptors){const unknownCommandMatch=rawMessage.match(/unknown command '([^']+)'/i);if(!unknownCommandMatch||typeof unknownCommandMatch[1]!=="string"){return void 0}const normalizedUnknown=normalizeHelpCommandPath(unknownCommandMatch[1]);if(normalizedUnknown.length===0){return void 0}const commandPaths=collectRuntimeCommandPaths(root,extensionDescriptors);if(commandPaths.length===0){return void 0}const primaryToken=normalizedUnknown.split(" ")[0];const combinedCandidates=resolveUnknownCommandCandidates({commandPaths,normalizedUnknown,primaryToken,extensionDescriptors});const fallbackTopLevel=resolveUnknownCommandFallbacks(commandPaths);const suggestedPaths=(combinedCandidates.length>0?combinedCandidates:fallbackTopLevel).slice(0,3);const examples=buildUnknownCommandExamples(suggestedPaths,combinedCandidates.length>0);const optionalPackageHint=resolveOptionalPackageInstallHint(normalizedUnknown);const didYouMean=combinedCandidates.length>0?`Did you mean: ${suggestedPaths.join(", ")}?`:null;return{unknownCommandExamples:examples,unknownCommandNextSteps:[...didYouMean?[didYouMean]:[],'Run "pm --help --all" to list every command available in this runtime, including active extensions.',"Use one of the suggested command paths above with --help to inspect valid flags and usage.",...optionalPackageHint?[optionalPackageHint]:[]]}}function dedupeStrings(values){return Array.from(new Set(values))}function firstWhitespaceSeparatedToken(input){let token="";for(const character of input){if(character===" "||character==="	"||character==="\n"||character==="\r"||character==="\f"||character==="\v"){break}token+=character}return token}function trimTrailingPunctuationToken(token){let end=token.length;while(end>0){const character=token[end-1];if(character!==","&&character!==":"&&character!==";"){break}end-=1}return token.slice(0,end)}function resolveChildCommandByToken(parent,token){const normalizedToken=token.trim().toLowerCase();return parent.commands.find(candidate=>{if(candidate.name().trim().toLowerCase()===normalizedToken){return true}const aliases=typeof candidate.aliases==="function"?candidate.aliases():[];return aliases.some(alias=>alias.trim().toLowerCase()===normalizedToken)})}function isKnownHelpCommandPath(root,commandPathTokens){if(commandPathTokens.length===0){return true}let current=root;for(const[tokenIndex,token]of commandPathTokens.entries()){const next=resolveChildCommandByToken(current,token);if(!next){const declaredArguments=current.registeredArguments;return declaredArguments.length>0&&(current.commands.length===0||declaredArguments[0]?.required===true)&&(declaredArguments.at(-1)?.variadic===true||commandPathTokens.length-tokenIndex<=declaredArguments.length)}current=next}return true}async function resolveWorkspaceUsageContext(bootstrapGlobal,message,invocationArgv,commandName){try{const pmRoot=resolvePmRoot(process.cwd(),bootstrapGlobal.path);if(!await pathExists(getSettingsPath(pmRoot))){return{allowedTypes:BUILTIN_TYPE_HELP_VALUES}}const settings=await readSettings(pmRoot);const extensionRegistrations=bootstrapGlobal.noExtensions?void 0:getActiveExtensionRegistrations();const typeRegistry=resolveItemTypeRegistry(settings,extensionRegistrations);let verifiedCollectionItemId;if(/too many arguments/i.test(message)&&["comments","docs","files","learnings","notes","test"].includes(commandName??"")){const commandIndex=invocationArgv.findIndex(token=>token===commandName);const candidate=invocationArgv[commandIndex+2];if(invocationArgv[commandIndex+1]?.toLowerCase()==="add"&&candidate!==void 0&&!candidate.startsWith("-")){try{verifiedCollectionItemId=(await locateItem(pmRoot,candidate,settings.id_prefix,settings.item_format,typeRegistry.type_to_folder))?.id}catch{}}}return{allowedTypes:typeRegistry.types.length>0?typeRegistry.types.join("|"):BUILTIN_TYPE_HELP_VALUES,pmRoot,settings,typeToFolder:typeRegistry.type_to_folder,verifiedCollectionItemId}}catch{return{allowedTypes:BUILTIN_TYPE_HELP_VALUES}}}function resolveUnknownOptionSuggestions(message,commandName){const match=message.match(/unknown option '([^']+)'/i);const suggestions=match&&commandName?dedupeStrings([...getSemanticUnknownOptionSuggestions(commandName,match[1]),...suggestNearestLongFlags(match[1],collectKnownLongFlags(commandName))]):void 0;const otherCommands=match?findOtherCommandsForFlag(match[1],commandName):[];const declaredOnPath=match!==null&&collectKnownLongFlags(commandName).includes(normalizeLongFlag(match[1]));return{match,suggestions,otherCommands,scope:declaredOnPath?"declared_on_path":otherCommands.length>0?"declared_elsewhere":"declared_nowhere"}}function resolveSuggestedRetryForUnknownOption(invocationArgv,unknownOptionMatch,unknownOptionSuggestions){if(!unknownOptionMatch||!unknownOptionSuggestions||unknownOptionSuggestions.length===0){return void 0}const rewritten=rewriteUnknownOptionArgv(invocationArgv,unknownOptionMatch[1],unknownOptionSuggestions[0]);return rewritten?renderAttemptedCommand(rewritten):void 0}function resolveSuggestedRetryForMissingOption(message,invocationArgv){const missingRequiredOption=message.match(/required option '([^']+)' not specified/i);const requiredOptionToken=missingRequiredOption?.[1]?trimTrailingPunctuationToken(firstWhitespaceSeparatedToken(missingRequiredOption[1].trim())):void 0;if(!requiredOptionToken?.startsWith("--")){return void 0}const commandName=parseBootstrapCommandName(invocationArgv);if(!commandName){return void 0}return renderMissingOptionRetry(invocationArgv,commandName,[requiredOptionToken])}function resolveSplitSchemaSubcommand(message,invocationArgv){if(!/too many arguments/i.test(message)){return void 0}if(parseBootstrapCommandName(invocationArgv)!=="schema"){return void 0}const schemaIndex=findBootstrapCommandTokenIndex(invocationArgv);const verb=invocationArgv[schemaIndex+1]?.trim().toLowerCase();const noun=invocationArgv[schemaIndex+2]?.trim().toLowerCase();if(!verb||!noun){return void 0}const joined=`${verb}-${noun}`;if(!SCHEMA_SUBCOMMAND_VALUES.includes(joined)){return void 0}const rewritten=[...invocationArgv.slice(0,schemaIndex+1),joined,...invocationArgv.slice(schemaIndex+3)];return{unknownSubcommandPath:"schema",unknownSubcommandToken:`${verb} ${noun}`,unknownSubcommandAllowedValues:[...SCHEMA_SUBCOMMAND_VALUES],suggestedRetryCommand:renderAttemptedCommand(rewritten)}}async function resolveCommanderUsageContext(error,rootProgram,extensionDescriptors,guidanceOverrides={}){const rawMessage=typeof error==="object"&&error!==null?error.message:void 0;const message=rawMessage??"Invalid command usage";const invocationArgv=normalizeBootstrapInvocation(process.argv.slice(2)).argv;const bootstrapGlobal=parseBootstrapGlobalOptions(invocationArgv);const commandName=parseBootstrapCommandName(invocationArgv);const attemptedCommand=renderAttemptedCommand(invocationArgv);const providedOptionFlags=extractProvidedOptionFlags(invocationArgv);const workspaceUsage=await resolveWorkspaceUsageContext(bootstrapGlobal,message,invocationArgv,commandName);const allowedTypes=workspaceUsage.allowedTypes;const unknownCommandGuidance=buildUnknownCommandGuidanceFromRuntime(message,rootProgram,extensionDescriptors);const unknownOption=resolveUnknownOptionSuggestions(message,commandName);const splitSchemaSubcommand=resolveSplitSchemaSubcommand(message,invocationArgv);const suggestedRetryCommand=splitSchemaSubcommand?.suggestedRetryCommand??resolveSuggestedRetryForUnknownOption(invocationArgv,unknownOption.match,unknownOption.suggestions)??resolveSuggestedRetryForMissingOption(message,invocationArgv);return{message,commandName,allowedTypes,attemptedCommand,normalizedInvocationArgs:[...invocationArgv],providedOptionFlags,unknownOptionSuggestions:unknownOption.suggestions,unknownOptionOtherCommands:unknownOption.otherCommands.length>0?unknownOption.otherCommands.slice(0,12):void 0,unknownOptionOtherCommandsTotal:unknownOption.otherCommands.length>0?unknownOption.otherCommands.length:void 0,unknownOptionOtherCommandsTruncated:unknownOption.otherCommands.length>12||void 0,unknownOptionScope:unknownOption.scope,suggestedRetryCommand,verifiedCollectionItemId:workspaceUsage.verifiedCollectionItemId,...splitSchemaSubcommand,...unknownCommandGuidance,...guidanceOverrides}}async function formatCommanderUsageMessage(error,rootProgram,extensionDescriptors,guidanceOverrides={}){const usageContext=await resolveCommanderUsageContext(error,rootProgram,extensionDescriptors,guidanceOverrides);const{message,commandName,allowedTypes,unknownCommandExamples,unknownCommandNextSteps,attemptedCommand,normalizedInvocationArgs,providedOptionFlags,unknownOptionSuggestions,unknownOptionOtherCommands,unknownOptionOtherCommandsTotal,unknownOptionOtherCommandsTruncated,unknownOptionScope,unknownSubcommandPath,unknownSubcommandToken,unknownSubcommandAllowedValues,suggestedRetryCommand,verifiedCollectionItemId,failedExtensions}=usageContext;const formatted=formatCommanderErrorForDisplay(message,commandName,allowedTypes,{unknownCommandExamples,unknownCommandNextSteps,attemptedCommand,normalizedInvocationArgs,providedOptionFlags,unknownOptionSuggestions,unknownOptionOtherCommands,unknownOptionOtherCommandsTotal,unknownOptionOtherCommandsTruncated,unknownOptionScope,unknownSubcommandPath,unknownSubcommandToken,unknownSubcommandAllowedValues,suggestedRetryCommand,verifiedCollectionItemId,failedExtensions});const serviceOverride=await runActiveServiceOverride("help_format",{message:formatted,command:commandName,allowed_types:allowedTypes});if(serviceOverride.handled&&typeof serviceOverride.result==="string"){return serviceOverride.result}return formatted}async function formatCommanderUsageJson(error,rootProgram,extensionDescriptors,lean=false,guidanceOverrides={}){const usageContext=await resolveCommanderUsageContext(error,rootProgram,extensionDescriptors,guidanceOverrides);const envelope=formatCommanderErrorForJson(usageContext.message,usageContext.commandName,usageContext.allowedTypes,EXIT_CODE.USAGE,{unknownCommandExamples:usageContext.unknownCommandExamples,unknownCommandNextSteps:usageContext.unknownCommandNextSteps,attemptedCommand:usageContext.attemptedCommand,normalizedInvocationArgs:usageContext.normalizedInvocationArgs,providedOptionFlags:usageContext.providedOptionFlags,unknownOptionSuggestions:usageContext.unknownOptionSuggestions,unknownOptionOtherCommands:usageContext.unknownOptionOtherCommands,unknownOptionOtherCommandsTotal:usageContext.unknownOptionOtherCommandsTotal,unknownOptionOtherCommandsTruncated:usageContext.unknownOptionOtherCommandsTruncated,unknownOptionScope:usageContext.unknownOptionScope,unknownSubcommandPath:usageContext.unknownSubcommandPath,unknownSubcommandToken:usageContext.unknownSubcommandToken,unknownSubcommandAllowedValues:usageContext.unknownSubcommandAllowedValues,suggestedRetryCommand:usageContext.suggestedRetryCommand,verifiedCollectionItemId:usageContext.verifiedCollectionItemId,failedExtensions:usageContext.failedExtensions});const projected=lean?projectLeanErrorEnvelope(envelope):envelope;const accountingRequested=parseBootstrapGlobalOptions(usageContext.normalizedInvocationArgs).tokenAccounting===true;return JSON.stringify(accountingRequested?attachOutputTokenAccounting(projected,value=>`${JSON.stringify(value,null,2)}
+`):projected,null,2)}const _testOnly={collectKnownLongFlags,collectInstalledPackageCommandPathHints,resolveOptionalPackageInstallHint,resolveSuggestedRetryForMissingOption,suggestNearestLongFlags};export{BUILTIN_TYPE_HELP_VALUES,_testOnly,appendCommanderExtensionFailures,buildUnknownCommandGuidanceFromRuntime,collectRuntimeCommandPaths,formatCommanderUsageJson,formatCommanderUsageMessage,isKnownHelpCommandPath,resolveChildCommandByToken,resolveCommanderUsageContext,resolveUnknownCommanderToken,scoreCommandPathMatch};
 //# sourceMappingURL=commander-usage.js.map
-//# debugId=18758585-648f-5422-80e4-fbc7478c3cf3