@unbrained/pm-cli 2026.9.6 → 2026.9.8

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

@@ -1,637 +1,6 @@
-/**
- * @module cli/extension-command-help
- *
- * Provides CLI runtime support for Extension Command Help.
- */
-
-!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]="99d39b7c-ec26-5c95-85c0-ac28112a6fe6")}catch(e){}}();
-import { Option } from "commander";
-/** Implements normalize extension command path for the public runtime surface of this module. */
-export function normalizeExtensionCommandPath(commandPath) {
-    return commandPath
-        .trim()
-        .toLowerCase()
-        .split(/\s+/)
-        .filter((part) => part.length > 0)
-        .join(" ");
-}
-/** Build verified flattened-alias mappings within one extension and layer. */
-export function buildCanonicalExtensionAliases(handlers, definitions) {
-    const aliases = new Map();
-    for (const handler of handlers) {
-        const alias = normalizeExtensionCommandPath(handler.command);
-        for (const definition of definitions) {
-            if (definition.layer !== handler.layer ||
-                definition.name !== handler.name) {
-                continue;
-            }
-            const canonical = normalizeExtensionCommandPath(definition.command);
-            const parts = canonical.split(" ");
-            const action = parts.at(-1);
-            const suffix = parts.slice(1).join(" ");
-            const expectedAlias = suffix
-                ? `${parts[0]}-${action} ${suffix}`
-                : `${parts[0]}-${action}`;
-            if (action &&
-                alias === expectedAlias) {
-                aliases.set(alias, canonical);
-                break;
-            }
-        }
-    }
-    return aliases;
-}
-/** Resolve whether a registered extension flag consumes a value. */
-export function extensionFlagTakesValueForInvocation(invocationArgv, commandName, normalizedMissing, descriptors) {
-    if (!commandName || !normalizedMissing) {
-        return undefined;
-    }
-    let descriptor;
-    let matchedTokenCount = 0;
-    for (const [index, token] of invocationArgv.entries()) {
-        if (token !== commandName) {
-            continue;
-        }
-        const commandTokens = invocationArgv.slice(index);
-        for (const [path, candidate] of descriptors.entries()) {
-            const pathTokens = path.split(" ");
-            if (pathTokens.length > matchedTokenCount &&
-                pathTokens.every((pathToken, pathIndex) => commandTokens[pathIndex] === pathToken)) {
-                descriptor = candidate;
-                matchedTokenCount = pathTokens.length;
-            }
-        }
-    }
-    const flag = descriptor?.flags.find((candidate) => candidate.long === normalizedMissing ||
-        candidate.short === normalizedMissing);
-    if (!flag) {
-        return undefined;
-    }
-    return resolveExtensionFlagArity(flag).takesValue;
-}
-function toNonEmptyFlagString(value) {
-    if (typeof value !== "string") {
-        return null;
-    }
-    const trimmed = value.trim();
-    return trimmed.length > 0 ? trimmed : null;
-}
-function toOptionalBoolean(value) {
-    return typeof value === "boolean" ? value : undefined;
-}
-/** Canonical value-arity contract shared by extension invocation recovery, Commander parsing, and structured help. */
-export function resolveExtensionFlagArity(definition) {
-    const valueType = toNonEmptyFlagString(definition.value_type) ??
-        toNonEmptyFlagString(definition.type);
-    const declaredValueName = toNonEmptyFlagString(definition.value_name);
-    const takesValue = valueType !== "boolean" &&
-        (declaredValueName !== null ||
-            valueType !== null ||
-            toOptionalBoolean(definition.required) === true ||
-            toOptionalBoolean(definition.list) === true);
-    return {
-        takesValue,
-        valueName: takesValue ? (declaredValueName ?? "value") : null,
-    };
-}
-function formatDynamicExtensionFlagHelpLine(definition) {
-    const visible = toOptionalBoolean(definition.visible);
-    if (visible === false) {
-        return null;
-    }
-    const longName = toNonEmptyFlagString(definition.long);
-    if (!longName || !longName.startsWith("--") || longName.length < 3) {
-        return null;
-    }
-    const shortName = toNonEmptyFlagString(definition.short);
-    const shortPrefix = shortName && shortName.startsWith("-") && !shortName.startsWith("--")
-        ? `${shortName}, `
-        : "";
-    const valueName = toNonEmptyFlagString(definition.value_name);
-    const valueSuffix = valueName ? ` <${valueName}>` : "";
-    const description = toNonEmptyFlagString(definition.description) ??
-        "Extension-provided option.";
-    const markers = [];
-    if (toOptionalBoolean(definition.required) === true) {
-        markers.push("required");
-    }
-    if (toOptionalBoolean(definition.enabled) === false) {
-        markers.push("disabled");
-    }
-    const markerSuffix = markers.length > 0 ? ` [${markers.join(", ")}]` : "";
-    return `${shortPrefix}${longName}${valueSuffix}  ${description}${markerSuffix}`;
-}
-function buildDynamicExtensionFlagHelp(definitions) {
-    const lines = [
-        ...new Set(definitions
-            .map(formatDynamicExtensionFlagHelpLine)
-            .filter((line) => line !== null)),
-    ].sort((left, right) => left.localeCompare(right));
-    if (lines.length === 0) {
-        return null;
-    }
-    return `\nExtension-provided flags:\n  ${lines.join("\n  ")}`;
-}
-/** Implements collect dynamic extension flag help by command for the public runtime surface of this module. */
-export function collectDynamicExtensionFlagHelpByCommand(registrations) {
-    const grouped = new Map();
-    for (const registration of registrations) {
-        const commandPath = normalizeExtensionCommandPath(registration.target_command);
-        if (commandPath.length === 0) {
-            continue;
-        }
-        const existing = grouped.get(commandPath) ?? [];
-        existing.push(...registration.flags);
-        grouped.set(commandPath, existing);
-    }
-    const entries = [...grouped.entries()].sort(([left], [right]) => left.localeCompare(right));
-    const helpByCommand = new Map();
-    for (const [commandPath, definitions] of entries) {
-        const helpText = buildDynamicExtensionFlagHelp(definitions);
-        if (!helpText) {
-            continue;
-        }
-        helpByCommand.set(commandPath, helpText);
-    }
-    return helpByCommand;
-}
-function normalizeExtensionCommandAction(commandPath, action) {
-    if (typeof action !== "string" || action.trim().length === 0) {
-        return commandPath.replace(/\s+/g, "-");
-    }
-    return action.trim().toLowerCase();
-}
-function normalizeExtensionCommandStringList(values) {
-    if (!Array.isArray(values)) {
-        return [];
-    }
-    const normalized = [];
-    const seen = new Set();
-    for (const value of values) {
-        if (typeof value !== "string") {
-            continue;
-        }
-        const trimmed = value.trim();
-        if (trimmed.length === 0 || seen.has(trimmed)) {
-            continue;
-        }
-        seen.add(trimmed);
-        normalized.push(trimmed);
-    }
-    return normalized;
-}
-function normalizeExtensionCommandArguments(values) {
-    if (!Array.isArray(values)) {
-        return [];
-    }
-    return values
-        .map((value) => {
-        const name = typeof value.name === "string" ? value.name.trim() : "";
-        if (name.length === 0) {
-            return null;
-        }
-        const normalized = {
-            name,
-            required: value.required === true,
-            variadic: value.variadic === true,
-        };
-        if (typeof value.description === "string" &&
-            value.description.trim().length > 0) {
-            normalized.description = value.description.trim();
-        }
-        return normalized;
-    })
-        .filter((entry) => entry !== null);
-}
-function collectExtensionDefinitionsByCommand(commandDefinitions) {
-    const definitionsByCommand = new Map();
-    for (const definition of commandDefinitions) {
-        const commandPath = normalizeExtensionCommandPath(definition.command);
-        if (commandPath.length === 0) {
-            continue;
-        }
-        const description = typeof definition.description === "string" &&
-            definition.description.trim().length > 0
-            ? definition.description.trim()
-            : undefined;
-        const intent = typeof definition.intent === "string" &&
-            definition.intent.trim().length > 0
-            ? definition.intent.trim()
-            : undefined;
-        definitionsByCommand.set(commandPath, {
-            command: commandPath,
-            action: normalizeExtensionCommandAction(commandPath, definition.action),
-            description,
-            intent,
-            examples: normalizeExtensionCommandStringList(definition.examples),
-            failure_hints: normalizeExtensionCommandStringList(definition.failure_hints),
-            arguments: normalizeExtensionCommandArguments(definition.arguments),
-            flags: [],
-            tier: definition.tier ?? "standard",
-            family: definition.family ?? "extensions",
-            source: {
-                layer: definition.layer,
-                name: definition.name,
-                package: definition.source_package,
-            },
-        });
-    }
-    return definitionsByCommand;
-}
-function collectExtensionFlagsByCommand(flagRegistrations) {
-    const flagsByCommand = new Map();
-    for (const registration of flagRegistrations) {
-        const commandPath = normalizeExtensionCommandPath(registration.target_command);
-        if (commandPath.length === 0) {
-            continue;
-        }
-        const existing = flagsByCommand.get(commandPath) ?? [];
-        existing.push(...registration.flags);
-        flagsByCommand.set(commandPath, existing);
-    }
-    return flagsByCommand;
-}
-function collectExtensionHelpCommandSet(commandHandlers, definitionsByCommand, flagsByCommand) {
-    const commandSet = new Set();
-    for (const commandPath of commandHandlers) {
-        const normalized = normalizeExtensionCommandPath(commandPath);
-        if (normalized.length > 0) {
-            commandSet.add(normalized);
-        }
-    }
-    for (const commandPath of definitionsByCommand.keys()) {
-        commandSet.add(commandPath);
-    }
-    for (const commandPath of flagsByCommand.keys()) {
-        commandSet.add(commandPath);
-    }
-    return commandSet;
-}
-/** Resolve the canonical nested command behind an auto-generated flattened
- * extension alias such as `csv-export export` -> `csv export`. Package authors
- * should not have to duplicate command metadata merely because a compatibility
- * alias was registered by the host package. */
-function resolveFlattenedAliasDescriptor(commandPath, definitionsByCommand, canonicalAliases) {
-    const canonical = canonicalAliases.get(commandPath);
-    return canonical ? definitionsByCommand.get(canonical) : undefined;
-}
-/** Implements collect extension command help descriptors for the public runtime surface of this module. */
-export function collectExtensionCommandHelpDescriptors(commandHandlers, commandDefinitions, flagRegistrations, canonicalAliases = new Map()) {
-    const definitionsByCommand = collectExtensionDefinitionsByCommand(commandDefinitions);
-    const flagsByCommand = collectExtensionFlagsByCommand(flagRegistrations);
-    const commandSet = collectExtensionHelpCommandSet(commandHandlers, definitionsByCommand, flagsByCommand);
-    const descriptors = new Map();
-    const sortedCommands = [...commandSet].sort((left, right) => left.localeCompare(right));
-    for (const commandPath of sortedCommands) {
-        const definition = resolveFlattenedAliasDescriptor(commandPath, definitionsByCommand, canonicalAliases) ?? definitionsByCommand.get(commandPath);
-        const flags = flagsByCommand.get(commandPath) ??
-            (definition ? flagsByCommand.get(definition.command) : undefined) ??
-            [];
-        if (definition) {
-            descriptors.set(commandPath, {
-                ...definition,
-                command: commandPath,
-                flags,
-            });
-            continue;
-        }
-        descriptors.set(commandPath, {
-            command: commandPath,
-            action: normalizeExtensionCommandAction(commandPath, undefined),
-            examples: [],
-            failure_hints: [],
-            arguments: [],
-            flags,
-            tier: "standard",
-            family: "extensions",
-        });
-    }
-    return descriptors;
-}
-function buildExtensionArgumentToken(argument) {
-    const variadicSuffix = argument.variadic ? "..." : "";
-    if (argument.required) {
-        return `<${argument.name}${variadicSuffix}>`;
-    }
-    return `[${argument.name}${variadicSuffix}]`;
-}
-/** Implements apply dynamic extension arguments for the public runtime surface of this module. */
-export function applyDynamicExtensionArguments(command, descriptor) {
-    for (const argument of descriptor.arguments) {
-        command.argument(buildExtensionArgumentToken(argument), argument.description ?? "Extension argument.");
-    }
-}
-function normalizeDynamicExtensionOptionNames(definition) {
-    const visible = toOptionalBoolean(definition.visible);
-    if (visible === false) {
-        return null;
-    }
-    const longName = toNonEmptyFlagString(definition.long);
-    const shortName = toNonEmptyFlagString(definition.short);
-    const normalizedShort = shortName && shortName.startsWith("-") && !shortName.startsWith("--")
-        ? shortName
-        : null;
-    const normalizedLong = longName && longName.startsWith("--") && longName.length > 2
-        ? longName
-        : null;
-    const optionNames = [normalizedShort, normalizedLong].filter((entry) => entry !== null);
-    return optionNames.length > 0 ? optionNames : null;
-}
-function formatDynamicExtensionOptionFlags(definition) {
-    const optionNames = normalizeDynamicExtensionOptionNames(definition);
-    if (!optionNames) {
-        return null;
-    }
-    const { valueName } = resolveExtensionFlagArity(definition);
-    const optionValueSuffix = valueName ? ` <${valueName}>` : "";
-    return `${optionNames.join(", ")}${optionValueSuffix}`;
-}
-function formatDynamicExtensionParseOptionFlags(definition) {
-    const optionNames = normalizeDynamicExtensionOptionNames(definition);
-    if (!optionNames) {
-        return null;
-    }
-    const { valueName } = resolveExtensionFlagArity(definition);
-    const valueSuffix = valueName ? ` <${valueName}>` : "";
-    return `${optionNames.join(", ")}${valueSuffix}`;
-}
-function formatDynamicExtensionOptionDescription(definition) {
-    const description = toNonEmptyFlagString(definition.description) ??
-        "Extension-provided option.";
-    const markers = [];
-    if (toOptionalBoolean(definition.required) === true) {
-        markers.push("required");
-    }
-    if (toOptionalBoolean(definition.enabled) === false) {
-        markers.push("disabled");
-    }
-    const markerSuffix = markers.length > 0 ? ` [${markers.join(", ")}]` : "";
-    return `${description}${markerSuffix}`;
-}
-function commandAlreadyHasOption(command, definition) {
-    const longName = toNonEmptyFlagString(definition.long);
-    const shortName = toNonEmptyFlagString(definition.short);
-    return command.options.some((option) => {
-        const optionWithNames = option;
-        return ((longName !== null && optionWithNames.long === longName) ||
-            (shortName !== null && optionWithNames.short === shortName));
-    });
-}
-/** Implements apply dynamic extension flag options for the public runtime surface of this module. */
-export function applyDynamicExtensionFlagOptions(command, definitions) {
-    for (const definition of definitions) {
-        if (commandAlreadyHasOption(command, definition)) {
-            continue;
-        }
-        const flags = formatDynamicExtensionParseOptionFlags(definition);
-        if (!flags) {
-            continue;
-        }
-        const description = formatDynamicExtensionOptionDescription(definition);
-        if (definition.list !== true) {
-            command.option(flags, description);
-            continue;
-        }
-        command.addOption(new Option(flags, description).argParser((value, previous = []) => [
-            ...(Array.isArray(previous) ? previous : [previous]),
-            value,
-        ]));
-    }
-}
-/**
- * Builds the "Extension-provided flags" help block for only the definitions that
- * are NOT already rendered as real commander options on {@link command}. After
- * {@link applyDynamicExtensionFlagOptions} registers extension flags as first
- * class options, repeating them verbatim in an after-text block duplicated every
- * flag in `--help` output; this filters those already-listed flags out so the
- * block is emitted only when it carries flags the Options section does not.
- */
-export function buildResidualDynamicExtensionFlagHelp(command, definitions) {
-    return buildDynamicExtensionFlagHelp(definitions.filter((definition) => !commandAlreadyHasOption(command, definition)));
-}
-function buildDynamicExtensionHelpOptionSummary(definition) {
-    const flags = formatDynamicExtensionOptionFlags(definition);
-    if (!flags) {
-        return null;
-    }
-    const longName = toNonEmptyFlagString(definition.long);
-    const shortName = toNonEmptyFlagString(definition.short);
-    const normalizedLong = longName && longName.startsWith("--") && longName.length > 2
-        ? longName
-        : null;
-    const normalizedShort = shortName && shortName.startsWith("-") && !shortName.startsWith("--")
-        ? shortName
-        : null;
-    const { takesValue, valueName } = resolveExtensionFlagArity(definition);
-    const required = toOptionalBoolean(definition.required) === true;
-    return {
-        flags,
-        long: normalizedLong,
-        short: normalizedShort,
-        description: formatDynamicExtensionOptionDescription(definition),
-        takes_value: takesValue,
-        value_required: takesValue,
-        value_name: valueName,
-        variadic: false,
-        required,
-        aliases: [],
-        alias_for: null,
-    };
-}
-/** Implements build dynamic extension help option summaries for the public runtime surface of this module. */
-export function buildDynamicExtensionHelpOptionSummaries(descriptor) {
-    if (!descriptor) {
-        return [];
-    }
-    const summaries = [];
-    const seen = new Set();
-    for (const definition of descriptor.flags) {
-        const summary = buildDynamicExtensionHelpOptionSummary(definition);
-        if (!summary || seen.has(summary.flags)) {
-            continue;
-        }
-        seen.add(summary.flags);
-        summaries.push(summary);
-    }
-    return summaries;
-}
-/** Implements merge help option summaries for the public runtime surface of this module. */
-export function mergeHelpOptionSummaries(base, extension) {
-    if (extension.length === 0) {
-        return base;
-    }
-    const merged = [...base];
-    const seen = new Set(base.map((entry) => entry.flags));
-    for (const entry of extension) {
-        if (seen.has(entry.flags)) {
-            continue;
-        }
-        seen.add(entry.flags);
-        merged.push(entry);
-    }
-    return merged;
-}
-/** Implements build dynamic extension command metadata help for the public runtime surface of this module. */
-export function buildDynamicExtensionCommandMetadataHelp(descriptor) {
-    const lines = [];
-    if (descriptor.intent) {
-        lines.push(`Intent: ${descriptor.intent}`);
-    }
-    if (descriptor.action) {
-        lines.push(`Action contract: ${descriptor.action}`);
-    }
-    if (descriptor.examples.length > 0) {
-        lines.push("Examples:");
-        for (const example of descriptor.examples) {
-            lines.push(`  - ${example}`);
-        }
-    }
-    if (descriptor.failure_hints.length > 0) {
-        lines.push("Common failure hints:");
-        for (const hint of descriptor.failure_hints) {
-            lines.push(`  - ${hint}`);
-        }
-    }
-    if (lines.length === 0) {
-        return null;
-    }
-    return `\nExtension command metadata:\n  ${lines.join("\n  ")}`;
-}
-/** Implements command aliases for the public runtime surface of this module. */
-export function commandAliases(command) {
-    const commandRecord = command;
-    if (typeof commandRecord.aliases === "function") {
-        return commandRecord
-            .aliases()
-            .map((value) => value.trim().toLowerCase())
-            .filter((value) => value.length > 0);
-    }
-    if (typeof commandRecord.alias === "function") {
-        const alias = commandRecord.alias();
-        if (typeof alias === "string" && alias.trim().length > 0) {
-            return [alias.trim().toLowerCase()];
-        }
-    }
-    if (Array.isArray(commandRecord._aliases)) {
-        return commandRecord._aliases
-            .map((value) => value.trim().toLowerCase())
-            .filter((value) => value.length > 0);
-    }
-    return [];
-}
-/** Implements find direct child command for the public runtime surface of this module. */
-export function findDirectChildCommand(parent, name) {
-    const normalizedTarget = name.trim().toLowerCase();
-    return (parent.commands.find((entry) => {
-        if (entry.name().trim().toLowerCase() === normalizedTarget) {
-            return true;
-        }
-        return commandAliases(entry).includes(normalizedTarget);
-    }) ?? null);
-}
-/** Implements find command by path for the public runtime surface of this module. */
-export function findCommandByPath(root, pathParts) {
-    let current = root;
-    for (const part of pathParts) {
-        const next = findDirectChildCommand(current, part);
-        if (!next) {
-            return null;
-        }
-        current = next;
-    }
-    return current;
-}
-const extensionCreatedCommands = new WeakSet();
-/** Implements ensure command path for the public runtime surface of this module. */
-export function ensureCommandPath(root, pathParts) {
-    if (pathParts.length === 0) {
-        return null;
-    }
-    let current = root;
-    for (let index = 0; index < pathParts.length; index += 1) {
-        const part = pathParts[index];
-        const existing = findDirectChildCommand(current, part);
-        if (existing) {
-            current = existing;
-            continue;
-        }
-        const created = current.command(part);
-        extensionCreatedCommands.add(created);
-        if (index < pathParts.length - 1) {
-            created.description("Extension-provided command group.");
-            // Without a handler, commander routes bare-group help through the error
-            // channel, which the root configureOutput intentionally swallows — the
-            // group would exit 0 in silence. Render help on stdout instead so agents
-            // always get subcommand discovery. A later terminal registration for the
-            // same path replaces this handler via Command.action().
-            created.action(() => {
-                created.help();
-            });
-        }
-        else {
-            created.description("Extension-provided command path.");
-        }
-        current = created;
-    }
-    return current;
-}
-/** Describe the first core-owned command prefix that an extension path would shadow or graft beneath. */
-export function findExtensionCommandPathCollision(root, pathParts) {
-    let current = root;
-    const traversed = [];
-    for (const part of pathParts) {
-        const existing = findDirectChildCommand(current, part);
-        if (!existing) {
-            return null;
-        }
-        traversed.push(part);
-        if (!extensionCreatedCommands.has(existing)) {
-            return {
-                core_path: traversed.join(" "),
-                extension_path: pathParts.join(" "),
-            };
-        }
-        current = existing;
-    }
-    return null;
-}
-/** Build an ownership-rich warning when an extension alias would shadow or graft beneath a core command. */
-export function buildExtensionCommandCollisionWarning(root, commandPath, aliases, descriptor) {
-    const pathParts = commandPath.split(" ").filter((part) => part.length > 0);
-    const collision = findExtensionCommandPathCollision(root, pathParts);
-    // Direct canonical paths intentionally augment core help with extension flags
-    // and metadata while registerCommandPath preserves the core action handler.
-    // Canonical aliases and nested grafts cannot make that ownership distinction,
-    // so those paths are rejected instead.
-    if (!collision ||
-        (collision.core_path === commandPath && !aliases.has(commandPath))) {
-        return null;
-    }
-    const extensionOwner = descriptor?.source?.package ??
-        descriptor?.source?.name ??
-        "unknown-extension";
-    return (`extension_command_collision:${collision.extension_path}:` +
-        `core_owner=pm-cli:${collision.core_path}:extension_owner=${extensionOwner}`);
-}
-/** Collect deterministic extension command paths while reporting and excluding aliases that collide with core ownership. */
-export function collectSafeExtensionCommandPaths(root, commandHandlers, descriptors, aliases, onCollision) {
-    return [
-        ...new Set([...commandHandlers, ...descriptors.keys()]),
-    ]
-        .filter((commandPath) => commandPath.trim().length > 0)
-        .sort((left, right) => left.localeCompare(right))
-        .filter((commandPath) => {
-        const warning = buildExtensionCommandCollisionWarning(root, commandPath, aliases, descriptors.get(commandPath));
-        if (!warning)
-            return true;
-        onCollision(warning);
-        return false;
-    });
-}
-/** Record and surface one extension collision with stable recovery guidance. */
-export function reportExtensionCommandCollision(activationWarnings, report, warning) {
-    activationWarnings.push(warning);
-    report(`[pm] warning: ${warning}; core command preserved. Rename or namespace the extension command alias.`);
-}
+!(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]="3c82c125-73b7-5f75-bc3c-3d83d4b7d7f8")}catch(e2){}})();import{Option}from"commander";function normalizeExtensionCommandPath(commandPath){return commandPath.trim().toLowerCase().split(/\s+/).filter(part=>part.length>0).join(" ")}function buildCanonicalExtensionAliases(handlers,definitions){const aliases=new Map;for(const handler of handlers){const alias=normalizeExtensionCommandPath(handler.command);for(const definition of definitions){if(definition.layer!==handler.layer||definition.name!==handler.name){continue}const canonical=normalizeExtensionCommandPath(definition.command);const parts=canonical.split(" ");const action=parts.at(-1);const suffix=parts.slice(1).join(" ");const expectedAlias=suffix?`${parts[0]}-${action} ${suffix}`:`${parts[0]}-${action}`;if(action&&alias===expectedAlias){aliases.set(alias,canonical);break}}}return aliases}function extensionFlagTakesValueForInvocation(invocationArgv,commandName,normalizedMissing,descriptors){if(!commandName||!normalizedMissing){return void 0}let descriptor;let matchedTokenCount=0;for(const[index,token]of invocationArgv.entries()){if(token!==commandName){continue}const commandTokens=invocationArgv.slice(index);for(const[path,candidate]of descriptors.entries()){const pathTokens=path.split(" ");if(pathTokens.length>matchedTokenCount&&pathTokens.every((pathToken,pathIndex)=>commandTokens[pathIndex]===pathToken)){descriptor=candidate;matchedTokenCount=pathTokens.length}}}const flag=descriptor?.flags.find(candidate=>candidate.long===normalizedMissing||candidate.short===normalizedMissing);if(!flag){return void 0}return resolveExtensionFlagArity(flag).takesValue}function toNonEmptyFlagString(value){if(typeof value!=="string"){return null}const trimmed=value.trim();return trimmed.length>0?trimmed:null}function toOptionalBoolean(value){return typeof value==="boolean"?value:void 0}function resolveExtensionFlagArity(definition){const valueType=toNonEmptyFlagString(definition.value_type)??toNonEmptyFlagString(definition.type);const declaredValueName=toNonEmptyFlagString(definition.value_name);const takesValue=valueType!=="boolean"&&(declaredValueName!==null||valueType!==null||toOptionalBoolean(definition.required)===true||toOptionalBoolean(definition.list)===true);return{takesValue,valueName:takesValue?declaredValueName??"value":null}}function formatDynamicExtensionFlagHelpLine(definition){const visible=toOptionalBoolean(definition.visible);if(visible===false){return null}const longName=toNonEmptyFlagString(definition.long);if(!longName||!longName.startsWith("--")||longName.length<3){return null}const shortName=toNonEmptyFlagString(definition.short);const shortPrefix=shortName&&shortName.startsWith("-")&&!shortName.startsWith("--")?`${shortName}, `:"";const valueName=toNonEmptyFlagString(definition.value_name);const valueSuffix=valueName?` <${valueName}>`:"";const description=toNonEmptyFlagString(definition.description)??"Extension-provided option.";const markers=[];if(toOptionalBoolean(definition.required)===true){markers.push("required")}if(toOptionalBoolean(definition.enabled)===false){markers.push("disabled")}const markerSuffix=markers.length>0?` [${markers.join(", ")}]`:"";return`${shortPrefix}${longName}${valueSuffix}  ${description}${markerSuffix}`}function buildDynamicExtensionFlagHelp(definitions){const lines=[...new Set(definitions.map(formatDynamicExtensionFlagHelpLine).filter(line=>line!==null))].sort((left,right)=>left.localeCompare(right));if(lines.length===0){return null}return`
+Extension-provided flags:
+  ${lines.join("\n  ")}`}function collectDynamicExtensionFlagHelpByCommand(registrations){const grouped=new Map;for(const registration of registrations){const commandPath=normalizeExtensionCommandPath(registration.target_command);if(commandPath.length===0){continue}const existing=grouped.get(commandPath)??[];existing.push(...registration.flags);grouped.set(commandPath,existing)}const entries=[...grouped.entries()].sort(([left],[right])=>left.localeCompare(right));const helpByCommand=new Map;for(const[commandPath,definitions]of entries){const helpText=buildDynamicExtensionFlagHelp(definitions);if(!helpText){continue}helpByCommand.set(commandPath,helpText)}return helpByCommand}function normalizeExtensionCommandAction(commandPath,action){if(typeof action!=="string"||action.trim().length===0){return commandPath.replace(/\s+/g,"-")}return action.trim().toLowerCase()}function normalizeExtensionCommandStringList(values){if(!Array.isArray(values)){return[]}const normalized=[];const seen=new Set;for(const value of values){if(typeof value!=="string"){continue}const trimmed=value.trim();if(trimmed.length===0||seen.has(trimmed)){continue}seen.add(trimmed);normalized.push(trimmed)}return normalized}function normalizeExtensionCommandArguments(values){if(!Array.isArray(values)){return[]}return values.map(value=>{const name=typeof value.name==="string"?value.name.trim():"";if(name.length===0){return null}const normalized={name,required:value.required===true,variadic:value.variadic===true};if(typeof value.description==="string"&&value.description.trim().length>0){normalized.description=value.description.trim()}return normalized}).filter(entry=>entry!==null)}function collectExtensionDefinitionsByCommand(commandDefinitions){const definitionsByCommand=new Map;for(const definition of commandDefinitions){const commandPath=normalizeExtensionCommandPath(definition.command);if(commandPath.length===0){continue}const description=typeof definition.description==="string"&&definition.description.trim().length>0?definition.description.trim():void 0;const intent=typeof definition.intent==="string"&&definition.intent.trim().length>0?definition.intent.trim():void 0;definitionsByCommand.set(commandPath,{command:commandPath,action:normalizeExtensionCommandAction(commandPath,definition.action),description,intent,examples:normalizeExtensionCommandStringList(definition.examples),failure_hints:normalizeExtensionCommandStringList(definition.failure_hints),arguments:normalizeExtensionCommandArguments(definition.arguments),flags:[],tier:definition.tier??"standard",family:definition.family??"extensions",source:{layer:definition.layer,name:definition.name,package:definition.source_package}})}return definitionsByCommand}function collectExtensionFlagsByCommand(flagRegistrations){const flagsByCommand=new Map;for(const registration of flagRegistrations){const commandPath=normalizeExtensionCommandPath(registration.target_command);if(commandPath.length===0){continue}const existing=flagsByCommand.get(commandPath)??[];existing.push(...registration.flags);flagsByCommand.set(commandPath,existing)}return flagsByCommand}function collectExtensionHelpCommandSet(commandHandlers,definitionsByCommand,flagsByCommand){const commandSet=new Set;for(const commandPath of commandHandlers){const normalized=normalizeExtensionCommandPath(commandPath);if(normalized.length>0){commandSet.add(normalized)}}for(const commandPath of definitionsByCommand.keys()){commandSet.add(commandPath)}for(const commandPath of flagsByCommand.keys()){commandSet.add(commandPath)}return commandSet}function resolveFlattenedAliasDescriptor(commandPath,definitionsByCommand,canonicalAliases){const canonical=canonicalAliases.get(commandPath);return canonical?definitionsByCommand.get(canonical):void 0}function collectExtensionCommandHelpDescriptors(commandHandlers,commandDefinitions,flagRegistrations,canonicalAliases=new Map){const definitionsByCommand=collectExtensionDefinitionsByCommand(commandDefinitions);const flagsByCommand=collectExtensionFlagsByCommand(flagRegistrations);const commandSet=collectExtensionHelpCommandSet(commandHandlers,definitionsByCommand,flagsByCommand);const descriptors=new Map;const sortedCommands=[...commandSet].sort((left,right)=>left.localeCompare(right));for(const commandPath of sortedCommands){const definition=resolveFlattenedAliasDescriptor(commandPath,definitionsByCommand,canonicalAliases)??definitionsByCommand.get(commandPath);const flags=flagsByCommand.get(commandPath)??(definition?flagsByCommand.get(definition.command):void 0)??[];if(definition){descriptors.set(commandPath,{...definition,command:commandPath,flags});continue}descriptors.set(commandPath,{command:commandPath,action:normalizeExtensionCommandAction(commandPath,void 0),examples:[],failure_hints:[],arguments:[],flags,tier:"standard",family:"extensions"})}return descriptors}function buildExtensionArgumentToken(argument){const variadicSuffix=argument.variadic?"...":"";if(argument.required){return`<${argument.name}${variadicSuffix}>`}return`[${argument.name}${variadicSuffix}]`}function applyDynamicExtensionArguments(command,descriptor){for(const argument of descriptor.arguments){command.argument(buildExtensionArgumentToken(argument),argument.description??"Extension argument.")}}function normalizeDynamicExtensionOptionNames(definition){const visible=toOptionalBoolean(definition.visible);if(visible===false){return null}const longName=toNonEmptyFlagString(definition.long);const shortName=toNonEmptyFlagString(definition.short);const normalizedShort=shortName&&shortName.startsWith("-")&&!shortName.startsWith("--")?shortName:null;const normalizedLong=longName&&longName.startsWith("--")&&longName.length>2?longName:null;const optionNames=[normalizedShort,normalizedLong].filter(entry=>entry!==null);return optionNames.length>0?optionNames:null}function formatDynamicExtensionOptionFlags(definition){const optionNames=normalizeDynamicExtensionOptionNames(definition);if(!optionNames){return null}const{valueName}=resolveExtensionFlagArity(definition);const optionValueSuffix=valueName?` <${valueName}>`:"";return`${optionNames.join(", ")}${optionValueSuffix}`}function formatDynamicExtensionParseOptionFlags(definition){const optionNames=normalizeDynamicExtensionOptionNames(definition);if(!optionNames){return null}const{valueName}=resolveExtensionFlagArity(definition);const valueSuffix=valueName?` <${valueName}>`:"";return`${optionNames.join(", ")}${valueSuffix}`}function formatDynamicExtensionOptionDescription(definition){const description=toNonEmptyFlagString(definition.description)??"Extension-provided option.";const markers=[];if(toOptionalBoolean(definition.required)===true){markers.push("required")}if(toOptionalBoolean(definition.enabled)===false){markers.push("disabled")}const markerSuffix=markers.length>0?` [${markers.join(", ")}]`:"";return`${description}${markerSuffix}`}function commandAlreadyHasOption(command,definition){const longName=toNonEmptyFlagString(definition.long);const shortName=toNonEmptyFlagString(definition.short);return command.options.some(option=>{const optionWithNames=option;return longName!==null&&optionWithNames.long===longName||shortName!==null&&optionWithNames.short===shortName})}function applyDynamicExtensionFlagOptions(command,definitions){for(const definition of definitions){if(commandAlreadyHasOption(command,definition)){continue}const flags=formatDynamicExtensionParseOptionFlags(definition);if(!flags){continue}const description=formatDynamicExtensionOptionDescription(definition);if(definition.list!==true){command.option(flags,description);continue}command.addOption(new Option(flags,description).argParser((value,previous=[])=>[...Array.isArray(previous)?previous:[previous],value]))}}function buildResidualDynamicExtensionFlagHelp(command,definitions){return buildDynamicExtensionFlagHelp(definitions.filter(definition=>!commandAlreadyHasOption(command,definition)))}function buildDynamicExtensionHelpOptionSummary(definition){const flags=formatDynamicExtensionOptionFlags(definition);if(!flags){return null}const longName=toNonEmptyFlagString(definition.long);const shortName=toNonEmptyFlagString(definition.short);const normalizedLong=longName&&longName.startsWith("--")&&longName.length>2?longName:null;const normalizedShort=shortName&&shortName.startsWith("-")&&!shortName.startsWith("--")?shortName:null;const{takesValue,valueName}=resolveExtensionFlagArity(definition);const required=toOptionalBoolean(definition.required)===true;return{flags,long:normalizedLong,short:normalizedShort,description:formatDynamicExtensionOptionDescription(definition),takes_value:takesValue,value_required:takesValue,value_name:valueName,variadic:false,required,aliases:[],alias_for:null}}function buildDynamicExtensionHelpOptionSummaries(descriptor){if(!descriptor){return[]}const summaries=[];const seen=new Set;for(const definition of descriptor.flags){const summary=buildDynamicExtensionHelpOptionSummary(definition);if(!summary||seen.has(summary.flags)){continue}seen.add(summary.flags);summaries.push(summary)}return summaries}function mergeHelpOptionSummaries(base,extension){if(extension.length===0){return base}const merged=[...base];const seen=new Set(base.map(entry=>entry.flags));for(const entry of extension){if(seen.has(entry.flags)){continue}seen.add(entry.flags);merged.push(entry)}return merged}function buildDynamicExtensionCommandMetadataHelp(descriptor){const lines=[];if(descriptor.intent){lines.push(`Intent: ${descriptor.intent}`)}if(descriptor.action){lines.push(`Action contract: ${descriptor.action}`)}if(descriptor.examples.length>0){lines.push("Examples:");for(const example of descriptor.examples){lines.push(`  - ${example}`)}}if(descriptor.failure_hints.length>0){lines.push("Common failure hints:");for(const hint of descriptor.failure_hints){lines.push(`  - ${hint}`)}}if(lines.length===0){return null}return`
+Extension command metadata:
+  ${lines.join("\n  ")}`}function commandAliases(command){const commandRecord=command;if(typeof commandRecord.aliases==="function"){return commandRecord.aliases().map(value=>value.trim().toLowerCase()).filter(value=>value.length>0)}if(typeof commandRecord.alias==="function"){const alias=commandRecord.alias();if(typeof alias==="string"&&alias.trim().length>0){return[alias.trim().toLowerCase()]}}if(Array.isArray(commandRecord._aliases)){return commandRecord._aliases.map(value=>value.trim().toLowerCase()).filter(value=>value.length>0)}return[]}function findDirectChildCommand(parent,name){const normalizedTarget=name.trim().toLowerCase();return parent.commands.find(entry=>{if(entry.name().trim().toLowerCase()===normalizedTarget){return true}return commandAliases(entry).includes(normalizedTarget)})??null}function findCommandByPath(root,pathParts){let current=root;for(const part of pathParts){const next=findDirectChildCommand(current,part);if(!next){return null}current=next}return current}const extensionCreatedCommands=new WeakSet;function ensureCommandPath(root,pathParts){if(pathParts.length===0){return null}let current=root;for(let index=0;index<pathParts.length;index+=1){const part=pathParts[index];const existing=findDirectChildCommand(current,part);if(existing){current=existing;continue}const created=current.command(part);extensionCreatedCommands.add(created);if(index<pathParts.length-1){created.description("Extension-provided command group.");created.action(()=>{created.help()})}else{created.description("Extension-provided command path.")}current=created}return current}function findExtensionCommandPathCollision(root,pathParts){let current=root;const traversed=[];for(const part of pathParts){const existing=findDirectChildCommand(current,part);if(!existing){return null}traversed.push(part);if(!extensionCreatedCommands.has(existing)){return{core_path:traversed.join(" "),extension_path:pathParts.join(" ")}}current=existing}return null}function buildExtensionCommandCollisionWarning(root,commandPath,aliases,descriptor){const pathParts=commandPath.split(" ").filter(part=>part.length>0);const collision=findExtensionCommandPathCollision(root,pathParts);if(!collision||collision.core_path===commandPath&&!aliases.has(commandPath)){return null}const extensionOwner=descriptor?.source?.package??descriptor?.source?.name??"unknown-extension";return`extension_command_collision:${collision.extension_path}:core_owner=pm-cli:${collision.core_path}:extension_owner=${extensionOwner}`}function collectSafeExtensionCommandPaths(root,commandHandlers,descriptors,aliases,onCollision){return[...new Set([...commandHandlers,...descriptors.keys()])].filter(commandPath=>commandPath.trim().length>0).sort((left,right)=>left.localeCompare(right)).filter(commandPath=>{const warning=buildExtensionCommandCollisionWarning(root,commandPath,aliases,descriptors.get(commandPath));if(!warning)return true;onCollision(warning);return false})}function reportExtensionCommandCollision(activationWarnings,report,warning){activationWarnings.push(warning);report(`[pm] warning: ${warning}; core command preserved. Rename or namespace the extension command alias.`)}export{applyDynamicExtensionArguments,applyDynamicExtensionFlagOptions,buildCanonicalExtensionAliases,buildDynamicExtensionCommandMetadataHelp,buildDynamicExtensionHelpOptionSummaries,buildExtensionCommandCollisionWarning,buildResidualDynamicExtensionFlagHelp,collectDynamicExtensionFlagHelpByCommand,collectExtensionCommandHelpDescriptors,collectSafeExtensionCommandPaths,commandAliases,ensureCommandPath,extensionFlagTakesValueForInvocation,findCommandByPath,findDirectChildCommand,findExtensionCommandPathCollision,mergeHelpOptionSummaries,normalizeExtensionCommandPath,reportExtensionCommandCollision,resolveExtensionFlagArity};
 //# sourceMappingURL=extension-command-help.js.map
-//# debugId=99d39b7c-ec26-5c95-85c0-ac28112a6fe6