minercon 3.0.0

package/out/completionBackend.js

@@ -0,0 +1,94 @@
+"use strict";
+// src/completionBackend.ts
+//
+// The completionEngine state machine knows it needs completions and usage
+// text for a given input line — it doesn't know or care whether those come
+// from a network round trip or an in-memory lookup. A CompletionBackend is
+// that boundary: one implementation asks the server-side TabComplete
+// plugin over RCON, the other asks the locally-built command tree.
+//
+// Driving both modes through the same backend interface (and therefore the
+// same engine, the same dispatch plumbing, and the same rendering) is what
+// lets RconSession be entirely mode-blind — "which backend" is decided once,
+// not branched on at every call site.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalCompletionBackend = exports.RconCompletionBackend = void 0;
+const completionQueries_1 = require("./completionQueries");
+/**
+ * Server-side completions via the TabComplete plugin's `tabcomplete`/`cmdusage` commands.
+ *
+ * Takes a `controller` thunk rather than a fixed `RconController` — the
+ * connection manager replaces its controller wholesale on every reconnect, so
+ * capturing one instance up front would silently start sending through a dead
+ * (disconnected) controller after the first reconnect, with every fetch
+ * throwing "Not connected" (swallowed by the caller as "no completions").
+ * Looking it up fresh on each call always reaches whatever's live.
+ */
+class RconCompletionBackend {
+    getController;
+    constructor(getController) {
+        this.getController = getController;
+    }
+    async fetchCompletions(line) {
+        const query = (0, completionQueries_1.buildCompletionsQuery)(line);
+        if (query === null) {
+            return [];
+        }
+        const response = await this.getController().send(`tabcomplete ${query}`);
+        return (0, completionQueries_1.parseCompletionsResponse)(response);
+    }
+    async fetchUsage(line) {
+        const query = (0, completionQueries_1.buildUsageQuery)(line);
+        if (query === null) {
+            return '';
+        }
+        const response = await this.getController().send(`cmdusage ${query}`);
+        return (0, completionQueries_1.parseUsageResponse)(response);
+    }
+}
+exports.RconCompletionBackend = RconCompletionBackend;
+/**
+ * Local completions via the command tree CommandTreeCrawler builds at
+ * startup — a synchronous in-memory lookup, wrapped in `async` so it flows
+ * through exactly the same dispatch path as the RCON backend (the `await`
+ * still yields to the microtask queue, so a `dispatchToEngine` call made from
+ * here lands *after* the effect loop that triggered it has finished — same
+ * ordering guarantee the real async backend gets for free from the network).
+ */
+class LocalCompletionBackend {
+    commandTree;
+    // getSuggestions sometimes returns undefined argumentHelp when the user is
+    // typing a free-form argument value the tree has no completions for (e.g. a
+    // player name). Rather than letting the hint flicker to blank, cache the last
+    // resolved usage and return it until the commandPath changes — each distinct
+    // navigated path (e.g. "mv worldborder" vs "mv worldborder damage buffer")
+    // gets its own cache entry so deeper subcommand navigation produces the
+    // correct, more-specific usage string rather than a stale parent-level one.
+    cachedCommandPath = null;
+    cachedHelp = null;
+    constructor(commandTree) {
+        this.commandTree = commandTree;
+    }
+    async fetchCompletions(line) {
+        return this.commandTree.getSuggestions(line).suggestions;
+    }
+    async fetchUsage(line) {
+        const result = this.commandTree.getSuggestions(line);
+        if (result.argumentHelp !== undefined) {
+            // Match the shape of the server's `cmdusage` response (e.g. "clear
+            // [<targets>] [<item>]") - formatArgumentHint derives the command
+            // prefix from this leading commandPath, so it must be present even
+            // when there's no argument help (e.g. "reload").
+            const usage = result.argumentHelp ? `${result.commandPath} ${result.argumentHelp}` : result.commandPath;
+            if (result.commandPath !== this.cachedCommandPath) {
+                this.cachedCommandPath = result.commandPath ?? null;
+                this.cachedHelp = usage;
+                return usage;
+            }
+            return this.cachedHelp ?? usage;
+        }
+        return this.cachedHelp ?? '';
+    }
+}
+exports.LocalCompletionBackend = LocalCompletionBackend;
+//# sourceMappingURL=completionBackend.js.map

