minercon 3.0.0

package/out/commandTreeParsingBrigadier.js

@@ -0,0 +1,426 @@
+"use strict";
+// src/commandTreeParsingBrigadier.ts
+//
+// Pure parsing of Minecraft's Brigadier-shaped `/help` output (flat
+// `/cmd <args>` blobs, as returned by `minecraft:help` and vanilla's plain
+// `help`) into a `Parameter` tree, plus the root-listing parser
+// (`parseHelpResponse`) and the one-time namespace-support probe
+// (`isUnsupportedNamespaceError`). No state, no IO — every export here is a
+// deterministic function of its arguments, which is what makes them directly
+// unit-testable without constructing a `CommandTreeCrawler`.
+//
+// Bukkit's hand-written `Description:`/`Usage:`/`Aliases:` `/help <command>`
+// pages are a different grammar entirely - their extraction lives in
+// `commandTreeParsingBukkit.ts`.
+//
+// `stripColors` (used throughout to normalize input before parsing) and the
+// `formatMinecraftColors`/ANSI rendering side live in ansi.ts.
+//
+// The `Parameter`/`ParameterType` tree this file builds is defined in
+// `commandTree.ts`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tokenizeParameterString = tokenizeParameterString;
+exports.parseParameter = parseParameter;
+exports.classifyParameterTokens = classifyParameterTokens;
+exports.splitConcatenatedHelpLines = splitConcatenatedHelpLines;
+exports.parseAliasRedirect = parseAliasRedirect;
+exports.parseHelpLines = parseHelpLines;
+exports.isGenericArgsPlaceholder = isGenericArgsPlaceholder;
+exports.hasUsableArguments = hasUsableArguments;
+exports.hasRealUsage = hasRealUsage;
+exports.parseHelpResponse = parseHelpResponse;
+exports.isUnsupportedNamespaceError = isUnsupportedNamespaceError;
+exports.buildParameterStructureFromVariants = buildParameterStructureFromVariants;
+const ansi_1 = require("./ansi");
+const commandTree_1 = require("./commandTree");
+/**
+ * Tokenize parameter string handling nested structures
+ */
+function tokenizeParameterString(str) {
+    const tokens = [];
+    let current = '';
+    let depth = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str[i];
+        if ((char === '<' || char === '[' || char === '(')) {
+            if (depth === 0 && current.trim()) {
+                // A bare literal abutting the start of a bracketed token.
+                tokens.push(current.trim());
+                current = '';
+            }
+            depth++;
+            current += char;
+        }
+        else if ((char === '>' || char === ']' || char === ')')) {
+            depth--;
+            current += char;
+            if (depth === 0) {
+                tokens.push(current.trim());
+                current = '';
+            }
+        }
+        else if (char === ' ' && depth === 0) {
+            // Whitespace only separates tokens at the top level; inside a bracketed
+            // token (depth > 0) it's part of the token (e.g. "[plugin name]").
+            if (current.trim()) {
+                tokens.push(current.trim());
+                current = '';
+            }
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current.trim()) {
+        tokens.push(current.trim());
+    }
+    return tokens;
+}
+/**
+ * Parse a single parameter token. Every token maps to exactly one parameter
+ * (an unbracketed word becomes a `LITERAL`), so this never returns null.
+ */
+function parseParameter(token, position) {
+    // Check for choice list (option1|option2|...)
+    if (token.startsWith('(') && token.endsWith(')')) {
+        const choicesStr = token.slice(1, -1);
+        const choices = choicesStr.split('|').map((choice, idx) => ({
+            type: commandTree_1.ParameterType.LITERAL,
+            literal: choice.trim(),
+            optional: false,
+            position: idx
+        }));
+        return {
+            type: commandTree_1.ParameterType.CHOICE_LIST,
+            choices,
+            optional: false,
+            position
+        };
+    }
+    // Check for optional argument [name] or [<name>]
+    if (token.startsWith('[') && token.endsWith(']')) {
+        let name = token.slice(1, -1); // Remove [ and ]
+        // Also remove inner angle brackets if present
+        if (name.startsWith('<') && name.endsWith('>')) {
+            name = name.slice(1, -1); // Remove < and >
+            return {
+                type: commandTree_1.ParameterType.ARGUMENT,
+                name,
+                optional: true,
+                position
+            };
+        }
+        // For [literal] without angle brackets, this could be an optional subcommand
+        // Return as LITERAL but we'll handle it specially in loadCommandDetails
+        return {
+            type: commandTree_1.ParameterType.LITERAL,
+            literal: name, // Store WITHOUT the brackets
+            optional: true,
+            position
+        };
+    }
+    // Check for required argument <name>
+    if (token.startsWith('<') && token.endsWith('>')) {
+        const name = token.slice(1, -1);
+        return {
+            type: commandTree_1.ParameterType.ARGUMENT,
+            name,
+            optional: false,
+            position
+        };
+    }
+    // Otherwise it's a literal (could be a subcommand name)
+    // We'll determine if it's actually a subcommand later when we see it has members
+    return {
+        type: commandTree_1.ParameterType.LITERAL,
+        literal: token,
+        optional: false,
+        position
+    };
+}
+/**
+ * Classify a tokenized parameter string as either a named subcommand variant
+ * or a direct parameter list, parsing the relevant tokens along the way.
+ */
+function classifyParameterTokens(tokens) {
+    if (tokens.length === 0) {
+        return null;
+    }
+    const firstToken = tokens[0];
+    // Determine if first token is a literal/subcommand or an argument
+    // FIXED: Better detection for optional subcommands vs optional arguments
+    let isArgument = false;
+    if (firstToken.startsWith('<')) {
+        // <arg> - required argument
+        isArgument = true;
+    }
+    else if (firstToken.startsWith('[') && firstToken.endsWith(']')) {
+        // Could be [<arg>] or [subcommand]
+        const inner = firstToken.slice(1, -1);
+        if (inner.startsWith('<') && inner.endsWith('>')) {
+            // [<arg>] - optional argument
+            isArgument = true;
+        }
+        else {
+            // [subcommand] - optional subcommand, treat as subcommand
+            isArgument = false;
+        }
+    }
+    else if (firstToken.startsWith('(') && firstToken.endsWith(')')) {
+        // (choice1|choice2) - choice list, treat as argument
+        isArgument = true;
+    }
+    if (isArgument) {
+        // Every token is a direct parameter of the command/subcommand itself
+        const parameters = tokens.map((token, i) => parseParameter(token, i));
+        return { kind: 'direct', parameters };
+    }
+    // First token is a literal/subcommand name introducing a variant
+    let name = firstToken;
+    let optional = false;
+    // Strip optional brackets if present
+    if (name.startsWith('[') && name.endsWith(']')) {
+        name = name.slice(1, -1); // Remove [ and ]
+        optional = true;
+    }
+    const parameters = tokens.slice(1).map((token, i) => parseParameter(token, i));
+    return { kind: 'variant', name, optional, parameters };
+}
+/**
+ * Re-split a help response that packs multiple `/cmd ...` entries onto one
+ * line with no separators (e.g. a `minecraft:help` blob, or vanilla's `help
+ * <path>` for a multi-variant command like `gamerule`/`team`/`debug`) into
+ * one entry per line, ready for `parseHelpResponse`/`parseHelpLines`.
+ *
+ * Header/separator (`---...`) and blank lines are dropped first, so a
+ * `§e--------- §fHelp: /<cmd> §e----...` banner line - which itself contains
+ * a `/` - doesn't get re-split into a bogus `/<cmd> ----...` entry.
+ */
+function splitConcatenatedHelpLines(text) {
+    return text.split('\n')
+        .filter(line => {
+        const stripped = (0, ansi_1.stripColors)(line).trim();
+        return stripped && !stripped.startsWith('---');
+    })
+        .join('\n')
+        .replace(/\//g, '\n/');
+}
+/**
+ * Parse a single (already `stripColors`'d and trimmed) help line as a
+ * vanilla `minecraft:help` alias redirect of the form `/<alias> -> <target>`
+ * (e.g. `/tp -> teleport`, `/minecraft:xp -> experience`). Either side may
+ * carry a namespace prefix (e.g. `minecraft:`); namespace prefixes are
+ * preserved verbatim on both sides - per "ingest everything", a namespaced
+ * alias like `minecraft:tp` is its own root command, not folded into `tp`.
+ * Returns `null` if `line` doesn't match this shape.
+ */
+function parseAliasRedirect(line) {
+    const match = line.match(/^\/([a-zA-Z0-9_:-]+)\s*->\s*([a-zA-Z0-9_:-]+)$/);
+    if (!match) {
+        return null;
+    }
+    return { alias: match[1], target: match[2] };
+}
+/**
+ * Parse every line of `text` that describes `commandPath`'s syntax (an
+ * optional leading `/`, then `commandPath` with internal spaces matching
+ * runs of whitespace, then the argument tokens), collecting subcommand
+ * variants and/or a direct parameter list. Lines for other commands, alias
+ * redirects (`-> target`), and lines with no arguments at all are ignored.
+ *
+ * `text` is matched line-by-line (split on `\n`) — callers whose source may
+ * pack multiple commands' syntax onto one line without separators (e.g. a
+ * `minecraft:help` blob, where consecutive commands are simply concatenated)
+ * must first replace `/` with `\n/` to re-split it into one command per line.
+ */
+function parseHelpLines(text, commandPath) {
+    const escaped = commandPath
+        .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+        .replace(/ /g, '\\s+');
+    const pattern = new RegExp(`^/?${escaped}(?::)?\\s*(.*)$`, 'i');
+    const variants = new Map();
+    let direct = null;
+    for (const rawLine of text.split('\n')) {
+        const stripped = (0, ansi_1.stripColors)(rawLine).trim();
+        if (!stripped || stripped.startsWith('---')) {
+            continue;
+        }
+        const match = stripped.match(pattern);
+        if (!match) {
+            continue;
+        }
+        const afterCommand = match[1] || '';
+        if (!afterCommand || afterCommand.startsWith('->')) {
+            continue;
+        }
+        const tokens = tokenizeParameterString(afterCommand);
+        const classified = classifyParameterTokens(tokens);
+        if (classified?.kind === 'variant') {
+            variants.set(classified.name, { optional: classified.optional, members: classified.parameters });
+        }
+        else if (classified?.kind === 'direct') {
+            direct = classified.parameters;
+        }
+    }
+    return { variants, direct };
+}
+/**
+ * True iff `parameters` is exactly a bare `<args>`/`[<args>]` placeholder -
+ * the generic stand-in Bukkit emits (e.g. for `minecraft:help <cmd>` on
+ * commands that aren't Brigadier-backed, like `version`/`reload`/`plugins`)
+ * when it has no real argument info, regardless of whether it's optional.
+ */
+function isArgsPlaceholder(parameters) {
+    return parameters.length === 1
+        && parameters[0].type === commandTree_1.ParameterType.ARGUMENT
+        && parameters[0].name === 'args';
+}
+/**
+ * True iff `parameters` is exactly the generic `[<args>]` placeholder Bukkit
+ * emits for `minecraft:help <cmd>` on commands that aren't Brigadier-backed
+ * (e.g. `version`, `reload`, `plugins`) — i.e. no real argument info.
+ *
+ * Narrower than `isArgsPlaceholder` on purpose: it requires the `[<args>]`
+ * form to be *optional*. Bukkit's stand-in is always optional, so a
+ * *required* `<args>` is treated as a genuine (if oddly-named) argument by
+ * `hasRealUsage`/`mergeHelpSources` — those guard against emitting a fake
+ * `[<args>]` token while still honoring a real one. (`hasUsableArguments`,
+ * used for the separate "should we re-fetch this subcommand?" decision,
+ * deliberately rejects both forms via `isArgsPlaceholder`.)
+ */
+function isGenericArgsPlaceholder(parameters) {
+    return isArgsPlaceholder(parameters) && parameters[0].optional === true;
+}
+/**
+ * True iff `members` carries real, usable argument info for a subcommand
+ * variant - i.e. it's non-empty and not just an `<args>`/`[<args>]`
+ * placeholder (which means "no info available", whether or not it's
+ * optional). Used to decide whether the usage already parsed from a parent
+ * command's help output is trustworthy enough to skip a further per-subcommand
+ * help round trip.
+ */
+function hasUsableArguments(members) {
+    return members.length > 0 && !isArgsPlaceholder(members);
+}
+/**
+ * True iff `result` carries real, usable syntax info - either a non-placeholder
+ * `direct` parameter list or at least one subcommand variant. Used to decide
+ * whether a help source already answers a command's usage, or whether the
+ * caller needs to try another source.
+ */
+function hasRealUsage(result) {
+    return (result.direct !== null && !isGenericArgsPlaceholder(result.direct)) || result.variants.size > 0;
+}
+/**
+ * Shapes a root-command line can take in a `/help`/`minecraft:help` response,
+ * tried in order (first match wins). Each captures the command name in group
+ * 1; namespace prefixes (`minecraft:`, ...) are part of the name, so `:` is in
+ * every character class - see `parseHelpResponse`.
+ */
+const ROOT_COMMAND_PATTERNS = [
+    /^\/([a-zA-Z0-9_:-]+)/, // /command or /namespace:command
+    /^([a-zA-Z0-9_:-]+):\s/, // command: or command-with-hyphens:
+    /^[-*]\s*([a-zA-Z0-9_:-]+)/, // - command or * command
+    /^([a-zA-Z0-9_:-]+)\s+[-<[(]/ // command followed by args
+];
+/** Words that look like commands in description text but never are. */
+const NON_COMMAND_WORDS = new Set(['usage', 'example', 'description', 'syntax']);
+/**
+ * Parse a `/help` or `minecraft:help` response into the root commands and
+ * alias redirects it describes.
+ *
+ * `response` is first run through `splitConcatenatedHelpLines` so that a
+ * `minecraft:help` blob (multiple `/cmd ...` entries packed onto one line)
+ * is split one-per-line. Each resulting line is then matched against one of:
+ *
+ * - an alias redirect (`/<alias> -> <target>`, via `parseAliasRedirect`)
+ * - `/command ...` or `/namespace:command ...`
+ * - `command: ...` or `command-with-hyphens: ...`
+ * - `- command ...` or `* command ...`
+ * - `command <args>` (command name followed by `-`/`<`/`[`/`(`)
+ *
+ * Namespace prefixes (`minecraft:`, `bukkit:`, ...) are part of the command
+ * name - per "ingest everything", `minecraft:advancement` is its own root
+ * command, not just `minecraft`, so `:` is included in every pattern's
+ * character class. Common non-command words that appear in descriptions
+ * (`usage`, `example`, `description`, `syntax`) are skipped.
+ *
+ * For each command found, `isPlaceholder` reflects whether its summary line
+ * already carries real syntax info (`hasRealUsage`), so callers can decide
+ * which help source to try first for that command's full details.
+ */
+function parseHelpResponse(response) {
+    const lines = splitConcatenatedHelpLines(response).split('\n');
+    const commands = [];
+    const aliases = [];
+    for (const line of lines) {
+        const stripped = (0, ansi_1.stripColors)(line).trim();
+        // Skip empty lines and headers
+        if (!stripped || stripped.startsWith('---') || stripped.startsWith('===')) {
+            continue;
+        }
+        // Alias redirect lines (`/tp -> teleport`) describe an alias, not a
+        // root command in their own right.
+        const redirect = parseAliasRedirect(stripped);
+        if (redirect) {
+            aliases.push(redirect);
+            continue;
+        }
+        for (const pattern of ROOT_COMMAND_PATTERNS) {
+            const match = stripped.match(pattern);
+            if (!match) {
+                continue;
+            }
+            const commandName = match[1];
+            // Skip common non-command words that appear in descriptions
+            if (NON_COMMAND_WORDS.has(commandName.toLowerCase())) {
+                continue;
+            }
+            const summary = parseHelpLines(stripped, commandName);
+            commands.push({ name: commandName, isPlaceholder: !hasRealUsage(summary) });
+            break;
+        }
+    }
+    return { commands, aliases };
+}
+/**
+ * True iff `response` is the Brigadier "unknown namespace" syntax error
+ * returned for `minecraft:help` on servers where the `minecraft:` command
+ * namespace prefix isn't registered (vanilla/fabric) — distinct from the
+ * normal "Unknown command or insufficient permissions" not-found message.
+ */
+function isUnsupportedNamespaceError(response) {
+    return /^Unknown or incomplete command/i.test((0, ansi_1.stripColors)(response).trim());
+}
+/**
+ * Build the parameter structure representing a set of collected variants:
+ * a single SUBCOMMAND if there's only one, or a CHOICE_LIST wrapping a
+ * SUBCOMMAND for each variant (in encounter order) otherwise.
+ */
+function buildParameterStructureFromVariants(variants) {
+    if (variants.size === 0) {
+        return [];
+    }
+    const subcommandChoices = [];
+    for (const [name, { optional, members }] of variants) {
+        subcommandChoices.push({
+            type: commandTree_1.ParameterType.SUBCOMMAND,
+            name,
+            optional,
+            position: subcommandChoices.length,
+            members,
+            isComplete: false
+        });
+    }
+    // If there's only one variant, use it directly; otherwise wrap in a choice list
+    if (subcommandChoices.length === 1) {
+        return [subcommandChoices[0]];
+    }
+    return [{
+            type: commandTree_1.ParameterType.CHOICE_LIST,
+            optional: false,
+            position: 0,
+            choices: subcommandChoices
+        }];
+}
+//# sourceMappingURL=commandTreeParsingBrigadier.js.map

package/out/commandTreeParsingBukkit.js

@@ -0,0 +1,116 @@
+"use strict";
+// src/commandTreeParsingBukkit.ts
+//
+// Pure parsing of Bukkit's hand-written `/help <command>` pages. Two formats:
+//
+// 1. Description:/Usage:/Aliases: block — the standard format for commands with
+//    a single usage string (e.g. `/version`, `/reload`).
+//
+// 2. "Showing help for X" — a search-results page listing multiple subcommand
+//    usages as `<cmd> <subcmd> [args] - description` lines. Bukkit uses this
+//    for plugin commands that register each subcommand as its own help topic
+//    rather than a single `Usage:` string (e.g. multi-command plugin like mvp).
+//
+// Both formats are extracted by `extractBukkitUsageLines` and are a different
+// grammar from the flat Brigadier `/cmd <args>` blobs that
+// `commandTreeParsingBrigadier.ts` handles: on a server where the `minecraft:`
+// namespace is supported (Paper/Spigot), `help <path>` is *always* one of
+// these pages — so no shape-sniffing is needed to decide which parser applies,
+// only `CommandTreeCrawler.supportsMinecraftNamespace`.
+//
+// No state, no IO — every export here is a deterministic function of its
+// arguments.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractBukkitUsageLines = extractBukkitUsageLines;
+exports.extractBukkitAliases = extractBukkitAliases;
+const ansi_1 = require("./ansi");
+/**
+ * Find the index of the first ` - ` (space-dash-space) at bracket depth 0 in
+ * `s`. This is the separator between the usage string and the description in
+ * Bukkit's "Showing help for X" format. Returns -1 if not found.
+ */
+function descriptionSeparatorIndex(s) {
+    let depth = 0;
+    for (let i = 0; i < s.length - 2; i++) {
+        const c = s[i];
+        if (c === '<' || c === '[' || c === '(') {
+            depth++;
+        }
+        else if (c === '>' || c === ']' || c === ')') {
+            depth--;
+        }
+        else if (depth === 0 && c === ' ' && s[i + 1] === '-' && s[i + 2] === ' ') {
+            return i;
+        }
+    }
+    return -1;
+}
+/**
+ * Extract the `Usage: ...` line(s) from a Bukkit-style `/help <command>`
+ * response. Handles two formats:
+ *
+ * 1. Standard `Description:`/`Usage:`/`Aliases:` block (e.g. `/version`,
+ *    `/reload`): returns the `Usage:` line(s), normalized for `parseHelpLines`.
+ *    Returns `[]` if the Usage is just the bare command name (the generic
+ *    response Bukkit gives for Brigadier-backed vanilla commands).
+ *
+ * 2. "Showing help for X" page (e.g. multi-command plugin help topics): lines
+ *    of the form `<cmd> <subcmd> [args] - description`. Strips the ` -
+ *    description` tail from each matching line and returns the usage portions,
+ *    filtered to exclude the bare command itself.
+ *
+ * Returns `[]` if neither format yields usable argument info.
+ */
+function extractBukkitUsageLines(helpText, commandPath) {
+    const lines = (0, ansi_1.stripColors)(helpText).split('\n').map(line => line.trim());
+    const usageIndex = lines.findIndex(line => /^Usage:\s*/i.test(line));
+    if (usageIndex !== -1) {
+        const result = [lines[usageIndex].replace(/^Usage:\s*/i, '')];
+        for (let i = usageIndex + 1; i < lines.length; i++) {
+            const line = lines[i];
+            if (!line || /^[A-Za-z][A-Za-z ]*:/.test(line) || line.startsWith('---')) {
+                break;
+            }
+            result.push(line);
+        }
+        const normalizedPath = commandPath.toLowerCase();
+        return result.filter(line => line.replace(/^\//, '').toLowerCase() !== normalizedPath);
+    }
+    // "Showing help for X" format: each line is `<cmd> <subcmd> [args] - description`.
+    // Match lines that start with commandPath followed by a space, strip descriptions.
+    const escaped = commandPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/ /g, '\\s+');
+    const cmdPattern = new RegExp(`^/?${escaped}\\s`, 'i');
+    const normalizedPath = commandPath.toLowerCase();
+    const usageLines = [];
+    for (const line of lines) {
+        if (!line || line.startsWith('---') || line.startsWith('===')) {
+            continue;
+        }
+        if (!cmdPattern.test(line)) {
+            continue;
+        }
+        const sepIdx = descriptionSeparatorIndex(line);
+        const usagePart = (sepIdx >= 0 ? line.slice(0, sepIdx) : line).trim();
+        if (usagePart.replace(/^\//, '').toLowerCase() !== normalizedPath) {
+            usageLines.push(usagePart);
+        }
+    }
+    return usageLines;
+}
+/**
+ * Extract alias names from a Bukkit-style `/help <command>` response's
+ * `Aliases: a, b, c` line (e.g. "Description: ...\nUsage: ...\nAliases: ver,
+ * about"). Returns `[]` if there's no Aliases line.
+ */
+function extractBukkitAliases(helpText) {
+    const lines = (0, ansi_1.stripColors)(helpText).split('\n').map(line => line.trim());
+    const aliasesLine = lines.find(line => /^Aliases:\s*/i.test(line));
+    if (!aliasesLine) {
+        return [];
+    }
+    return aliasesLine.replace(/^Aliases:\s*/i, '')
+        .split(',')
+        .map(alias => alias.trim())
+        .filter(alias => alias.length > 0);
+}
+//# sourceMappingURL=commandTreeParsingBukkit.js.map

package/out/commandTreeSuggestions.js

@@ -0,0 +1,142 @@
+"use strict";
+// src/commandTreeSuggestions.ts
+//
+// Pure suggestion generation: given the command tree `CommandTreeCrawler`
+// builds and the user's current input line, work out what to suggest next
+// and what argument-help text to show. No state, no IO — a deterministic
+// function of the tree and the input.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSuggestions = getSuggestions;
+const commandTree_1 = require("./commandTree");
+const commandLine_1 = require("./commandLine");
+/**
+ * Get suggestions based on current input
+ */
+function getSuggestions(rootCommands, isReady, input) {
+    if (!isReady) {
+        return { suggestions: [], argumentHelp: undefined };
+    }
+    const trimmed = input.trim();
+    if (!trimmed.startsWith('/')) {
+        return { suggestions: [], argumentHelp: undefined };
+    }
+    const { parts, hasTrailingSpace } = (0, commandLine_1.splitCommandLine)(input);
+    const commandName = parts[0];
+    // Handle root command suggestions
+    if (parts.length === 0 || (parts.length === 1 && !hasTrailingSpace)) {
+        const suggestions = Array.from(rootCommands.keys())
+            .filter(cmd => cmd.startsWith(commandName || ''))
+            .sort();
+        return { suggestions, argumentHelp: undefined };
+    }
+    // Find the command node
+    const rootNode = rootCommands.get(commandName);
+    if (!rootNode) {
+        return { suggestions: [], argumentHelp: undefined };
+    }
+    // Navigate through the parameter tree
+    let currentParameters = rootNode.members;
+    let paramIndex = 1; // Start after the command name
+    // The command path consumed so far (root command + any literal/subcommand
+    // tokens navigated past) - see SuggestionResult.commandPath.
+    const pathParts = [commandName];
+    // Navigate through completed parts (not including what we're currently typing)
+    const partsToNavigate = hasTrailingSpace ? parts.length : parts.length - 1;
+    while (paramIndex < partsToNavigate && currentParameters.length > 0) {
+        const currentPart = parts[paramIndex];
+        let navigated = false;
+        // Get the first parameter at this position
+        const firstParam = currentParameters[0];
+        if (firstParam.type === commandTree_1.ParameterType.SUBCOMMAND) {
+            // Direct subcommand
+            if (firstParam.name === currentPart) {
+                currentParameters = firstParam.members;
+                navigated = true;
+            }
+        }
+        else if (firstParam.type === commandTree_1.ParameterType.CHOICE_LIST) {
+            // Choice list - find matching choice and navigate into it
+            for (const choice of firstParam.choices) {
+                if (choice.type === commandTree_1.ParameterType.SUBCOMMAND && choice.name === currentPart) {
+                    // IMPORTANT: Navigate into the selected choice's members
+                    currentParameters = choice.members;
+                    navigated = true;
+                    break;
+                }
+                else if (choice.type === commandTree_1.ParameterType.LITERAL && choice.literal === currentPart) {
+                    // For literal choices, move to next parameter position
+                    currentParameters = currentParameters.slice(1);
+                    navigated = true;
+                    break;
+                }
+            }
+        }
+        else if (firstParam.type === commandTree_1.ParameterType.LITERAL && firstParam.literal === currentPart) {
+            // Literal parameter
+            currentParameters = currentParameters.slice(1);
+            navigated = true;
+        }
+        paramIndex++;
+        if (navigated) {
+            pathParts.push(currentPart);
+        }
+        else {
+            // It's an argument value, skip to next position
+            currentParameters = currentParameters.slice(1);
+        }
+    }
+    // Build argument help from current position
+    const argumentHelp = buildArgumentHelp(currentParameters);
+    const commandPath = pathParts.join(' ');
+    // Generate suggestions for the current position. A trailing space means the
+    // user is starting the next token, so match against an empty prefix (every
+    // candidate); otherwise match the partial token they're still typing.
+    const typedPrefix = hasTrailingSpace ? '' : (parts[parts.length - 1] || '');
+    const suggestions = suggestionsMatchingPrefix(currentParameters, typedPrefix);
+    return { suggestions, argumentHelp, commandPath };
+}
+/**
+ * Suggestions for the parameter position represented by `parameters`, limited
+ * to the candidates that start with `prefix` (pass `''` to get them all — e.g.
+ * after a trailing space, when the user is starting a fresh token). Only the
+ * first parameter at this position is suggestable; ARGUMENT positions have no
+ * fixed candidates and yield nothing.
+ */
+function suggestionsMatchingPrefix(parameters, prefix) {
+    if (parameters.length === 0) {
+        return [];
+    }
+    const param = parameters[0];
+    // A CHOICE_LIST contributes each of its subcommand/literal choices; a bare
+    // SUBCOMMAND/LITERAL contributes itself; an ARGUMENT contributes nothing.
+    const candidates = param.type === commandTree_1.ParameterType.CHOICE_LIST
+        ? param.choices.filter(c => c.type === commandTree_1.ParameterType.SUBCOMMAND || c.type === commandTree_1.ParameterType.LITERAL)
+        : (param.type === commandTree_1.ParameterType.SUBCOMMAND || param.type === commandTree_1.ParameterType.LITERAL)
+            ? [param]
+            : [];
+    return candidates
+        .map(commandTree_1.parameterLabel)
+        .filter(label => label.startsWith(prefix))
+        .sort();
+}
+/**
+ * Build argument help string from parameters
+ */
+function buildArgumentHelp(parameters) {
+    if (parameters.length === 0) {
+        return '';
+    }
+    return parameters.map(param => {
+        switch (param.type) {
+            case commandTree_1.ParameterType.ARGUMENT:
+                return param.optional ? `[<${param.name}>]` : `<${param.name}>`;
+            case commandTree_1.ParameterType.CHOICE_LIST:
+                return `(${param.choices.map(commandTree_1.parameterLabel).join('|')})`;
+            case commandTree_1.ParameterType.LITERAL:
+                return param.literal;
+            case commandTree_1.ParameterType.SUBCOMMAND:
+                return param.name; // Show subcommand name
+        }
+    }).join(' ');
+}
+//# sourceMappingURL=commandTreeSuggestions.js.map