@nimbus-sh/core 0.1.0

package/dist/shell/features.js

@@ -0,0 +1,792 @@
+import { lex } from '../substrate/lifo/shell/lexer.js';
+import { TokenKind } from '../substrate/lifo/shell/types.js';
+export function parseHeredoc(input) {
+    const tokens = lex(input);
+    const delimiters = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token.kind === TokenKind.Heredoc || token.kind === TokenKind.HeredocStripTabs) {
+            const delimiter = tokens[i + 1];
+            if (!delimiter || delimiter.kind !== TokenKind.Word || !delimiter.value) {
+                return null;
+            }
+            delimiters.push({
+                delimiter: delimiter.value,
+                stripTabs: token.kind === TokenKind.HeredocStripTabs,
+            });
+        }
+    }
+    return delimiters.length > 0 ? { command: input, delimiters } : null;
+}
+export class HeredocHandler {
+    shell;
+    terminal;
+    originalExecuteLine = null;
+    originalPrintPrompt = null;
+    originalHandleInput = null;
+    // ── Accumulation state ──
+    active = false;
+    heredocInfo = null;
+    currentHeredocIndex = 0;
+    bodies = [];
+    historyLengthAtStart = 0;
+    /** Safety limit to prevent unbounded memory growth */
+    static MAX_HEREDOC_LINES = 50000;
+    constructor(shell, terminal) {
+        this.shell = shell;
+        this.terminal = terminal;
+    }
+    /**
+     * Install the heredoc handler on a Shell instance.
+     * Call once after the Shell is created.
+     */
+    static install(shell, terminal) {
+        const handler = new HeredocHandler(shell, terminal);
+        handler._patch();
+        return handler;
+    }
+    /** Cancel heredoc accumulation and return to normal shell prompt. */
+    _cancel() {
+        this.active = false;
+        this.heredocInfo = null;
+        this.currentHeredocIndex = 0;
+        this.bodies = [];
+        // Restore history to before the heredoc started (removes content lines)
+        if (this.shell.history) {
+            this.shell.history.length = this.historyLengthAtStart;
+        }
+    }
+    _patch() {
+        // Save originals (bound to shell)
+        this.originalExecuteLine = this.shell.executeLine.bind(this.shell);
+        this.originalPrintPrompt = this.shell.printPrompt.bind(this.shell);
+        this.originalHandleInput = this.shell.handleInput.bind(this.shell);
+        this.shell.handleInput = (data) => {
+            if (this.active && data === '\x03') {
+                this._cancel();
+                this.terminal.write('^C\r\n');
+                this._printPrompt();
+                return;
+            }
+            if (this.active && !this.shell.running && data.length > 1 && /[\r\n]/.test(data)) {
+                const parts = data.split(/\r\n|\r|\n/);
+                if (parts[0]) {
+                    this.shell.lineBuffer = this.shell.lineBuffer.slice(0, this.shell.cursorPos)
+                        + parts[0] + this.shell.lineBuffer.slice(this.shell.cursorPos);
+                    this.shell.cursorPos += parts[0].length;
+                }
+                if (parts.length > 1) {
+                    this.shell.redrawLine();
+                    this.terminal.write('\r\n');
+                    const currentLine = this.shell.lineBuffer;
+                    this.shell.lineBuffer = '';
+                    this.shell.cursorPos = 0;
+                    this.shell.screenCursorRow = 0;
+                    this.shell.historyIndex = -1;
+                    for (let i = 1; i < parts.length; i++) {
+                        if (i === parts.length - 1 && parts[i] === '')
+                            continue;
+                        this.shell.pasteQueue.push(parts[i]);
+                    }
+                    if (currentLine.trim()) {
+                        this.shell.history.push(currentLine.trim());
+                    }
+                    const isDelim = this._processLine(currentLine);
+                    if (isDelim && this.heredocInfo !== null) {
+                        this._finishHeredoc();
+                    }
+                    else if (!isDelim) {
+                        this.terminal.write('> ');
+                        this._drainPasteQueue();
+                    }
+                }
+                return;
+            }
+            if (this.active && !this.shell.running && data === '\r') {
+                this.terminal.write('\r\n');
+                const currentLine = this.shell.lineBuffer;
+                this.shell.lineBuffer = '';
+                this.shell.cursorPos = 0;
+                this.shell.screenCursorRow = 0;
+                this.shell.historyIndex = -1;
+                if (currentLine.trim()) {
+                    this.shell.history.push(currentLine.trim());
+                }
+                const isDelim = this._processLine(currentLine);
+                if (isDelim && this.heredocInfo !== null) {
+                    this._finishHeredoc();
+                }
+                else if (!isDelim) {
+                    this.terminal.write('> ');
+                }
+                return;
+            }
+            return this._handleOriginalInput(data);
+        };
+        this.shell.executeLine = async (line) => {
+            if (this.active) {
+                const current = this._currentDelimiter();
+                const rawLine = (current?.stripTabs && this.shell.lineBuffer)
+                    ? this.shell.lineBuffer
+                    : line;
+                await this._accumulateLine(rawLine);
+                return;
+            }
+            const info = parseHeredoc(line);
+            if (info) {
+                await this._startAccumulation(info);
+                return;
+            }
+            return this._executeOriginalLine(line);
+        };
+        this.shell.printPrompt = () => {
+            if (this.active) {
+                this._accumulateLine('');
+                return;
+            }
+            return this._printPrompt();
+        };
+    }
+    _printPrompt() {
+        const printPrompt = this.originalPrintPrompt;
+        if (printPrompt)
+            printPrompt();
+    }
+    _handleOriginalInput(data) {
+        const handleInput = this.originalHandleInput;
+        if (handleInput)
+            handleInput(data);
+    }
+    async _executeOriginalLine(line) {
+        const executeLine = this.originalExecuteLine;
+        if (!executeLine) {
+            throw new Error('heredoc handler is not installed');
+        }
+        await executeLine(line);
+    }
+    async _startAccumulation(info) {
+        this.active = true;
+        this.heredocInfo = info;
+        this.currentHeredocIndex = 0;
+        this.bodies = info.delimiters.map(() => []);
+        this.historyLengthAtStart = this.shell.history?.length ?? 0;
+        this.terminal.write('> ');
+        await this._drainPasteQueue();
+    }
+    /**
+     * Process a single heredoc content line (non-recursive).
+     * Returns true if this was the delimiter (heredoc is complete).
+     */
+    _processLine(line) {
+        const delimiter = this._currentDelimiter();
+        if (!delimiter)
+            return true;
+        const cleaned = line.replace(/[\r\n]+$/, '');
+        const checkLine = delimiter.stripTabs ? stripLeadingTabs(cleaned) : cleaned;
+        if (checkLine === delimiter.delimiter) {
+            this.currentHeredocIndex++;
+            return this.currentHeredocIndex >= this.bodies.length;
+        }
+        const lines = this.bodies[this.currentHeredocIndex];
+        if (!lines || lines.length >= HeredocHandler.MAX_HEREDOC_LINES) {
+            this.terminal.write(`\x1b[31mheredoc: exceeded ${HeredocHandler.MAX_HEREDOC_LINES} line limit\x1b[0m\r\n`);
+            this._cancel();
+            this._printPrompt();
+            return true; // stop accumulation
+        }
+        const processedLine = delimiter.stripTabs ? stripLeadingTabs(cleaned) : cleaned;
+        lines.push(processedLine);
+        return false;
+    }
+    /**
+     * Called when executeLine fires during accumulation (user typed a line + Enter).
+     * Also called during paste processing.
+     */
+    async _accumulateLine(line) {
+        if (this._processLine(line)) {
+            if (this.heredocInfo === null)
+                return; // limit exceeded, already cancelled
+            await this._finishHeredoc();
+            return;
+        }
+        this.terminal.write('> ');
+    }
+    /**
+     * Drain the Shell's pasteQueue during heredoc accumulation.
+     * When a multi-line heredoc is pasted, all lines land in the paste queue.
+     * Uses an iterative loop (not recursive) to avoid stack overflow.
+     */
+    async _drainPasteQueue() {
+        const queue = this.shell.pasteQueue;
+        if (!queue || queue.length === 0)
+            return;
+        while (this.active && queue.length > 0) {
+            const nextLine = queue.shift();
+            if (nextLine === undefined)
+                break;
+            this.terminal.write(nextLine + '\r\n');
+            if (this._processLine(nextLine)) {
+                if (this.heredocInfo === null)
+                    return; // limit exceeded
+                await this._finishHeredoc();
+                return;
+            }
+            this.terminal.write('> ');
+        }
+    }
+    async _finishHeredoc() {
+        const info = this.heredocInfo;
+        if (!info)
+            return;
+        const script = [
+            info.command,
+            ...info.delimiters.flatMap((delimiter, index) => {
+                const lines = this.bodies[index] ?? [];
+                return lines.length > 0 ? [lines.join('\n'), delimiter.delimiter] : [delimiter.delimiter];
+            }),
+            '',
+        ].join('\n');
+        this.active = false;
+        this.heredocInfo = null;
+        this.currentHeredocIndex = 0;
+        this.bodies = [];
+        if (this.shell.history) {
+            this.shell.history.length = this.historyLengthAtStart;
+        }
+        try {
+            await this._executeOriginalLine(script);
+        }
+        catch (error) {
+            this.terminal.write(`\x1b[31mheredoc error: ${errorMessage(error)}\x1b[0m\r\n`);
+            this._printPrompt();
+            this.shell.drainPasteQueue();
+        }
+    }
+    _currentDelimiter() {
+        return this.heredocInfo?.delimiters[this.currentHeredocIndex] ?? null;
+    }
+}
+function stripLeadingTabs(input) {
+    let i = 0;
+    while (input[i] === '\t')
+        i++;
+    return input.slice(i);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+// ── Line-editor extension (readline parity) ─────────────────────────────
+/**
+ * LineEditorExtender — adds bash-readline-parity keybindings to the
+ * Nimbus shell line editor.
+ *
+ * The vanilla Shell handles only a minimal set: ←/→/↑/↓, Home, End,
+ * Ctrl+A, Ctrl+E, Ctrl+C, Ctrl+D (EOF), Ctrl+U (whole-line wipe), Tab,
+ * Enter, Backspace, Delete. Every other readline binding (Ctrl+W,
+ * Ctrl+K, Ctrl+Y, Alt+B, Alt+F, Alt+D, Ctrl+←, Alt+. , Ctrl+R, etc.)
+ * gets dropped on the floor.
+ *
+ * This handler wraps `shell.handleInput` to recognise the missing
+ * sequences and apply their readline-spec semantics directly to
+ * `shell.lineBuffer` / `shell.cursorPos` / `shell.history`, then
+ * triggers `shell.redrawLine()` to re-render.
+ *
+ * Install AFTER HeredocHandler so the heredoc wrapper sees input
+ * first (its mode is exclusive); when heredoc isn't active our
+ * handler runs.
+ *
+ * Word boundary conventions (matches bash 5.x readline):
+ *   - Ctrl+W (unix-word-rubout): whitespace boundary — bash override
+ *   - Alt+Backspace (backward-kill-word): readline word `[A-Za-z0-9_]+`
+ *   - Alt+B / Alt+F (backward/forward-word): readline word
+ *   - Ctrl+← / Ctrl+→ (alias for word nav): readline word
+ *   - Alt+D (kill-word): readline word
+ *
+ * Kill-ring: simple single-slot (the most-recent cut). Ctrl+Y yanks it.
+ *
+ * Ctrl+R sub-mode: enters reverse-i-search; capturing chars narrows
+ * the match against history; Enter runs the matched line; Esc/Ctrl+G
+ * aborts; another Ctrl+R steps to the next-older match.
+ */
+export class LineEditorExtender {
+    shell;
+    terminal;
+    originalHandleInput = null;
+    /** Single-slot kill-ring. Set by Ctrl+W / Ctrl+K / Ctrl+U / Alt+Backspace / Alt+D. */
+    killRing = '';
+    /** Yank-last-arg state — index into `history` (from the end), most
+     *  recent = 0. Reset when the user types anything other than Alt+. */
+    yankLastArgIndex = -1;
+    /** Length of the inserted last-arg blob from the previous Alt+. press
+     *  so a follow-up Alt+. can remove it and insert the older one. */
+    yankLastArgInsertedLen = 0;
+    /** Reverse-i-search sub-mode state. */
+    rsearchActive = false;
+    rsearchQuery = '';
+    /** History index (from end) of the currently-displayed match;
+     *  -1 = no match, otherwise points at `history[history.length-1-idx]`. */
+    rsearchMatchIndex = -1;
+    /** Match readline's word definition: ASCII alphanumerics + underscore. */
+    static isWordChar(ch) {
+        if (!ch)
+            return false;
+        const c = ch.charCodeAt(0);
+        return ((c >= 0x30 && c <= 0x39) || // 0-9
+            (c >= 0x41 && c <= 0x5a) || // A-Z
+            (c >= 0x61 && c <= 0x7a) || // a-z
+            c === 0x5f // _
+        );
+    }
+    constructor(shell, terminal) {
+        this.shell = shell;
+        this.terminal = terminal;
+    }
+    static install(shell, terminal) {
+        const handler = new LineEditorExtender(shell, terminal);
+        handler._patch();
+        return handler;
+    }
+    _patch() {
+        this.originalHandleInput = this.shell.handleInput.bind(this.shell);
+        this.shell.handleInput = (data) => {
+            // Skip when a process is running — the line editor only governs
+            // shell-prompt input. Process-stdin input has its own model
+            // (terminalStdin / stdinLineBuffer) handled by the shell.
+            if (this.shell.running) {
+                return this.originalHandleInput(data);
+            }
+            // Reverse-i-search sub-mode owns ALL input until exited.
+            if (this.rsearchActive) {
+                this._rsearchHandle(data);
+                return;
+            }
+            // Yank-last-arg state is reset on any non-Alt+. input.
+            if (data !== '\x1b.') {
+                this.yankLastArgIndex = -1;
+                this.yankLastArgInsertedLen = 0;
+            }
+            // Try each binding. First-match wins; on no match fall through.
+            if (this._handleBinding(data))
+                return;
+            return this.originalHandleInput(data);
+        };
+    }
+    /**
+     * Returns true if the input was a recognised readline binding and we
+     * handled it; false to fall through to the original handler.
+     */
+    _handleBinding(data) {
+        const s = this.shell;
+        switch (data) {
+            // ── char-by-char navigation (readline Ctrl aliases) ──
+            case '\x02': // Ctrl+B → left
+                if (s.cursorPos > 0) {
+                    s.cursorPos--;
+                    s.redrawLine();
+                }
+                return true;
+            case '\x06': // Ctrl+F → right
+                if (s.cursorPos < s.lineBuffer.length) {
+                    s.cursorPos++;
+                    s.redrawLine();
+                }
+                return true;
+            // ── Home/End (Linux variants the upstream Shell misses) ──
+            case '\x1b[1~': // Home (vt220 / Linux)
+            case '\x1b[7~': // Home (rxvt)
+                s.cursorPos = 0;
+                s.redrawLine();
+                return true;
+            case '\x1b[4~': // End (vt220 / Linux)
+            case '\x1b[8~': // End (rxvt)
+                s.cursorPos = s.lineBuffer.length;
+                s.redrawLine();
+                return true;
+            // ── word-by-word navigation ──
+            case '\x1b[1;5D': // Ctrl+←  (xterm modifier-5)
+            case '\x1b[1;3D': // Alt+←   (xterm modifier-3, Mac Option+←)
+            case '\x1bb': // Alt+B / Esc-b
+            case '\x1bB':
+                s.cursorPos = this._prevWordStart(s.lineBuffer, s.cursorPos);
+                s.redrawLine();
+                return true;
+            case '\x1b[1;5C': // Ctrl+→
+            case '\x1b[1;3C': // Alt+→
+            case '\x1bf': // Alt+F / Esc-f
+            case '\x1bF':
+                s.cursorPos = this._nextWordEnd(s.lineBuffer, s.cursorPos);
+                s.redrawLine();
+                return true;
+            // ── history aliases ──
+            case '\x10': // Ctrl+P → ↑
+                // Delegate to the existing handler for ↑ which already manages
+                // historyIndex/savedLine bookkeeping.
+                return this.originalHandleInput('\x1b[A'), true;
+            case '\x0e': // Ctrl+N → ↓
+                return this.originalHandleInput('\x1b[B'), true;
+            // ── kill-to-end (Ctrl+K) ──
+            case '\x0b':
+                if (s.cursorPos < s.lineBuffer.length) {
+                    this.killRing = s.lineBuffer.slice(s.cursorPos);
+                    s.lineBuffer = s.lineBuffer.slice(0, s.cursorPos);
+                    s.redrawLine();
+                }
+                return true;
+            // ── kill-to-start (Ctrl+U) — override the upstream whole-line wipe ──
+            case '\x15':
+                if (s.cursorPos > 0) {
+                    this.killRing = s.lineBuffer.slice(0, s.cursorPos);
+                    s.lineBuffer = s.lineBuffer.slice(s.cursorPos);
+                    s.cursorPos = 0;
+                    s.redrawLine();
+                }
+                // cursorPos === 0 + non-empty line: bash's Ctrl+U here also kills
+                // the whole line (cursor was already at start, "to start" = 0).
+                // Falling through to the upstream whole-line wipe is wrong for
+                // mid-line case but correct for the start case. Since we
+                // returned true above only when something was cut, the
+                // start-of-empty case falls through to upstream which is fine
+                // (whole line is already empty). For non-empty-at-start, we
+                // also return true to avoid double-redraw.
+                return true;
+            // ── kill-word-back (Ctrl+W) — bash uses WHITESPACE boundary ──
+            case '\x17': {
+                if (s.cursorPos === 0)
+                    return true;
+                const buf = s.lineBuffer;
+                let i = s.cursorPos;
+                // Skip trailing whitespace BEFORE the cursor.
+                while (i > 0 && /\s/.test(buf[i - 1]))
+                    i--;
+                // Then skip non-whitespace (the "word").
+                while (i > 0 && !/\s/.test(buf[i - 1]))
+                    i--;
+                this.killRing = buf.slice(i, s.cursorPos);
+                s.lineBuffer = buf.slice(0, i) + buf.slice(s.cursorPos);
+                s.cursorPos = i;
+                s.redrawLine();
+                return true;
+            }
+            // ── kill-word-back (Alt+Backspace) — readline word boundary ──
+            case '\x1b\x7f':
+            case '\x1b\x08': {
+                if (s.cursorPos === 0)
+                    return true;
+                const buf = s.lineBuffer;
+                const newPos = this._prevWordStart(buf, s.cursorPos);
+                this.killRing = buf.slice(newPos, s.cursorPos);
+                s.lineBuffer = buf.slice(0, newPos) + buf.slice(s.cursorPos);
+                s.cursorPos = newPos;
+                s.redrawLine();
+                return true;
+            }
+            // ── kill-word-forward (Alt+D) — readline word boundary ──
+            case '\x1bd':
+            case '\x1bD': {
+                const buf = s.lineBuffer;
+                if (s.cursorPos >= buf.length)
+                    return true;
+                const newPos = this._nextWordEnd(buf, s.cursorPos);
+                this.killRing = buf.slice(s.cursorPos, newPos);
+                s.lineBuffer = buf.slice(0, s.cursorPos) + buf.slice(newPos);
+                // cursor stays at s.cursorPos (chars removed AFTER cursor)
+                s.redrawLine();
+                return true;
+            }
+            // ── yank (Ctrl+Y) ──
+            case '\x19': {
+                if (!this.killRing)
+                    return true;
+                const buf = s.lineBuffer;
+                s.lineBuffer = buf.slice(0, s.cursorPos) + this.killRing + buf.slice(s.cursorPos);
+                s.cursorPos += this.killRing.length;
+                s.redrawLine();
+                return true;
+            }
+            // ── transpose (Ctrl+T) ──
+            case '\x14': {
+                const buf = s.lineBuffer;
+                if (buf.length < 2)
+                    return true;
+                let pos = s.cursorPos;
+                // bash behaviour: at end of line, swap last two chars without
+                // advancing the cursor. Mid-line: swap char-before with
+                // char-at, advance cursor by one.
+                if (pos >= buf.length) {
+                    const a = buf[buf.length - 2];
+                    const b = buf[buf.length - 1];
+                    s.lineBuffer = buf.slice(0, -2) + b + a;
+                }
+                else if (pos === 0) {
+                    // bash: bell, no-op.
+                    return true;
+                }
+                else {
+                    const before = buf[pos - 1];
+                    const at = buf[pos];
+                    s.lineBuffer = buf.slice(0, pos - 1) + at + before + buf.slice(pos + 1);
+                    s.cursorPos = pos + 1;
+                }
+                s.redrawLine();
+                return true;
+            }
+            // ── Ctrl+L: clear screen, redraw current line ──
+            case '\x0c':
+                // \x1b[H = cursor to top-left, \x1b[2J = erase screen
+                this.terminal.write('\x1b[H\x1b[2J');
+                // Reset the screen-row tracker so redrawLine doesn't try to
+                // ANSI-up past the (now-cleared) top of screen.
+                s.screenCursorRow = 0;
+                s.redrawLine();
+                return true;
+            // ── Ctrl+D mid-line: delete char at cursor (bash readline) ──
+            case '\x04': {
+                const buf = s.lineBuffer;
+                // If line is non-empty AND cursor not at end, delete char at cursor.
+                if (s.cursorPos < buf.length) {
+                    s.lineBuffer = buf.slice(0, s.cursorPos) + buf.slice(s.cursorPos + 1);
+                    s.redrawLine();
+                    return true;
+                }
+                // Otherwise fall through to the upstream handler (which treats
+                // Ctrl+D on an empty line as EOF / no-op).
+                return false;
+            }
+            // ── Alt+. — yank-last-arg ──
+            case '\x1b.': {
+                return this._yankLastArg();
+            }
+            // ── Alt+U / Alt+L / Alt+C — uppercase / lowercase / capitalize word ──
+            case '\x1bu':
+            case '\x1bU':
+                return this._caseTransformWord('upper');
+            case '\x1bl':
+            case '\x1bL':
+                return this._caseTransformWord('lower');
+            case '\x1bc':
+            case '\x1bC':
+                return this._caseTransformWord('capitalize');
+            // ── Ctrl+R — enter reverse-i-search ──
+            case '\x12':
+                this._rsearchEnter();
+                return true;
+        }
+        return false;
+    }
+    // ── Word-boundary helpers ──
+    /** Move from `pos` to the start of the previous readline word. */
+    _prevWordStart(buf, pos) {
+        let i = pos;
+        // Skip non-word chars (whitespace, punctuation) backward.
+        while (i > 0 && !LineEditorExtender.isWordChar(buf[i - 1]))
+            i--;
+        // Then skip the word backward.
+        while (i > 0 && LineEditorExtender.isWordChar(buf[i - 1]))
+            i--;
+        return i;
+    }
+    /** Move from `pos` to the end of the next readline word. */
+    _nextWordEnd(buf, pos) {
+        let i = pos;
+        // Skip non-word chars forward.
+        while (i < buf.length && !LineEditorExtender.isWordChar(buf[i]))
+            i++;
+        // Then skip the word forward.
+        while (i < buf.length && LineEditorExtender.isWordChar(buf[i]))
+            i++;
+        return i;
+    }
+    // ── Case transforms ──
+    _caseTransformWord(mode) {
+        const s = this.shell;
+        const buf = s.lineBuffer;
+        let i = s.cursorPos;
+        // Skip non-word forward.
+        while (i < buf.length && !LineEditorExtender.isWordChar(buf[i]))
+            i++;
+        const wordStart = i;
+        while (i < buf.length && LineEditorExtender.isWordChar(buf[i]))
+            i++;
+        const wordEnd = i;
+        if (wordEnd === wordStart)
+            return true; // no word to transform
+        const word = buf.slice(wordStart, wordEnd);
+        let transformed;
+        if (mode === 'upper')
+            transformed = word.toUpperCase();
+        else if (mode === 'lower')
+            transformed = word.toLowerCase();
+        else
+            transformed = word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+        s.lineBuffer = buf.slice(0, wordStart) + transformed + buf.slice(wordEnd);
+        s.cursorPos = wordEnd;
+        s.redrawLine();
+        return true;
+    }
+    // ── Yank-last-arg (Alt+.) ──
+    _yankLastArg() {
+        const s = this.shell;
+        const history = s.history ?? [];
+        if (history.length === 0)
+            return true;
+        // Advance the history index. First press → 0 (most-recent).
+        // Repeat press → 1 (previous), 2, ... wrap at end.
+        this.yankLastArgIndex = (this.yankLastArgIndex < 0)
+            ? 0
+            : Math.min(this.yankLastArgIndex + 1, history.length - 1);
+        const histLine = history[history.length - 1 - this.yankLastArgIndex] ?? '';
+        // bash: "last arg" = the LAST whitespace-delimited word of the
+        // previous command (after expansion). We don't expand here; the
+        // raw last word is what users expect.
+        const m = histLine.match(/(\S+)\s*$/);
+        const lastArg = m ? m[1] : '';
+        const buf = s.lineBuffer;
+        // Remove the previous Alt+. insertion (if any) before inserting
+        // the next.
+        const removedFrom = s.cursorPos - this.yankLastArgInsertedLen;
+        const removedTo = s.cursorPos;
+        const newBuf = buf.slice(0, removedFrom) + lastArg + buf.slice(removedTo);
+        s.lineBuffer = newBuf;
+        s.cursorPos = removedFrom + lastArg.length;
+        this.yankLastArgInsertedLen = lastArg.length;
+        s.redrawLine();
+        return true;
+    }
+    // ── Reverse-i-search (Ctrl+R sub-mode) ──
+    _rsearchEnter() {
+        this.rsearchActive = true;
+        this.rsearchQuery = '';
+        this.rsearchMatchIndex = -1;
+        this._rsearchRender();
+    }
+    _rsearchHandle(data) {
+        const s = this.shell;
+        // Esc / Ctrl+G → abort, keep the partial line buffer as it was.
+        if (data === '\x1b' || data === '\x07') {
+            this._rsearchExit(/*restoreLine=*/ true);
+            return;
+        }
+        // Enter → accept the current match and execute it.
+        if (data === '\r' || data === '\n') {
+            const accepted = this._rsearchCurrentMatch();
+            this._rsearchExit(/*restoreLine=*/ false);
+            if (accepted) {
+                s.lineBuffer = accepted;
+                s.cursorPos = accepted.length;
+            }
+            s.redrawLine();
+            // Defer to the original handler to execute the (now-restored)
+            // line. Sending '\r' triggers the same path Enter would.
+            this.originalHandleInput('\r');
+            return;
+        }
+        // Another Ctrl+R → step to the next-older match.
+        if (data === '\x12') {
+            this._rsearchAdvance();
+            this._rsearchRender();
+            return;
+        }
+        // Backspace / Ctrl+H → remove last query char and re-search.
+        if (data === '\x7f' || data === '\x08') {
+            this.rsearchQuery = this.rsearchQuery.slice(0, -1);
+            this.rsearchMatchIndex = -1; // restart search from most-recent
+            this._rsearchSearch();
+            this._rsearchRender();
+            return;
+        }
+        // Any other escape sequence aborts (cursor arrows etc).
+        if (data.startsWith('\x1b')) {
+            // Bash: arrow keys exit search and keep the current match in
+            // the buffer for further editing.
+            const accepted = this._rsearchCurrentMatch();
+            this._rsearchExit(/*restoreLine=*/ false);
+            if (accepted) {
+                s.lineBuffer = accepted;
+                s.cursorPos = accepted.length;
+            }
+            s.redrawLine();
+            return;
+        }
+        // Ctrl+C → cancel out of search and clear the line.
+        if (data === '\x03') {
+            this._rsearchExit(/*restoreLine=*/ true);
+            s.lineBuffer = '';
+            s.cursorPos = 0;
+            this.terminal.write('^C\r\n');
+            // Use the shell's prompt path.
+            if (typeof s.printPrompt === 'function')
+                s.printPrompt();
+            return;
+        }
+        // Otherwise: append printable to the query and search.
+        if (data >= ' ' && !data.startsWith('\x1b')) {
+            this.rsearchQuery += data;
+            this.rsearchMatchIndex = -1;
+            this._rsearchSearch();
+            this._rsearchRender();
+        }
+    }
+    /** Step the match index forward (older) and re-search from there. */
+    _rsearchAdvance() {
+        const history = this.shell.history ?? [];
+        let idx = this.rsearchMatchIndex < 0 ? 0 : this.rsearchMatchIndex + 1;
+        for (; idx < history.length; idx++) {
+            const line = history[history.length - 1 - idx];
+            if (line && line.includes(this.rsearchQuery)) {
+                this.rsearchMatchIndex = idx;
+                return;
+            }
+        }
+        // No further match — keep the current one.
+    }
+    /** Find the most-recent history line containing the query. */
+    _rsearchSearch() {
+        if (!this.rsearchQuery) {
+            this.rsearchMatchIndex = -1;
+            return;
+        }
+        const history = this.shell.history ?? [];
+        for (let idx = 0; idx < history.length; idx++) {
+            const line = history[history.length - 1 - idx];
+            if (line && line.includes(this.rsearchQuery)) {
+                this.rsearchMatchIndex = idx;
+                return;
+            }
+        }
+        this.rsearchMatchIndex = -1;
+    }
+    _rsearchCurrentMatch() {
+        if (this.rsearchMatchIndex < 0)
+            return null;
+        const history = this.shell.history ?? [];
+        return history[history.length - 1 - this.rsearchMatchIndex] ?? null;
+    }
+    /** Render the search-prompt line. */
+    _rsearchRender() {
+        const match = this._rsearchCurrentMatch();
+        // Clear the current screen row + redraw the search prompt.
+        this.terminal.write('\r\x1b[K');
+        if (match) {
+            this.terminal.write(`(reverse-i-search)\`${this.rsearchQuery}': ${match}`);
+        }
+        else {
+            this.terminal.write(`(failed reverse-i-search)\`${this.rsearchQuery}': `);
+        }
+    }
+    /**
+     * Exit the search sub-mode. If `restoreLine` is true, the line
+     * buffer is left as it was when search began (no insertion). The
+     * caller is expected to call `redrawLine()` afterward if needed.
+     */
+    _rsearchExit(restoreLine) {
+        this.rsearchActive = false;
+        this.rsearchQuery = '';
+        this.rsearchMatchIndex = -1;
+        // Clear the search prompt line.
+        this.terminal.write('\r\x1b[K');
+        if (restoreLine) {
+            // Caller wants the original buffer kept; nothing to do here —
+            // the caller will redraw.
+        }
+    }
+}