package/out/completionEngine.js

@@ -0,0 +1,376 @@
+"use strict";
+// src/completionEngine.ts
+//
+// Pure decision core for server-side ("plugin mode") tab completion.
+//
+// This module knows nothing about VS Code, sockets, or wall-clock time — it's
+// a reducer: (Machine, Event) -> { machine: Machine, effects: Effect[] }. The
+// shell (RconSession) feeds it terminal events and executes the Effects it
+// returns (RCON sends, ANSI writes, applying text to the line). That makes
+// every async race in here something you can drive with a scripted event
+// sequence in a test, rather than something that happens to you against a
+// real server at 2am.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applySuggestion = applySuggestion;
+exports.longestCommonPrefix = longestCommonPrefix;
+exports.createMachine = createMachine;
+exports.step = step;
+const commandLine_1 = require("./commandLine");
+const completionQueries_1 = require("./completionQueries");
+// ───────────────────────── completion-list helpers ─────────────────────────
+/**
+ * Splices a raw completion candidate (e.g. "adventure", "distance=", "[")
+ * into the line as typed so far, the same way a real client reconciles a
+ * server-suggested replacement against partial input.
+ *
+ * The server only ever hands back the candidate text — never which part of
+ * the line it replaces — and that part isn't reliably "the last
+ * space-delimited word": selector/NBT syntax nests further completion
+ * boundaries inside a single token (typing "@a[dist" and completing to
+ * "@a[distance=" should only replace "dist"; typing the *complete* selector
+ * "@a" and getting "[" appended makes "@a[", where nothing of "@a" overlaps
+ * the candidate at all).
+ *
+ * So instead of guessing where the word boundary is, this finds the longest
+ * suffix of what's typed that the candidate continues (a prefix-overlap,
+ * checked longest-first so e.g. "dist" wins over the shorter-but-also-
+ * matching "t"), and splices the candidate in over just that overlap. An
+ * overlap of zero naturally degrades to appending — exactly right for
+ * refinement suggestions ("@a" + "[") and for completions chosen right after
+ * a trailing space ("adventure " + "@a").
+ */
+function applySuggestion(line, suggestionText) {
+    let overlap = 0;
+    for (let len = Math.min(line.length, suggestionText.length); len > 0; len--) {
+        if (suggestionText.startsWith(line.slice(line.length - len))) {
+            overlap = len;
+            break;
+        }
+    }
+    return line.slice(0, line.length - overlap) + suggestionText;
+}
+/** The longest string every item in `items` starts with (`''` if `items` is empty). */
+function longestCommonPrefix(items) {
+    if (items.length === 0) {
+        return '';
+    }
+    let prefix = items[0];
+    for (let i = 1; i < items.length && prefix.length > 0; i++) {
+        let len = 0;
+        const max = Math.min(prefix.length, items[i].length);
+        while (len < max && prefix[len] === items[i][len]) {
+            len++;
+        }
+        prefix = prefix.slice(0, len);
+    }
+    return prefix;
+}
+function usageMatches(usage, line) {
+    return usage.kind !== 'none' && usage.forQuery === line;
+}
+/**
+ * Once a command has resolved to a single usage line, that usage stays valid
+ * across further keystrokes that only change the *arguments* — the command
+ * portion itself doesn't change, and `formatArgumentHint` already recomputes
+ * which argument is highlighted purely from `(usage, line)`. "Covers" means
+ * the cached query's words are a prefix of the current line's words, i.e. the
+ * command portion hasn't changed (only what comes after it has, or the user
+ * is still extending it). An empty-text usage (ambiguous prefix or "too
+ * broad") never covers anything — there's nothing resolved to stick to, so
+ * the next natural pause point should ask again.
+ *
+ * Exception: if the usage's first argument token is a `(choice|list)` — a
+ * subcommand branch point — and the user has typed beyond the cached query,
+ * they have navigated *into* one of those choices and the usage is stale;
+ * argument values (`<foo>`, `[<foo>]`) don't trigger this.
+ */
+function usageCoversLine(usage, line) {
+    if (usage.kind !== 'ready' || usage.text === '') {
+        return false;
+    }
+    const cachedWords = (0, commandLine_1.splitCommandLine)(usage.forQuery).parts;
+    const lineWords = (0, commandLine_1.splitCommandLine)(line).parts;
+    if (lineWords.length < cachedWords.length) {
+        return false;
+    }
+    if (!cachedWords.every((word, i) => word === lineWords[i])) {
+        return false;
+    }
+    if (lineWords.length > cachedWords.length && /\([^)]+\)/.test(usage.text)) {
+        return false;
+    }
+    return true;
+}
+function createMachine() {
+    return { seq: 0, phase: { kind: 'closed' }, fetch: { kind: 'idle' } };
+}
+function step(m, event) {
+    switch (event.kind) {
+        case 'lineChanged': return onLineChanged(m, event.line);
+        case 'tab': return onTabOrShiftTab(m, event.line, 'tab');
+        case 'shiftTab': return onTabOrShiftTab(m, event.line, 'shiftTab');
+        case 'arrow': return onArrow(m, event.direction);
+        case 'selectIndex': return onSelectIndex(m, event.index);
+        case 'escape': return onEscape(m);
+        case 'completionsResult': return onCompletionsResult(m, event.requestId, event.items);
+        case 'usageResult': return onUsageResult(m, event.requestId, event.text);
+    }
+}
+function unchanged(m) { return { machine: m, effects: [] }; }
+function renderEffect(phase) {
+    return {
+        kind: 'render',
+        items: phase.items,
+        selectedIndex: phase.selectedIndex,
+        usage: phase.usage.kind === 'ready' ? phase.usage.text : null,
+    };
+}
+function closeAndHide(m) {
+    return { machine: { seq: m.seq, phase: { kind: 'closed' }, fetch: { kind: 'idle' } }, effects: [{ kind: 'hide' }] };
+}
+/** Issue a fresh `tabcomplete` fetch for `line` (used for first-time queries and re-derives after a queued line wins). */
+function fetchCompletionsFor(m, line, reason) {
+    const query = (0, completionQueries_1.buildCompletionsQuery)(line);
+    if (query === null) {
+        return closeAndHide(m);
+    }
+    const requestId = m.seq + 1;
+    const machine = {
+        seq: requestId,
+        phase: m.phase,
+        fetch: { kind: 'busy', requestId, purpose: { kind: 'completions', reason }, forLine: line, queued: null },
+    };
+    return { machine, effects: [{ kind: 'fetchCompletions', requestId, query }] };
+}
+/**
+ * Open `basePhase` while kicking off a background `cmdusage` fetch for
+ * `forLine`: marks the usage `loading`, allocates the request id, and returns
+ * the busy machine plus the `fetchUsage` + `render` effects. Centralizes the
+ * seq/requestId bookkeeping that several call sites would otherwise repeat.
+ * Callers must have already checked the wire is free (`fetch.kind === 'idle'`).
+ */
+function fetchUsageInBackground(m, basePhase, forLine, usageQuery) {
+    const requestId = m.seq + 1;
+    const phase = { ...basePhase, usage: { kind: 'loading', forQuery: forLine } };
+    return {
+        machine: { seq: requestId, phase, fetch: { kind: 'busy', requestId, purpose: { kind: 'usage' }, forLine, queued: null } },
+        effects: [{ kind: 'fetchUsage', requestId, query: usageQuery }, renderEffect(phase)],
+    };
+}
+// ── lineChanged: the user typed or erased a character ──
+function onLineChanged(m, line) {
+    const query = (0, completionQueries_1.buildCompletionsQuery)(line);
+    if (query === null) {
+        if (m.phase.kind === 'closed' && m.fetch.kind === 'idle') {
+            return unchanged(m);
+        }
+        return closeAndHide(m);
+    }
+    if (m.fetch.kind === 'busy') {
+        // RCON serializes requests — only one fetch in flight at a time. Remember
+        // the newest input and refetch for it once the outstanding one resolves.
+        return { machine: { ...m, fetch: { ...m.fetch, queued: { line, reason: 'typing' } } }, effects: [] };
+    }
+    return fetchCompletionsFor(m, line, 'typing');
+}
+// ── tab / shiftTab ──
+function onTabOrShiftTab(m, line, which) {
+    const query = (0, completionQueries_1.buildCompletionsQuery)(line);
+    if (query === null) {
+        return m.phase.kind === 'open'
+            ? { machine: { ...m, phase: { kind: 'closed' } }, effects: [{ kind: 'hide' }] }
+            : unchanged(m);
+    }
+    const phase = m.phase;
+    const delta = which === 'tab' ? 1 : -1;
+    // Already cycling and nothing's been typed since the last suggestion was
+    // applied: advance to the next/previous item. This is an exact comparison
+    // (not a time window) — as soon as the line diverges from what was applied,
+    // we fall through and re-derive for the new line instead.
+    if (phase.kind === 'open' && phase.mode.kind === 'cycling' && phase.items.length > 0
+        && line === applySuggestion(phase.query, phase.items[phase.selectedIndex])) {
+        return advance(m, phase, phase.selectedIndex, delta);
+    }
+    // We already have fresh items for exactly this input — they were pulled
+    // live as the user typed, so there's no need to hit the server again.
+    if (phase.kind === 'open' && phase.query === line && phase.items.length > 0) {
+        // First Tab with multiple candidates: if they share a prefix longer than
+        // what's typed, complete to that prefix (bash-style) and leave the list
+        // open — a follow-up Tab with nothing further to gain falls through to
+        // cycling below. A single candidate's "common prefix" is itself, but
+        // that case is left to the cycling branch, which already fills it in
+        // (and fetches its usage line) on the first press.
+        if (which === 'tab' && phase.items.length > 1) {
+            const lcp = longestCommonPrefix(phase.items);
+            const completed = applySuggestion(line, lcp);
+            if (completed !== line) {
+                const newPhase = { ...phase, query: completed };
+                return { machine: { ...m, phase: newPhase }, effects: [{ kind: 'applySuggestion', text: lcp }, renderEffect(newPhase)] };
+            }
+        }
+        // Tab keeps the existing selection (e.g. from arrow keys); Shift-Tab steps
+        // back from it — both rules match the pre-refactor behavior.
+        const base = (phase.selectedIndex >= 0 && phase.selectedIndex < phase.items.length) ? phase.selectedIndex : 0;
+        const initialDelta = which === 'tab' ? 0 : -1;
+        return advance(m, phase, base, initialDelta, /* maybeFetchUsage */ true);
+    }
+    // Need fresh completions from the server, but only one fetch at a time —
+    // e.g. a background usage fetch may still be outstanding. Remember what the
+    // user actually wants and act on it the moment the wire frees up, rather
+    // than silently swallowing the keypress.
+    if (m.fetch.kind === 'busy') {
+        return { machine: { ...m, fetch: { ...m.fetch, queued: { line, reason: which } } }, effects: [] };
+    }
+    return fetchCompletionsFor(m, line, which);
+}
+function advance(m, phase, baseIndex, delta, maybeFetchUsage = false) {
+    const selectedIndex = (baseIndex + delta + phase.items.length) % phase.items.length;
+    const newPhase = { ...phase, selectedIndex, mode: { kind: 'cycling' } };
+    const applyEffect = { kind: 'applySuggestion', text: phase.items[selectedIndex] };
+    // The usage line is purely supplementary — fetch it in the background
+    // (once the wire is free) rather than making the user wait on it before
+    // the completion itself is applied.
+    if (maybeFetchUsage && !usageMatches(newPhase.usage, phase.query) && m.fetch.kind === 'idle') {
+        const usageQuery = (0, completionQueries_1.buildUsageQuery)(phase.query);
+        if (usageQuery !== null) {
+            const usageStep = fetchUsageInBackground(m, newPhase, phase.query, usageQuery);
+            return { machine: usageStep.machine, effects: [applyEffect, ...usageStep.effects] };
+        }
+    }
+    return { machine: { ...m, phase: newPhase }, effects: [applyEffect, renderEffect(newPhase)] };
+}
+// ── arrow keys: browse the list without committing to anything ──
+function onArrow(m, direction) {
+    if (m.phase.kind !== 'open' || m.phase.items.length === 0) {
+        return unchanged(m);
+    }
+    const { items, selectedIndex } = m.phase;
+    const delta = direction === 'down' ? 1 : -1;
+    const next = (selectedIndex + delta + items.length) % items.length;
+    const newPhase = { ...m.phase, selectedIndex: next, mode: { kind: 'preview' } };
+    return { machine: { ...m, phase: newPhase }, effects: [renderEffect(newPhase)] };
+}
+// ── jump/page: shell-computed target index, same "just browsing" semantics as arrows ──
+function onSelectIndex(m, index) {
+    if (m.phase.kind !== 'open' || index < 0 || index >= m.phase.items.length) {
+        return unchanged(m);
+    }
+    const newPhase = { ...m.phase, selectedIndex: index, mode: { kind: 'preview' } };
+    return { machine: { ...m, phase: newPhase }, effects: [renderEffect(newPhase)] };
+}
+// ── escape: close, restoring the pre-completion line if we'd applied one ──
+function onEscape(m) {
+    if (m.phase.kind !== 'open') {
+        return unchanged(m);
+    }
+    const effects = [];
+    if (m.phase.mode.kind === 'cycling') {
+        effects.push({ kind: 'restoreLine', text: m.phase.query });
+    }
+    effects.push({ kind: 'hide' });
+    return { machine: { ...m, phase: { kind: 'closed' } }, effects };
+}
+// ── server replies ──
+function onCompletionsResult(m, requestId, items) {
+    if (m.fetch.kind !== 'busy' || m.fetch.requestId !== requestId || m.fetch.purpose.kind !== 'completions') {
+        return unchanged(m); // stale/superseded response — ignore
+    }
+    const { forLine, queued, purpose } = m.fetch;
+    if (queued !== null) {
+        // The user has since moved on to different input (or pressed Tab again) —
+        // discard these results and immediately act on what they actually want now.
+        return fetchCompletionsFor(m, queued.line, queued.reason);
+    }
+    if (items.length === 0) {
+        if (purpose.reason !== 'typing') {
+            return closeAndHide(m);
+        }
+        // No completions for this input, but it still looks like a command in
+        // progress — rather than closing, show what argument comes next (e.g.
+        // "/gamemode creative " has no completions for the target selector, but
+        // there's still a usage hint worth displaying). Mirrors the "open with an
+        // empty item list, fill in usage in the background" shape used elsewhere.
+        const usageQuery = (0, completionQueries_1.buildUsageQuery)(forLine);
+        if (usageQuery === null) {
+            return closeAndHide(m);
+        }
+        const basePhase = {
+            kind: 'open', query: forLine, items: [], selectedIndex: -1,
+            usage: { kind: 'none' }, mode: { kind: 'preview' },
+        };
+        return fetchUsageInBackground(m, basePhase, forLine, usageQuery);
+    }
+    if (purpose.reason === 'typing') {
+        // Preserve the existing selection across re-fetches if still in range —
+        // keeps arrow-key navigation stable while the user keeps typing.
+        const previous = m.phase.kind === 'open' ? m.phase.selectedIndex : -1;
+        const selectedIndex = (previous >= 0 && previous < items.length) ? previous : 0;
+        // Sticky usage: once a command has resolved to a single usage line, keep
+        // showing it across further keystrokes within that same command — only
+        // the highlighted argument changes, which formatArgumentHint derives
+        // purely from (usage, line), no fetch needed. A new command (or one that
+        // hasn't resolved yet) starts fresh — the old usage no longer applies.
+        const carriedUsage = (m.phase.kind === 'open' && usageCoversLine(m.phase.usage, forLine))
+            ? m.phase.usage
+            : { kind: 'none' };
+        const basePhase = { kind: 'open', query: forLine, items, selectedIndex, usage: carriedUsage, mode: { kind: 'preview' } };
+        // Nothing resolved for this command yet, but the line looks like a
+        // natural pause point — the user just finished a token (trailing space),
+        // the same "word boundary" signal the empty-completions hint-phase above
+        // keys off. Worth asking whether it's now resolved to a single command.
+        // (Asking on *every* keystroke would double the round trips per
+        // character typed — the sticky cache plus this pause-point trigger keeps
+        // it to roughly one usage fetch per command, not one per character.)
+        if (carriedUsage.kind === 'none' && forLine.endsWith(' ')) {
+            const usageQuery = (0, completionQueries_1.buildUsageQuery)(forLine);
+            if (usageQuery !== null) {
+                return fetchUsageInBackground(m, basePhase, forLine, usageQuery);
+            }
+        }
+        return { machine: { ...m, phase: basePhase, fetch: { kind: 'idle' } }, effects: [renderEffect(basePhase)] };
+    }
+    // First Tab landing fresh completions for multiple candidates: same
+    // common-prefix completion as the "items already on hand" path in
+    // onTabOrShiftTab, just reached via a server round trip instead.
+    if (purpose.reason === 'tab' && items.length > 1) {
+        const lcp = longestCommonPrefix(items);
+        const completed = applySuggestion(forLine, lcp);
+        if (completed !== forLine) {
+            const phase = {
+                kind: 'open', query: completed, items, selectedIndex: 0,
+                usage: { kind: 'none' }, mode: { kind: 'preview' },
+            };
+            return { machine: { ...m, phase, fetch: { kind: 'idle' } }, effects: [{ kind: 'applySuggestion', text: lcp }, renderEffect(phase)] };
+        }
+    }
+    // purpose.reason is 'tab' or 'shiftTab': apply a suggestion right away and
+    // enter cycling mode; fetch the usage line afterwards without blocking on it.
+    const selectedIndex = purpose.reason === 'shiftTab' ? items.length - 1 : 0;
+    const basePhase = {
+        kind: 'open', query: forLine, items, selectedIndex,
+        usage: { kind: 'none' }, mode: { kind: 'cycling' },
+    };
+    const applyEffect = { kind: 'applySuggestion', text: items[selectedIndex] };
+    const usageQuery = (0, completionQueries_1.buildUsageQuery)(forLine);
+    if (usageQuery === null) {
+        return { machine: { ...m, phase: basePhase, fetch: { kind: 'idle' } }, effects: [applyEffect, renderEffect(basePhase)] };
+    }
+    const usageStep = fetchUsageInBackground(m, basePhase, forLine, usageQuery);
+    return { machine: usageStep.machine, effects: [applyEffect, ...usageStep.effects] };
+}
+function onUsageResult(m, requestId, text) {
+    if (m.fetch.kind !== 'busy' || m.fetch.requestId !== requestId || m.fetch.purpose.kind !== 'usage') {
+        return unchanged(m);
+    }
+    const { forLine, queued } = m.fetch;
+    if (queued !== null) {
+        return fetchCompletionsFor(m, queued.line, queued.reason);
+    }
+    if (m.phase.kind !== 'open' || m.phase.query !== forLine) {
+        // The list has moved on (closed, or now showing a different query) — discard.
+        return { machine: { ...m, fetch: { kind: 'idle' } }, effects: [] };
+    }
+    const phase = { ...m.phase, usage: { kind: 'ready', forQuery: forLine, text } };
+    return { machine: { ...m, phase, fetch: { kind: 'idle' } }, effects: [renderEffect(phase)] };
+}
+//# sourceMappingURL=completionEngine.js.map

