neonctl 2.22.2 → 2.23.1

package/psql/io/lineEditor/buffer.js

@@ -0,0 +1,323 @@
+/**
+ * Pure line-buffer state for the psql line editor.
+ *
+ * We avoid an actual gap buffer because edited lines are short (~100 chars
+ * typical, a few KB worst case for pasted SQL) and JavaScript string
+ * concatenation is fast enough at that scale. The "buffer-ish" API still
+ * exposes insert/delete-at-cursor primitives so callers stay code-point
+ * aware rather than byte aware.
+ *
+ * Everything in this module operates on Unicode *code points*. Internally
+ * we store the line as an array of code-point strings (each element is one
+ * scalar value, typically one UTF-16 code unit but two for astral chars).
+ * The `cursor` is an index into that array, in the range `[0, length]`.
+ *
+ * Editing primitives mutate the state in place and push the previous
+ * snapshot onto the undo stack. Killed text (^K, ^U, ^W) is appended to
+ * the most recent kill ring entry when killing continues in the same
+ * direction; yank pulls from the most recent entry.
+ *
+ * No I/O, no rendering, no terminal awareness — that lives in
+ * `keymap.ts` / `index.ts`. Tests cover this module exhaustively.
+ */
+/**
+ * Encode a string as an array of code-point characters. Each element is
+ * one Unicode scalar (`"A"`, `"é"`, `"\u{1F600}"`). This lets cursor
+ * arithmetic stay code-point-aligned without dealing with surrogate pairs
+ * at every callsite.
+ */
+const toCodePoints = (s) => Array.from(s);
+/**
+ * Pure line buffer plus kill ring plus undo. Used by the keymap layer.
+ */
+export class LineBuffer {
+    constructor(initial = '', cursor) {
+        /** One code point per element. */
+        this.chars = [];
+        /** Code-point index in `[0, chars.length]`. */
+        this._cursor = 0;
+        /** Most-recent-first ring of killed text. Bounded to keep memory sane. */
+        this.killRing = [];
+        /** Index into killRing for the next yank-pop (^Y / Alt-Y). */
+        this.yankIndex = -1;
+        /** Direction of the previous kill so consecutive kills concatenate. */
+        this.lastKill = 'none';
+        /** Snapshots for ^_ / undo. */
+        this.undoStack = [];
+        this.chars = toCodePoints(initial);
+        this._cursor =
+            cursor === undefined ? this.chars.length : this.clampCursor(cursor);
+    }
+    // -------------------------------------------------------------------------
+    // Accessors
+    // -------------------------------------------------------------------------
+    get text() {
+        return this.chars.join('');
+    }
+    get cursor() {
+        return this._cursor;
+    }
+    get length() {
+        return this.chars.length;
+    }
+    snapshot() {
+        return { text: this.text, cursor: this._cursor };
+    }
+    restore(snap) {
+        this.chars = toCodePoints(snap.text);
+        this._cursor = this.clampCursor(snap.cursor);
+        this.lastKill = 'none';
+    }
+    /**
+     * Replace the entire buffer in one go. Used when navigating history or
+     * accepting a completion. Does NOT push an undo entry on its own — call
+     * `pushUndo()` first if you want to record the previous state.
+     */
+    setText(text, cursor) {
+        this.chars = toCodePoints(text);
+        this._cursor =
+            cursor === undefined ? this.chars.length : this.clampCursor(cursor);
+        this.lastKill = 'none';
+    }
+    // -------------------------------------------------------------------------
+    // Cursor movement (all in code points, never bytes / UTF-16 units)
+    // -------------------------------------------------------------------------
+    moveLeft() {
+        if (this._cursor > 0)
+            this._cursor--;
+        this.lastKill = 'none';
+    }
+    moveRight() {
+        if (this._cursor < this.chars.length)
+            this._cursor++;
+        this.lastKill = 'none';
+    }
+    moveHome() {
+        this._cursor = 0;
+        this.lastKill = 'none';
+    }
+    moveEnd() {
+        this._cursor = this.chars.length;
+        this.lastKill = 'none';
+    }
+    /**
+     * Move left over one word. Word ≙ run of alphanumerics. Skip the
+     * non-alphanumerics immediately to the left first (matches readline's
+     * `M-b`). Pure stdlib `\w` is locale-sensitive in some runtimes; we
+     * use a `RegExp` against the actual code-point string.
+     */
+    moveWordLeft() {
+        let i = this._cursor;
+        while (i > 0 && !isWordChar(this.chars[i - 1]))
+            i--;
+        while (i > 0 && isWordChar(this.chars[i - 1]))
+            i--;
+        this._cursor = i;
+        this.lastKill = 'none';
+    }
+    moveWordRight() {
+        let i = this._cursor;
+        while (i < this.chars.length && !isWordChar(this.chars[i]))
+            i++;
+        while (i < this.chars.length && isWordChar(this.chars[i]))
+            i++;
+        this._cursor = i;
+        this.lastKill = 'none';
+    }
+    // -------------------------------------------------------------------------
+    // Insertion / deletion
+    // -------------------------------------------------------------------------
+    /** Insert a string at the cursor (split into code points first). */
+    insert(s) {
+        if (s.length === 0)
+            return;
+        this.pushUndo();
+        const cps = toCodePoints(s);
+        this.chars.splice(this._cursor, 0, ...cps);
+        this._cursor += cps.length;
+        this.lastKill = 'none';
+    }
+    /** Backspace: delete the code point to the left of cursor. */
+    deleteLeft() {
+        if (this._cursor === 0)
+            return;
+        this.pushUndo();
+        this.chars.splice(this._cursor - 1, 1);
+        this._cursor--;
+        this.lastKill = 'none';
+    }
+    /** Delete the code point to the right of cursor. */
+    deleteRight() {
+        if (this._cursor === this.chars.length)
+            return;
+        this.pushUndo();
+        this.chars.splice(this._cursor, 1);
+        this.lastKill = 'none';
+    }
+    // -------------------------------------------------------------------------
+    // Kill ring operations
+    // -------------------------------------------------------------------------
+    /** ^K: kill from cursor to end-of-line. Appends if previous kill was forward. */
+    killToEnd() {
+        if (this._cursor === this.chars.length)
+            return;
+        this.pushUndo();
+        const killed = this.chars.slice(this._cursor).join('');
+        this.chars.length = this._cursor;
+        this.recordKill(killed, 'forward');
+    }
+    /** ^U: kill from start-of-line to cursor. */
+    killToStart() {
+        if (this._cursor === 0)
+            return;
+        this.pushUndo();
+        const killed = this.chars.slice(0, this._cursor).join('');
+        this.chars.splice(0, this._cursor);
+        this._cursor = 0;
+        this.recordKill(killed, 'backward');
+    }
+    /** ^W: kill the word (backward) to the left of cursor. */
+    killWordLeft() {
+        if (this._cursor === 0)
+            return;
+        let i = this._cursor;
+        while (i > 0 && !isWordChar(this.chars[i - 1]))
+            i--;
+        while (i > 0 && isWordChar(this.chars[i - 1]))
+            i--;
+        if (i === this._cursor)
+            return;
+        this.pushUndo();
+        const killed = this.chars.slice(i, this._cursor).join('');
+        this.chars.splice(i, this._cursor - i);
+        this._cursor = i;
+        this.recordKill(killed, 'backward');
+    }
+    /** M-d: kill the word (forward) starting at cursor. */
+    killWordRight() {
+        if (this._cursor === this.chars.length)
+            return;
+        let i = this._cursor;
+        while (i < this.chars.length && !isWordChar(this.chars[i]))
+            i++;
+        while (i < this.chars.length && isWordChar(this.chars[i]))
+            i++;
+        if (i === this._cursor)
+            return;
+        this.pushUndo();
+        const killed = this.chars.slice(this._cursor, i).join('');
+        this.chars.splice(this._cursor, i - this._cursor);
+        this.recordKill(killed, 'forward');
+    }
+    /** ^Y: yank most recent kill at cursor. No-op if ring is empty. */
+    yank() {
+        if (this.killRing.length === 0)
+            return undefined;
+        const top = this.killRing[0];
+        this.insert(top);
+        this.yankIndex = 0;
+        return top;
+    }
+    /**
+     * M-y: rotate yank ring. Caller must have just yanked. Removes the
+     * previously yanked text and inserts the next entry from the ring.
+     */
+    yankPop(prevYank) {
+        if (this.killRing.length === 0)
+            return undefined;
+        this.yankIndex = (this.yankIndex + 1) % this.killRing.length;
+        if (this._cursor < prevYank.length)
+            return undefined;
+        const start = this._cursor - toCodePoints(prevYank).length;
+        this.pushUndo();
+        this.chars.splice(start, toCodePoints(prevYank).length);
+        this._cursor = start;
+        const next = this.killRing[this.yankIndex];
+        const cps = toCodePoints(next);
+        this.chars.splice(this._cursor, 0, ...cps);
+        this._cursor += cps.length;
+        return next;
+    }
+    /** Reset the kill-merge tracker. Called when a non-kill action runs. */
+    resetKillTracking() {
+        this.lastKill = 'none';
+    }
+    /** Test helper / introspection. */
+    getKillRing() {
+        return this.killRing;
+    }
+    // -------------------------------------------------------------------------
+    // Undo
+    // -------------------------------------------------------------------------
+    /** Push the current state onto the undo stack. */
+    pushUndo() {
+        this.undoStack.push({ text: this.text, cursor: this._cursor });
+        if (this.undoStack.length > LineBuffer.UNDO_STACK_MAX) {
+            this.undoStack.shift();
+        }
+    }
+    /** ^_: pop the most recent snapshot. Returns true if anything happened. */
+    undo() {
+        const snap = this.undoStack.pop();
+        if (!snap)
+            return false;
+        this.chars = toCodePoints(snap.text);
+        this._cursor = this.clampCursor(snap.cursor);
+        this.lastKill = 'none';
+        return true;
+    }
+    // -------------------------------------------------------------------------
+    // Internals
+    // -------------------------------------------------------------------------
+    clampCursor(c) {
+        if (c < 0)
+            return 0;
+        if (c > this.chars.length)
+            return this.chars.length;
+        return c;
+    }
+    recordKill(text, dir) {
+        if (text.length === 0)
+            return;
+        if (this.lastKill === dir && this.killRing.length > 0) {
+            // Merge with the previous kill so consecutive ^K / ^W feel like one
+            // logical kill in the yank ring.
+            this.killRing[0] =
+                dir === 'forward' ? this.killRing[0] + text : text + this.killRing[0];
+        }
+        else {
+            this.killRing.unshift(text);
+            if (this.killRing.length > LineBuffer.KILL_RING_MAX) {
+                this.killRing.length = LineBuffer.KILL_RING_MAX;
+            }
+        }
+        this.lastKill = dir;
+        this.yankIndex = -1;
+    }
+}
+LineBuffer.KILL_RING_MAX = 32;
+LineBuffer.UNDO_STACK_MAX = 256;
+/**
+ * Word character classifier. Matches readline's default: ASCII alphanumeric
+ * plus underscore. Non-ASCII letters are treated as word chars too so
+ * "señor" moves as one word.
+ */
+const isWordChar = (ch) => {
+    if (ch.length === 0)
+        return false;
+    const cp = ch.codePointAt(0) ?? 0;
+    if (cp >= 0x30 && cp <= 0x39)
+        return true; // 0-9
+    if (cp >= 0x41 && cp <= 0x5a)
+        return true; // A-Z
+    if (cp >= 0x61 && cp <= 0x7a)
+        return true; // a-z
+    if (cp === 0x5f)
+        return true; // _
+    if (cp > 0x7f) {
+        // Treat any non-ASCII printable as word-ish; cheap heuristic but
+        // sufficient for editor word motion.
+        return cp >= 0xa0;
+    }
+    return false;
+};

