minercon 3.0.0

package/out/cli.js

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+"use strict";
+// src/cli.ts — standalone CLI entry point for the Minercon terminal.
+// Compiles to out/cli.js; the build script copies it to out/minercon.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const util_1 = require("util");
+const consola_1 = require("consola");
+const prompts_1 = require("@clack/prompts");
+const rconClient_1 = require("./rconClient");
+const rconSession_1 = require("./rconSession");
+const cliConfig_1 = require("./cliConfig");
+// ── Config file ──────────────────────────────────────────────────────────────
+const CONFIG_DIR = path.join(os.homedir(), '.config', 'minercon');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+// ── Prompt cancellation ──────────────────────────────────────────────────────
+/** Unwraps a clack prompt result, exiting cleanly if the user cancelled (Ctrl+C/Esc). */
+function unwrap(result) {
+    if ((0, prompts_1.isCancel)(result)) {
+        (0, prompts_1.cancel)('Cancelled.');
+        process.exit(0);
+    }
+    return result;
+}
+// ── Main ─────────────────────────────────────────────────────────────────────
+async function main() {
+    const { values, positionals } = (0, util_1.parseArgs)({
+        args: process.argv.slice(2),
+        options: {
+            password: { type: 'string', short: 'p' },
+            save: { type: 'boolean', default: false },
+            'log-file': { type: 'string' },
+            'log-level': { type: 'string' },
+            'history-size': { type: 'string' },
+            'no-plugin': { type: 'boolean', default: false },
+            'no-unpaginate': { type: 'boolean', default: false },
+            'no-pager': { type: 'boolean', default: false },
+            help: { type: 'boolean', short: 'h', default: false },
+            version: { type: 'boolean', short: 'V', default: false },
+        },
+        allowPositionals: true,
+        strict: false,
+    });
+    if (values.version) {
+        const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+        process.stdout.write(`minercon ${pkg.version}\n`);
+        process.exit(0);
+    }
+    if (values.help) {
+        process.stdout.write([
+            'Usage: minercon [host] [port] [options]',
+            '',
+            'Options:',
+            '  -p, --password <pw>   RCON password (also: MCRCON_PASSWORD env var)',
+            '  --save                Save host/port/history-size to ~/.config/minercon/config.json',
+            '  --log-file <path>     Write log output to a file instead of the console',
+            '  --log-level <level>   consola log level, e.g. debug, info, warn, error (default: info)',
+            '  --history-size <n>    Number of commands to remember in history (default: 100)',
+            '  --no-plugin           Skip the server-side tab-complete plugin probe (manual testing only;',
+            '                        not persisted to config)',
+            '  --no-unpaginate       Do not request unpaginated output via the plugin (keep server pages)',
+            '  --no-pager            Do not page tall output; print it all at once',
+            '  -V, --version         Print version and exit',
+            '  -h, --help            Show this help',
+            '',
+            'Environment:',
+            '  MCRCON_PASSWORD       RCON password (used if --password is not given)',
+            '  MCRCON_LOG_FILE       Log file path (used if --log-file is not given)',
+            '  MCRCON_LOG_LEVEL      Log level (used if --log-level is not given)',
+            '  MCRCON_HISTORY_SIZE   History size (used if --history-size is not given)',
+            '  MCRCON_UNPAGINATE     Set to 0 to disable unpaginated output (default on)',
+            '  MCRCON_PAGER          Set to 0 to disable the output pager (default on)',
+            '',
+        ].join('\n'));
+        process.exit(0);
+    }
+    if (!process.stdin.isTTY) {
+        process.stderr.write('Error: minercon is an interactive terminal and does not support piped input\n');
+        process.exit(1);
+    }
+    const logLevelResolution = (0, cliConfig_1.resolveLogLevel)(values['log-level'], process.env['MCRCON_LOG_LEVEL']);
+    if ('error' in logLevelResolution) {
+        process.stderr.write(`Error: ${logLevelResolution.error}\n`);
+        process.exit(1);
+    }
+    const logFilePath = values['log-file'] ?? process.env['MCRCON_LOG_FILE'];
+    const logStream = logFilePath
+        ? fs.createWriteStream(logFilePath, { flags: 'a' })
+        : undefined;
+    (0, prompts_1.updateSettings)({ withGuide: false });
+    const logger = (0, consola_1.createConsola)({
+        level: logLevelResolution.level,
+        ...(logStream ? { stdout: logStream, stderr: logStream } : {}),
+    });
+    const savedConfig = (0, cliConfig_1.readConfig)(CONFIG_FILE);
+    // Resolve host
+    let host = (0, cliConfig_1.resolveHost)(positionals[0], savedConfig);
+    if (!host) {
+        host = unwrap(await (0, prompts_1.text)({
+            message: 'RCON host (e.g. 127.0.0.1):',
+            validate: (value) => {
+                if (!value || value.trim() === '') {
+                    return 'host is required';
+                }
+            },
+        })).trim();
+    }
+    // Resolve port
+    let port;
+    const portResolution = (0, cliConfig_1.resolvePort)(positionals[1], savedConfig);
+    if (portResolution && 'error' in portResolution) {
+        process.stderr.write(`Error: ${portResolution.error}\n`);
+        process.exit(1);
+    }
+    else if (portResolution) {
+        port = portResolution.port;
+    }
+    else {
+        const raw = unwrap(await (0, prompts_1.text)({
+            message: 'RCON port',
+            placeholder: '25575',
+            defaultValue: '25575',
+            validate: (value) => {
+                if (value && (0, cliConfig_1.parsePort)(value) === null) {
+                    return `invalid port: ${value}`;
+                }
+            },
+        }));
+        const parsed = (0, cliConfig_1.parsePort)(raw);
+        if (parsed === null) {
+            process.stderr.write(`Error: invalid port: ${raw}\n`);
+            process.exit(1);
+        }
+        port = parsed;
+    }
+    // Resolve password — never saved to disk
+    let password = (0, cliConfig_1.resolvePassword)(values.password, process.env['MCRCON_PASSWORD']);
+    if (!password) {
+        password = unwrap(await (0, prompts_1.password)({ message: `RCON password for ${host}:${port}:` }));
+    }
+    // Resolve history size
+    const historySizeResolution = (0, cliConfig_1.resolveHistorySize)(values['history-size'], process.env['MCRCON_HISTORY_SIZE'], savedConfig);
+    if ('error' in historySizeResolution) {
+        process.stderr.write(`Error: ${historySizeResolution.error}\n`);
+        process.exit(1);
+    }
+    const historySize = historySizeResolution.historySize;
+    if (values.save) {
+        (0, cliConfig_1.writeConfig)(CONFIG_FILE, { host, port, historySize });
+        logger.info(`Saved ${host}:${port} (history size ${historySize}) to ${CONFIG_FILE}`);
+    }
+    // ── Establish connection ──────────────────────────────────────────────────
+    const controller = new rconClient_1.RconController(host, port, password, logger);
+    logger.info(`Connecting to ${host}:${port}...`);
+    try {
+        await controller.connect();
+    }
+    catch (err) {
+        logger.error(`Failed to connect: ${err}`);
+        process.exit(1);
+    }
+    // ── Build session host ────────────────────────────────────────────────────
+    let pasteboard = '';
+    // Cache lives in the same config dir as config.json
+    const cacheDir = CONFIG_DIR;
+    const sessionHost = {
+        write: (text) => process.stdout.write(text),
+        close: (code) => {
+            teardown();
+            process.exit(code);
+        },
+        clipboard: {
+            readText: () => Promise.resolve(pasteboard),
+            writeText: (text) => { pasteboard = text; return Promise.resolve(); },
+        },
+        cacheDir,
+        dimensions: () => process.stdout.columns && process.stdout.rows
+            ? { columns: process.stdout.columns, rows: process.stdout.rows }
+            : undefined,
+        historySize,
+        disablePlugin: values['no-plugin'],
+        // Both default-on: disabled only by their --no-* flag or env var set to '0'.
+        unpaginateOutput: !values['no-unpaginate'] && process.env['MCRCON_UNPAGINATE'] !== '0',
+        terminalPager: !values['no-pager'] && process.env['MCRCON_PAGER'] !== '0',
+        logToFile: logFilePath !== undefined,
+    };
+    const session = new rconSession_1.RconSession(controller, host, port, password, logger, sessionHost);
+    // ── TTY / signal setup ────────────────────────────────────────────────────
+    let tornDown = false;
+    function teardown() {
+        if (tornDown) {
+            return;
+        }
+        tornDown = true;
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+        session.close();
+    }
+    process.on('exit', teardown);
+    process.on('SIGINT', () => { teardown(); process.exit(0); });
+    process.on('SIGTERM', () => { teardown(); process.exit(0); });
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+    process.stdout.on('resize', () => {
+        // dimensions() reads process.stdout.columns/rows live — nothing to do here
+    });
+    process.stdin.on('data', (chunk) => {
+        session.handleInput(chunk);
+    });
+    // Open the session (writes the welcome banner and starts the plugin probe)
+    session.open();
+}
+main().catch((err) => {
+    process.stderr.write(`Error: ${err}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/out/cliConfig.js

@@ -0,0 +1,141 @@
+"use strict";
+// src/cliConfig.ts
+//
+// Pure helpers for the CLI's connection-config resolution: the saved
+// host/port config file, port validation, and the precedence rules for
+// host/port/password (CLI args → saved config / env var → prompt). Kept
+// separate from cli.ts (which wires these into argv parsing, prompts, and
+// process I/O) so the precedence logic can be unit-tested without spawning a
+// process or touching stdin/stdout.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readConfig = readConfig;
+exports.writeConfig = writeConfig;
+exports.parsePort = parsePort;
+exports.resolveHost = resolveHost;
+exports.resolvePort = resolvePort;
+exports.resolvePassword = resolvePassword;
+exports.parseHistorySize = parseHistorySize;
+exports.resolveHistorySize = resolveHistorySize;
+exports.resolveLogLevel = resolveLogLevel;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const consola_1 = require("consola");
+function readConfig(configFile) {
+    try {
+        return JSON.parse(fs.readFileSync(configFile, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeConfig(configFile, cfg) {
+    fs.mkdirSync(path.dirname(configFile), { recursive: true });
+    fs.writeFileSync(configFile, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+}
+/** Parses a port string, returning null if it isn't a valid TCP port (1-65535). */
+function parsePort(raw) {
+    const port = parseInt(raw, 10);
+    if (isNaN(port) || port < 1 || port > 65535) {
+        return null;
+    }
+    return port;
+}
+/** Resolves the RCON host from a positional CLI arg and the saved config, or undefined if the user must be prompted. */
+function resolveHost(positionalHost, savedConfig) {
+    return positionalHost || savedConfig.host;
+}
+/**
+ * Resolves the RCON port from a positional CLI arg and the saved config.
+ *  - `{ port }` if resolved from the arg or the saved config
+ *  - `{ error }` if a positional port arg was given but isn't a valid port
+ *  - `undefined` if the user must be prompted (with a default of 25575)
+ */
+function resolvePort(positionalPort, savedConfig) {
+    if (positionalPort !== undefined) {
+        const port = parsePort(positionalPort);
+        return port !== null ? { port } : { error: `invalid port: ${positionalPort}` };
+    }
+    if (savedConfig.port !== undefined) {
+        return { port: savedConfig.port };
+    }
+    return undefined;
+}
+/** Resolves the RCON password from the --password flag and MCRCON_PASSWORD env var, or undefined if the user must be prompted. */
+function resolvePassword(flagPassword, envPassword) {
+    return flagPassword || envPassword || undefined;
+}
+/** Parses a history size string, returning null if it isn't a positive integer. */
+function parseHistorySize(raw) {
+    const size = parseInt(raw, 10);
+    if (isNaN(size) || size < 1 || String(size) !== raw.trim()) {
+        return null;
+    }
+    return size;
+}
+/**
+ * Resolves the number of history entries to remember from the --history-size
+ * flag, MCRCON_HISTORY_SIZE env var, and saved config, in that order, falling
+ * back to 100 if none are set. Returns `{ error }` if a value was given but
+ * isn't a positive integer.
+ */
+function resolveHistorySize(flagValue, envValue, savedConfig) {
+    const raw = flagValue || envValue;
+    if (raw !== undefined) {
+        const parsed = parseHistorySize(raw);
+        return parsed !== null ? { historySize: parsed } : { error: `invalid history size: ${raw}` };
+    }
+    if (savedConfig.historySize !== undefined) {
+        return { historySize: savedConfig.historySize };
+    }
+    return { historySize: 100 };
+}
+/**
+ * Resolves the consola log level from the --log-level flag or
+ * MCRCON_LOG_LEVEL env var, in that order, falling back to "info" if neither
+ * is set. Returns `{ error }` if a value was given but isn't one of
+ * consola's LogTypes.
+ */
+function resolveLogLevel(flagValue, envValue) {
+    const raw = flagValue || envValue;
+    if (raw === undefined) {
+        return { level: consola_1.LogLevels.info };
+    }
+    if (raw in consola_1.LogLevels) {
+        return { level: consola_1.LogLevels[raw] };
+    }
+    return { error: `invalid log level: ${raw} (expected one of: ${Object.keys(consola_1.LogLevels).join(', ')})` };
+}
+//# sourceMappingURL=cliConfig.js.map

package/out/commandLine.js

@@ -0,0 +1,28 @@
+"use strict";
+// src/commandLine.ts
+//
+// Splitting a *typed command invocation* into its space-separated words —
+// the shared counterpart to commandTreeParsingBrigadier's
+// `tokenizeParameterString`, which tokenizes a *usage/grammar string*.
+//
+// The distinction matters: a usage string uses `<>`/`[]`/`()` as structural
+// metacharacters (and `tokenizeParameterString` keeps those groups whole),
+// whereas a command line the user is typing carries those same characters as
+// literal argument data — target selectors (`@e[type=cow]`), NBT (`{...}`),
+// coordinates — where only whitespace separates arguments and a half-typed
+// bracket is just text. So command lines are split here, plainly on
+// whitespace, and never run through the grammar tokenizer.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitCommandLine = splitCommandLine;
+/**
+ * Split a typed command line into its words, dropping a single leading `/`
+ * if present. Callers that care whether the input *is* a command (starts with
+ * `/`) should check that themselves; this only parses the words out.
+ */
+function splitCommandLine(input) {
+    const hasTrailingSpace = input.endsWith(' ');
+    const body = input.trim().replace(/^\//, '');
+    const parts = body.split(/\s+/).filter(p => p.length > 0);
+    return { parts, hasTrailingSpace };
+}
+//# sourceMappingURL=commandLine.js.map

package/out/commandSuggestions.js

@@ -0,0 +1,202 @@
+"use strict";
+// src/commandSuggestions.ts
+//
+// Pure suggestion generation: given the command tree `LocalCommandTree`
+// 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");
+/**
+ * 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 hasTrailingSpace = input.endsWith(' ');
+    const parts = trimmed.slice(1).split(' ').filter(p => p.length > 0);
+    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 || firstParam.literal === currentPart) {
+                currentParameters = firstParam.members || [];
+                navigated = true;
+            }
+        }
+        else if (firstParam.type === commandTree_1.ParameterType.CHOICE_LIST && firstParam.choices) {
+            // 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 || choice.literal === 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 based on current position
+    let suggestions = [];
+    if (hasTrailingSpace) {
+        // We want suggestions for the NEXT parameter
+        suggestions = generateSuggestionsForNextPosition(currentParameters);
+    }
+    else {
+        // We're typing something, get matching suggestions
+        const currentPart = parts[parts.length - 1] || '';
+        suggestions = generateSuggestionsForCurrentPart(currentParameters, currentPart);
+    }
+    return { suggestions, argumentHelp, commandPath };
+}
+/**
+ * Generate suggestions for what we're currently typing
+ * Must handle CHOICE_LIST parameters properly
+ */
+function generateSuggestionsForCurrentPart(parameters, currentPart) {
+    const suggestions = [];
+    for (const param of parameters) {
+        if (param.type === commandTree_1.ParameterType.SUBCOMMAND) {
+            // Direct subcommand
+            const name = param.name || param.literal || '';
+            if (name.startsWith(currentPart)) {
+                suggestions.push(name);
+            }
+        }
+        else if (param.type === commandTree_1.ParameterType.CHOICE_LIST && param.choices) {
+            // Choice list - add all matching choices
+            for (const choice of param.choices) {
+                if (choice.type === commandTree_1.ParameterType.SUBCOMMAND) {
+                    const name = choice.name || choice.literal || '';
+                    if (name.startsWith(currentPart)) {
+                        suggestions.push(name);
+                    }
+                }
+                else if (choice.type === commandTree_1.ParameterType.LITERAL) {
+                    const literal = choice.literal || '';
+                    if (literal.startsWith(currentPart)) {
+                        suggestions.push(literal);
+                    }
+                }
+            }
+        }
+        else if (param.type === commandTree_1.ParameterType.LITERAL) {
+            const literal = param.literal || '';
+            if (literal.startsWith(currentPart)) {
+                suggestions.push(literal);
+            }
+        }
+        // We only process the first parameter position
+        break;
+    }
+    return suggestions.sort();
+}
+/**
+ * Generate suggestions for the next parameter position
+ * Must handle CHOICE_LIST parameters properly
+ */
+function generateSuggestionsForNextPosition(parameters) {
+    const suggestions = [];
+    if (parameters.length === 0) {
+        return suggestions;
+    }
+    const firstParam = parameters[0];
+    if (firstParam.type === commandTree_1.ParameterType.SUBCOMMAND) {
+        // Direct subcommand
+        suggestions.push(firstParam.name || firstParam.literal || '');
+    }
+    else if (firstParam.type === commandTree_1.ParameterType.CHOICE_LIST && firstParam.choices) {
+        // Choice list - add all choices as suggestions
+        for (const choice of firstParam.choices) {
+            if (choice.type === commandTree_1.ParameterType.SUBCOMMAND) {
+                suggestions.push(choice.name || choice.literal || '');
+            }
+            else if (choice.type === commandTree_1.ParameterType.LITERAL) {
+                suggestions.push(choice.literal || '');
+            }
+        }
+    }
+    else if (firstParam.type === commandTree_1.ParameterType.LITERAL) {
+        suggestions.push(firstParam.literal || '');
+    }
+    // Don't suggest anything for ARGUMENT types
+    return suggestions.sort();
+}
+/**
+ * Build argument help string from parameters
+ */
+function buildArgumentHelp(parameters) {
+    if (parameters.length === 0) {
+        return '';
+    }
+    return parameters.map(param => {
+        if (param.type === commandTree_1.ParameterType.ARGUMENT) {
+            return param.optional ? `[<${param.name}>]` : `<${param.name}>`;
+        }
+        else if (param.type === commandTree_1.ParameterType.CHOICE_LIST && param.choices) {
+            const choices = param.choices.map((c) => c.literal).join('|');
+            return `(${choices})`;
+        }
+        else if (param.type === commandTree_1.ParameterType.LITERAL) {
+            return param.literal;
+        }
+        else if (param.type === commandTree_1.ParameterType.SUBCOMMAND) {
+            return param.name; // Show subcommand name
+        }
+        return '';
+    }).join(' ');
+}
+//# sourceMappingURL=commandSuggestions.js.map

package/out/commandTree.js

@@ -0,0 +1,46 @@
+"use strict";
+// src/commandTree.ts
+//
+// The command tree model: a discriminated union `Parameter`, used both for
+// root commands (the entries in `CommandTreeCrawler`'s `rootCommands` map,
+// aliased here as `CommandNode`) and for every argument/subcommand/choice
+// nested beneath them. The `type` tag selects the variant, and each variant
+// carries exactly the fields that apply to it - so consumers `switch` on
+// `type` and get the right fields narrowed, with no `param.choices!` /
+// `param.name || param.literal` defensiveness.
+//
+// Everything that builds it lives in commandTreeParsingBrigadier.ts/
+// commandTreeParsingBukkit.ts; everything that reads it lives in
+// commandTreeSuggestions.ts/displayArgumentHint.ts; `commandTreeCrawler.ts` is the
+// stateful orchestration that ties construction and the cache together.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ParameterType = void 0;
+exports.newCommandNode = newCommandNode;
+exports.parameterLabel = parameterLabel;
+var ParameterType;
+(function (ParameterType) {
+    ParameterType["ARGUMENT"] = "argument";
+    ParameterType["LITERAL"] = "literal";
+    ParameterType["CHOICE_LIST"] = "choice_list";
+    ParameterType["SUBCOMMAND"] = "subcommand"; // subcommand with its own members
+})(ParameterType || (exports.ParameterType = ParameterType = {}));
+/** A fresh, not-yet-loaded root command node for `name`. */
+function newCommandNode(name) {
+    return { type: ParameterType.SUBCOMMAND, name, optional: false, position: 0, members: [], isComplete: false };
+}
+/**
+ * The bare display label of a parameter: an argument/subcommand name, a
+ * literal's text, or a choice list joined with `|`. The single source of
+ * truth both display sites (`commandTreeSuggestions`, `displayCommandTree`)
+ * use to render a parameter's inner token, so neither has to narrow the
+ * union by hand.
+ */
+function parameterLabel(p) {
+    switch (p.type) {
+        case ParameterType.ARGUMENT: return p.name;
+        case ParameterType.LITERAL: return p.literal;
+        case ParameterType.SUBCOMMAND: return p.name;
+        case ParameterType.CHOICE_LIST: return p.choices.map(parameterLabel).join('|');
+    }
+}
+//# sourceMappingURL=commandTree.js.map