package/out/completionQueries.js

@@ -0,0 +1,86 @@
+"use strict";
+// src/completionQueries.ts
+//
+// Pure adapters between an input line and the server-side TabComplete plugin's
+// `tabcomplete`/`cmdusage` wire format: build the argument string to send, and
+// parse the response back. No state and no dependency on the completion state
+// machine — shared by both `completionEngine` (which builds queries) and
+// `RconCompletionBackend` (which builds queries and parses responses), so the
+// backend needn't pull in the reducer just for these.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCompletionsQuery = buildCompletionsQuery;
+exports.buildUsageQuery = buildUsageQuery;
+exports.parseCompletionsResponse = parseCompletionsResponse;
+exports.parseUsageResponse = parseUsageResponse;
+const ansi_1 = require("./ansi");
+const commandLine_1 = require("./commandLine");
+/**
+ * Builds the argument string to send to the `tabcomplete` plugin command for
+ * a given input line, or null if the line isn't a command at all.
+ *
+ * A trailing "-" is the plugin's convention for "the user typed a trailing
+ * space here" (some RCON clients strip trailing whitespace before it reaches
+ * the plugin). A bare "-" with no other parts asks for root-level completions:
+ * Brigadier suggests by prefix-matching the *remaining* input, and an empty
+ * remaining string matches every root command name.
+ */
+function buildCompletionsQuery(input) {
+    if (input.startsWith('.')) {
+        return input;
+    } // builtin commands: pass through for local handling
+    if (!input.startsWith('/')) {
+        return null;
+    }
+    const { parts, hasTrailingSpace } = (0, commandLine_1.splitCommandLine)(input);
+    if (parts.length === 0) {
+        return '-';
+    }
+    return hasTrailingSpace ? `${parts.join(' ')} -` : parts.join(' ');
+}
+/** Builds the argument string for `cmdusage`, or null if there's nothing to ask about yet. */
+function buildUsageQuery(input) {
+    if (!input.startsWith('/')) {
+        return null;
+    }
+    const withoutSlash = input.slice(1).trim();
+    return withoutSlash.length > 0 ? withoutSlash : null;
+}
+/** Every failure/meta message from both `tabcomplete` and `cmdusage` starts with "(". */
+function isFailureResponse(response) {
+    return !response || response.trim().startsWith('(');
+}
+function parseCompletionsResponse(response) {
+    if (isFailureResponse(response)) {
+        return [];
+    }
+    return response.split('\n').map(s => s.trim()).filter(s => s.length > 0);
+}
+/**
+ * `cmdusage` resolves an input to one of three shapes: a clean failure like
+ * "(too broad — use /help mvp or provide a subcommand)" (caught above), a
+ * single matching command's usage line, or — when the input is still an
+ * ambiguous prefix of multiple subcommands (e.g. "mvp c" matching both "mvp
+ * create" and "mvp config") — one usage line per candidate, newline-separated.
+ *
+ * Only the single-match shape represents *the* usage for what's been typed —
+ * multiple candidates means the command still hasn't resolved to one thing,
+ * so (same as the explicit failure case) there's nothing unambiguous to show
+ * yet. This is the actual "is there a single usage line" signal — the server
+ * already does the resolution; we just need to recognize its shape.
+ *
+ * `cmdusage` echoes the command's help text verbatim, Minecraft `§` color
+ * codes and all (e.g. "§b§bmvp create§b §a <portal-name> [destination]"). The
+ * hint display applies its own ANSI styling on top of the plain usage string,
+ * so any embedded color codes need to come out here, at the parsing boundary
+ * — otherwise they show up as literal `§b` noise mixed in with our own escapes.
+ */
+function parseUsageResponse(response) {
+    if (isFailureResponse(response)) {
+        return '';
+    }
+    const lines = response.split('\n')
+        .map(line => (0, ansi_1.stripColors)(line).trim())
+        .filter(line => line.length > 0);
+    return lines.length === 1 ? lines[0] : '';
+}
+//# sourceMappingURL=completionQueries.js.map