package/psql/io/lineEditor/complete.js

@@ -0,0 +1,227 @@
+/**
+ * Tab-completion plumbing for the line editor.
+ *
+ * Holds the small bit of state that lives between consecutive Tab presses
+ * (last completion result, cycle index, last-tab timestamp). The renderer
+ * calls `apply` on each Tab; the function mutates the buffer in place and
+ * returns a `CompletionStep` telling the driver whether to ring the bell,
+ * insert text, or list candidates below the prompt.
+ *
+ * State machine:
+ *
+ *   - First Tab: ask the completer. If 0 candidates → `bell`. If 1, insert
+ *     it. If >1, insert the common prefix (if any) and remember the result.
+ *   - Second Tab within DOUBLE_TAP_MS: emit a `list` action so the driver
+ *     prints the candidates below the prompt.
+ *   - Third Tab and onward: cycle through candidates. The previously
+ *     inserted candidate is removed before inserting the next.
+ *
+ * Any non-Tab keystroke (handled by the keymap) calls `reset()` to drop
+ * the completion state.
+ */
+/** Threshold for "second Tab" detection. Roughly 500ms by spec. */
+const DOUBLE_TAP_MS = 500;
+export class CompletionState {
+    constructor() {
+        /** Most recent completion result. Reset to null after non-Tab input. */
+        this.result = null;
+        /** When the previous tab fired. */
+        this.lastTapAt = 0;
+        /** How many tabs in a row (the first tab inserts prefix; second lists). */
+        this.tabCount = 0;
+        /**
+         * When cycling, the index of the candidate currently inserted in the
+         * buffer. -1 means "no candidate inserted yet (common prefix only)".
+         */
+        this.cycleIndex = -1;
+        /** Length (in code points) of the candidate currently inserted. */
+        this.cycleLen = 0;
+    }
+    reset() {
+        this.result = null;
+        this.tabCount = 0;
+        this.cycleIndex = -1;
+        this.cycleLen = 0;
+        this.lastTapAt = 0;
+    }
+    /**
+     * Index of the candidate currently inserted in the buffer, or `-1` if no
+     * specific candidate is active (e.g. the user has only seen the common
+     * prefix). Used by the listing renderer to reverse-video the active
+     * candidate while cycling.
+     */
+    getCycleIndex() {
+        return this.cycleIndex;
+    }
+    /** Snapshot of the candidate list, for re-rendering during a cycle. */
+    getCandidates() {
+        return this.result?.candidates ?? [];
+    }
+    async apply(buffer, completer, now = Date.now()) {
+        const elapsed = now - this.lastTapAt;
+        this.lastTapAt = now;
+        if (this.result === null || elapsed > DOUBLE_TAP_MS * 4) {
+            // Fresh start: ask the completer.
+            const res = await Promise.resolve(completer(buffer.text, buffer.cursor));
+            this.result = res;
+            this.tabCount = 1;
+            this.cycleIndex = -1;
+            this.cycleLen = 0;
+            if (res.candidates.length === 0)
+                return { kind: 'bell' };
+            if (res.candidates.length === 1) {
+                // Mirror upstream readline: a unique completion gets a trailing space
+                // (rl_completion_append_character defaults to ' ') unless the result
+                // explicitly suppresses it (e.g. schema prefix `public.` that the user
+                // is expected to continue typing through) or the candidate itself
+                // already ends in a punctuator that shouldn't be followed by a space.
+                const cand = res.candidates[0];
+                const text = shouldAppendSpace(cand, res) ? cand + ' ' : cand;
+                replaceBeforeCursor(buffer, res.replaceLength, text);
+                this.reset();
+                return { kind: 'inserted' };
+            }
+            // Multiple candidates: insert the common prefix when it differs from
+            // what's currently in the buffer at that position. The diff can be
+            // length (more chars to insert) OR case (COMP_KEYWORD_CASE flipping
+            // `CO` to `co`) — both should redraw with the canonical form so the
+            // user sees what they'd commit on the next keystroke.
+            const before = buffer.text.slice(buffer.cursor - res.replaceLength, buffer.cursor);
+            if (res.commonPrefix !== before) {
+                replaceBeforeCursor(buffer, res.replaceLength, res.commonPrefix);
+            }
+            // Update the "what's currently inserted" to the common prefix length
+            // so the cycle path knows how many code points to overwrite when it
+            // swaps in the next candidate.
+            this.cycleLen = countCodePoints(res.commonPrefix);
+            return { kind: 'inserted' };
+        }
+        // We already have a result, and the second Tab arrived in time.
+        this.tabCount++;
+        if (this.tabCount === 2 && elapsed <= DOUBLE_TAP_MS) {
+            // List the candidates.
+            return { kind: 'list', candidates: this.result.candidates.slice() };
+        }
+        // Third or later: cycle.
+        const cands = this.result.candidates;
+        this.cycleIndex = (this.cycleIndex + 1) % cands.length;
+        const cand = cands[this.cycleIndex];
+        replaceBeforeCursor(buffer, this.cycleLen, cand);
+        this.cycleLen = countCodePoints(cand);
+        return { kind: 'cycled', candidate: cand };
+    }
+}
+/**
+ * Replace `replaceLen` code points before cursor with `text`. The buffer
+ * loses an undo entry per call; that's intentional so Ctrl-_ can undo a
+ * mistaken completion.
+ */
+const replaceBeforeCursor = (buffer, replaceLen, text) => {
+    // Move left over the bytes we're replacing, delete them, then insert.
+    for (let i = 0; i < replaceLen; i++)
+        buffer.deleteLeft();
+    buffer.insert(text);
+};
+const countCodePoints = (s) => Array.from(s).length;
+/**
+ * Decide whether to append a trailing space after a unique completion.
+ * Mirrors upstream readline's `rl_completion_append_character` convention:
+ * default is `' '`, but psql clears it for partial completions the user
+ * is expected to continue typing (schema prefix, open-quoted identifier,
+ * directory path).
+ *
+ * Rules:
+ *   - If the result explicitly sets `suppressTrailingSpace: true`, don't.
+ *   - Candidates already ending in whitespace are left untouched.
+ *   - Candidates ending in `.`, `/`, `(` are "in progress" (schema
+ *     namespace, path component, function open-paren) — no space.
+ *   - Candidates ending in `'` or `"` get a space only when quote count
+ *     is BALANCED (closed string / closed quoted identifier). An odd
+ *     count means the user is still inside the quoted region.
+ *   - Everything else gets a space.
+ */
+const shouldAppendSpace = (candidate, result) => {
+    if (result.suppressTrailingSpace === true)
+        return false;
+    if (candidate.length === 0)
+        return false;
+    const last = candidate[candidate.length - 1];
+    if (last === ' ' || last === '\t' || last === '\n')
+        return false;
+    if (last === '.' || last === '/' || last === '(')
+        return false;
+    if (last === '"') {
+        // Even count means quotes are balanced (e.g. `"mixedName"`) — completed
+        // identifier, append a space. Odd count means we're still inside an
+        // open quote (e.g. `"foo`) — leave the user to type more.
+        const count = countChar(candidate, '"');
+        return count % 2 === 0;
+    }
+    if (last === "'") {
+        const count = countChar(candidate, "'");
+        return count % 2 === 0;
+    }
+    return true;
+};
+const countChar = (s, ch) => {
+    let n = 0;
+    for (const c of s)
+        if (c === ch)
+            n++;
+    return n;
+};
+// ---------------------------------------------------------------------------
+// Listing helper: format candidates in column layout for display.
+// ---------------------------------------------------------------------------
+/** ANSI reverse-video escape (SGR 7) used to mark the active candidate. */
+const SGR_REVERSE = '\x1b[7m';
+const SGR_NO_REVERSE = '\x1b[27m';
+/**
+ * Lay out candidates into a multi-column block. Returns the formatted
+ * string (without a trailing newline — caller decides). Columns are sized
+ * to fit `termWidth`; we use the longest candidate plus a 2-space gutter.
+ *
+ * Falls back to one-per-line if `termWidth` is too narrow.
+ *
+ * If `highlightIndex` is provided and points to a valid candidate, that
+ * candidate is wrapped in `\x1b[7m...\x1b[27m` (reverse video) so the user
+ * can see which entry is currently inserted in the line during a Tab cycle.
+ * Out-of-range indices are silently ignored.
+ */
+export const formatCandidates = (candidates, termWidth, highlightIndex) => {
+    if (candidates.length === 0)
+        return '';
+    const maxLen = candidates.reduce((m, c) => Math.max(m, c.length), 0);
+    const colWidth = maxLen + 2;
+    const cols = Math.max(1, Math.floor(termWidth / colWidth));
+    const rows = Math.ceil(candidates.length / cols);
+    const hl = highlightIndex !== undefined &&
+        highlightIndex >= 0 &&
+        highlightIndex < candidates.length
+        ? highlightIndex
+        : -1;
+    const lines = [];
+    for (let r = 0; r < rows; r++) {
+        const parts = [];
+        for (let c = 0; c < cols; c++) {
+            const idx = r * cols + c;
+            if (idx >= candidates.length)
+                break;
+            const cand = candidates[idx];
+            const padded = cand + ' '.repeat(colWidth - cand.length);
+            if (idx === hl) {
+                // Wrap only the candidate text, not the gutter spaces, so adjacent
+                // columns don't get a colored stripe between them.
+                parts.push(SGR_REVERSE +
+                    cand +
+                    SGR_NO_REVERSE +
+                    ' '.repeat(colWidth - cand.length));
+            }
+            else {
+                parts.push(padded);
+            }
+        }
+        lines.push(parts.join('').trimEnd());
+    }
+    return lines.join('\n');
+};