package/out/completionsBackend.js

@@ -0,0 +1,97 @@
+"use strict";
+// src/completionsBackend.ts
+//
+// The completionEngine state machine knows it needs completions and usage
+// text for a given input line — it doesn't know or care whether those come
+// from a network round trip or an in-memory lookup. A CompletionsBackend is
+// that boundary: one implementation asks the server-side TabComplete
+// plugin over RCON, the other asks the locally-built command tree.
+//
+// Driving both modes through the same backend interface (and therefore the
+// same engine, the same dispatch plumbing, and the same rendering) is what
+// lets RconSession be entirely mode-blind — "which backend" is decided once,
+// not branched on at every call site.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalCompletionsBackend = exports.RconCompletionsBackend = void 0;
+const completionEngine_1 = require("./completionEngine");
+/**
+ * Server-side completions via the TabComplete plugin's `tabcomplete`/`cmdusage` commands.
+ *
+ * Takes a `controller` thunk rather than a fixed `RconController` — the
+ * connection manager replaces its controller wholesale on every reconnect, so
+ * capturing one instance up front would silently start sending through a dead
+ * (disconnected) controller after the first reconnect, with every fetch
+ * throwing "Not connected" (swallowed by the caller as "no completions").
+ * Looking it up fresh on each call always reaches whatever's live.
+ */
+class RconCompletionsBackend {
+    getController;
+    constructor(getController) {
+        this.getController = getController;
+    }
+    async fetchCompletions(line) {
+        const query = (0, completionEngine_1.buildCompletionsQuery)(line);
+        if (query === null) {
+            return [];
+        }
+        const response = await this.getController().send(`tabcomplete ${query}`);
+        return (0, completionEngine_1.parseCompletionsResponse)(response ?? undefined);
+    }
+    async fetchUsage(line) {
+        const query = (0, completionEngine_1.buildUsageQuery)(line);
+        if (query === null) {
+            return '';
+        }
+        const response = await this.getController().send(`cmdusage ${query}`);
+        return (0, completionEngine_1.parseUsageResponse)(response ?? undefined);
+    }
+}
+exports.RconCompletionsBackend = RconCompletionsBackend;
+/**
+ * Local completions via the command tree LocalCommandTree builds at
+ * startup — a synchronous in-memory lookup, wrapped in `async` so it flows
+ * through exactly the same dispatch path as the RCON backend (the `await`
+ * still yields to the microtask queue, so a `dispatchToEngine` call made from
+ * here lands *after* the effect loop that triggered it has finished — same
+ * ordering guarantee the real async backend gets for free from the network).
+ */
+class LocalCompletionsBackend {
+    commandTree;
+    // getSuggestions sometimes returns incomplete argument help for inputs that
+    // are mid-command (e.g. once the user is typing a free-form argument like a
+    // player name, the locally-built tree may not have anything to say). Stick
+    // with the first full version we saw for this command rather than flicker
+    // between that and "(nothing)" — mirrors the original local-mode behavior.
+    cachedCommand = null;
+    cachedHelp = null;
+    constructor(commandTree) {
+        this.commandTree = commandTree;
+    }
+    async fetchCompletions(line) {
+        return this.commandTree.getSuggestions(line).suggestions;
+    }
+    async fetchUsage(line) {
+        const result = this.commandTree.getSuggestions(line);
+        // Everything up to the first space, including any "namespace:" prefix -
+        // \S rather than \w so "minecraft:clear" isn't truncated to "minecraft".
+        const commandName = (line.match(/^\/?(\S+)/) || [])[1] || '';
+        if (commandName !== this.cachedCommand) {
+            this.cachedCommand = commandName;
+            this.cachedHelp = null;
+        }
+        if (result.argumentHelp !== undefined) {
+            // Match the shape of the server's `cmdusage` response (e.g. "clear
+            // [<targets>] [<item>]") - formatArgumentHint derives the command
+            // prefix from this leading commandPath, so it must be present even
+            // when there's no argument help (e.g. "reload").
+            const usage = result.argumentHelp ? `${result.commandPath} ${result.argumentHelp}` : result.commandPath;
+            if (this.cachedHelp === null) {
+                this.cachedHelp = usage;
+            }
+            return this.cachedHelp;
+        }
+        return this.cachedHelp ?? '';
+    }
+}
+exports.LocalCompletionsBackend = LocalCompletionsBackend;
+//# sourceMappingURL=completionsBackend.js.map