@pugi/cli 0.1.0-alpha.6 → 0.1.0-alpha.8

package/dist/core/auto-open-browser.js

@@ -0,0 +1,128 @@
+import { spawn } from 'node:child_process';
+/**
+ * Open `url` in the default browser. Returns `{ opened: true }` on a
+ * successful spawn, `{ opened: false }` on any failure. The url is not
+ * shell-escaped here; we always pass it as a single argv element to a
+ * direct spawn (no shell), so quoting is irrelevant.
+ */
+export async function autoOpenBrowser(url, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const spawnDetached = deps.spawnDetached ?? defaultSpawnDetached;
+    // Refuse anything that does not parse as http(s). The device-flow URL
+    // is always https — guarding here keeps a hostile server response
+    // from convincing us to spawn `open file:///etc/passwd` or worse.
+    if (!isSafeHttpUrl(url)) {
+        return { opened: false };
+    }
+    if (platform === 'darwin') {
+        return { opened: spawnDetached('open', [url]) };
+    }
+    if (platform === 'win32') {
+        // P1-3 (triple-review 2026-05-24): cmd.exe parses `&` as a command
+        // separator BEFORE Node hands argv to the child, regardless of
+        // `shell: false`. A device-flow URL like
+        // `https://app.pugi.io/devices/authorize?user_code=ABC&trace=xyz`
+        // would be truncated at the `&`, opening only the first half. We
+        // prefer PowerShell (its argv parser is sane: a single quoted URL
+        // round-trips verbatim) and fall back to a double-quoted cmd
+        // invocation when PowerShell is missing from PATH.
+        if (spawnDetached('powershell', [
+            '-NoProfile',
+            '-NonInteractive',
+            '-Command',
+            'Start-Process',
+            quoteForPowerShell(url),
+        ])) {
+            return { opened: true };
+        }
+        // Fallback: `cmd /c start "" "<url>"`. The URL itself is wrapped
+        // in double quotes so cmd does not split on `&`; any embedded `"`
+        // in the URL is escaped using cmd's caret-quote convention.
+        return {
+            opened: spawnDetached('cmd', ['/c', 'start', '""', quoteForCmd(url)]),
+        };
+    }
+    if (platform === 'linux' || platform === 'freebsd' || platform === 'openbsd') {
+        // Try xdg-open first (the freedesktop standard), then gio (GNOME),
+        // then a couple of well-known browsers as a last resort. Each
+        // attempt is a fresh spawn — if the binary is missing the helper
+        // returns false and we fall through.
+        for (const cmd of LINUX_OPENERS) {
+            if (spawnDetached(cmd, [url]))
+                return { opened: true };
+        }
+        return { opened: false };
+    }
+    // Unknown platform (android, aix, sunos…) — degrade gracefully.
+    return { opened: false };
+}
+const LINUX_OPENERS = ['xdg-open', 'gio', 'gnome-open', 'kde-open'];
+function isSafeHttpUrl(candidate) {
+    try {
+        const url = new URL(candidate);
+        return url.protocol === 'https:' || url.protocol === 'http:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * P1-3 (triple-review 2026-05-24): wrap a URL for PowerShell's
+ * `Start-Process` invocation. PowerShell's single-quote string literal
+ * does NOT process escape sequences; the only metachar inside is the
+ * single quote itself (escaped by doubling). URLs do not contain
+ * single quotes in practice, but the helper handles them defensively
+ * so future input shapes do not break.
+ */
+function quoteForPowerShell(url) {
+    return `'${url.replace(/'/g, "''")}'`;
+}
+/**
+ * P1-3 (triple-review 2026-05-24): wrap a URL for cmd.exe's
+ * `start ""` invocation. Double quotes pin the URL as a single token
+ * so cmd does NOT split on `&`, `|`, `^`, `<`, `>`. Embedded `"` (rare
+ * in URLs but defensible) is escaped via cmd's caret-quote convention:
+ * `^"`.
+ */
+function quoteForCmd(url) {
+    return `"${url.replace(/"/g, '^"')}"`;
+}
+/**
+ * Real spawn implementation. Detaches the child so the Pugi CLI can
+ * exit (or keep polling) without inheriting the browser's lifecycle.
+ * Returns `true` only when the spawn produced a pid; any error event
+ * (ENOENT for a missing binary, EACCES for a sandboxed permission
+ * denial) flips the result to `false`.
+ */
+function defaultSpawnDetached(cmd, args) {
+    try {
+        const options = {
+            detached: true,
+            stdio: 'ignore',
+            shell: false,
+        };
+        const child = spawn(cmd, args.slice(), options);
+        // P3 polish (triple-review 2026-05-24): swallow the async `error`
+        // event (ENOENT for a missing binary, EACCES for a sandboxed
+        // permission denial). The old `errored` flag was always false at
+        // the synchronous `return !errored` point (the `error` event is
+        // delivered later in the next tick), so the flag was dead. The
+        // listener is still required: without it, Node escalates the
+        // event to an unhandled-error and crashes the host process when
+        // the binary is missing.
+        child.on('error', () => undefined);
+        if (typeof child.pid !== 'number')
+            return false;
+        // unref so the parent event loop is not held open by the browser
+        // handle. The browser process continues independently.
+        child.unref();
+        // Callers treat `true` as best-effort: the fallback "Browser
+        // didn't open?" hint is always rendered, so a silent spawn
+        // failure still leaves the user a usable path.
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=auto-open-browser.js.map

package/dist/core/clipboard.js

@@ -0,0 +1,70 @@
+import { spawn } from 'node:child_process';
+/**
+ * Write `text` to the platform clipboard. Best-effort, async.
+ */
+export async function writeClipboard(text, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const spawnWrite = deps.spawnWrite ?? defaultSpawnWrite;
+    if (platform === 'darwin') {
+        const ok = await spawnWrite('pbcopy', [], text);
+        return { copied: ok };
+    }
+    if (platform === 'win32') {
+        // clip.exe is shipped with every Windows >= XP. UTF-16LE would be
+        // ideal, but a UTF-8 BOM-less write covers the ASCII subset that
+        // device-flow URLs use (no non-ASCII characters reach this path).
+        const ok = await spawnWrite('clip', [], text);
+        return { copied: ok };
+    }
+    if (platform === 'linux' || platform === 'freebsd' || platform === 'openbsd') {
+        // Wayland-native sessions usually have wl-copy and not xclip. Try
+        // wl-copy first if WAYLAND_DISPLAY is set, otherwise prefer xclip.
+        const order = process.env.WAYLAND_DISPLAY
+            ? ['wl-copy', 'xclip', 'xsel']
+            : ['xclip', 'wl-copy', 'xsel'];
+        for (const tool of order) {
+            const args = tool === 'xclip' ? ['-selection', 'clipboard'] : tool === 'xsel' ? ['--clipboard', '--input'] : [];
+            const ok = await spawnWrite(tool, args, text);
+            if (ok)
+                return { copied: true };
+        }
+        return { copied: false };
+    }
+    return { copied: false };
+}
+/**
+ * Real spawn. Writes `text` to the child's stdin and resolves with
+ * `true` only when the child exits 0. Errors (missing binary,
+ * permission denied, non-zero exit) flip the result to `false`.
+ */
+function defaultSpawnWrite(cmd, args, text) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
+        try {
+            const options = {
+                stdio: ['pipe', 'ignore', 'ignore'],
+                shell: false,
+            };
+            const child = spawn(cmd, args.slice(), options);
+            child.on('error', () => settle(false));
+            child.on('close', (code) => settle(code === 0));
+            const stdin = child.stdin;
+            if (!stdin) {
+                settle(false);
+                return;
+            }
+            stdin.on('error', () => settle(false));
+            stdin.end(text, 'utf8');
+        }
+        catch {
+            settle(false);
+        }
+    });
+}
+//# sourceMappingURL=clipboard.js.map

package/dist/core/repl/clipboard-read.js

@@ -0,0 +1,174 @@
+/**
+ * Best-effort clipboard READ helper - Sprint α6.14.
+ *
+ * Mirror of the clipboard WRITE helper but for the opposite
+ * direction. Powers Ctrl+V paste in the REPL input box: when the
+ * operator presses Ctrl+V we spawn the platform's paste binary
+ * (pbpaste / wl-paste / xclip -o / PowerShell Get-Clipboard) and
+ * insert the result at the cursor.
+ *
+ * Contract:
+ *   - Returns `{ text }` when the helper exited 0 with non-empty
+ *     stdout. Trailing single newline is stripped (clipboard
+ *     contents authored by the operator rarely include the trailing
+ *     LF the paste helpers append).
+ *   - Returns `{ text: null }` on any failure: missing binary,
+ *     non-zero exit, no $DISPLAY on headless Linux, EAGAIN.
+ *   - Never throws. Caller falls back to "Ctrl+V not available -
+ *     try right-click paste" hint.
+ *   - Targets node >= 20.
+ *
+ * Implementation note: we do NOT optimistically run all three Linux
+ * helpers in parallel - the cost of spawning xclip when wl-copy
+ * already produced text is small but visible (50ms+ each on cold
+ * cache). Ordering: WAYLAND_DISPLAY → wl-paste; otherwise xclip first.
+ */
+import { spawn } from 'node:child_process';
+export async function readClipboard(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const spawnRead = deps.spawnRead ?? defaultSpawnRead;
+    const env = deps.env ?? process.env;
+    if (platform === 'darwin') {
+        const text = await spawnRead('pbpaste', []);
+        return { text: normalise(text) };
+    }
+    if (platform === 'win32') {
+        // PowerShell is the universally available path. Get-Clipboard
+        // emits UTF-16 by default; the -Raw flag preserves newlines and
+        // returns one string.
+        const text = await spawnRead('powershell', ['-NoProfile', '-Command', 'Get-Clipboard -Raw']);
+        return { text: normalise(text) };
+    }
+    if (platform === 'linux' || platform === 'freebsd' || platform === 'openbsd') {
+        const order = env.WAYLAND_DISPLAY
+            ? ['wl-paste', 'xclip', 'xsel']
+            : ['xclip', 'wl-paste', 'xsel'];
+        for (const tool of order) {
+            const args = tool === 'xclip'
+                ? ['-selection', 'clipboard', '-o']
+                : tool === 'xsel'
+                    ? ['--clipboard', '--output']
+                    : ['--no-newline'];
+            const text = await spawnRead(tool, args);
+            if (text !== null && text.length > 0) {
+                return { text: normalise(text) };
+            }
+        }
+        return { text: null };
+    }
+    return { text: null };
+}
+function normalise(raw) {
+    if (raw === null)
+        return null;
+    if (raw.length === 0)
+        return null;
+    // Strip a single trailing LF the helpers often append. Multi-line
+    // pastes preserve interior newlines.
+    return raw.endsWith('\n') ? raw.slice(0, -1) : raw;
+}
+/**
+ * Hard cap on clipboard payload size. The paste helper streams stdout
+ * with no upper bound by default, so a pathologically large clipboard
+ * (e.g. a hostile actor's 500 MiB file URL list, or an accidental copy
+ * of a large binary) would OOM the CLI process if we kept appending.
+ * 1 MiB is plenty for any realistic prompt + code snippet paste and
+ * still leaves room in V8's default young-generation heap.
+ */
+const MAX_CLIPBOARD_BYTES = 1024 * 1024; // 1 MiB
+function defaultSpawnRead(cmd, args) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let overflow = false;
+        let totalBytes = 0;
+        const chunks = [];
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
+        try {
+            const options = {
+                stdio: ['ignore', 'pipe', 'ignore'],
+                shell: false,
+            };
+            const child = spawn(cmd, args.slice(), options);
+            child.on('error', () => settle(null));
+            child.stdout?.on('data', (b) => {
+                if (overflow)
+                    return;
+                totalBytes += b.length;
+                if (totalBytes > MAX_CLIPBOARD_BYTES) {
+                    overflow = true;
+                    try {
+                        child.kill('SIGTERM');
+                    }
+                    catch {
+                        // Best effort; close handler still settles below.
+                    }
+                    return;
+                }
+                chunks.push(b);
+            });
+            child.on('close', (code) => {
+                if (overflow)
+                    return settle(null);
+                if (code !== 0)
+                    return settle(null);
+                const buf = Buffer.concat(chunks);
+                settle(buf.toString('utf8'));
+            });
+        }
+        catch {
+            settle(null);
+        }
+    });
+}
+/* ------------------------------------------------------------------ */
+/* Bracketed-paste mode helpers                                       */
+/* ------------------------------------------------------------------ */
+/**
+ * Modern terminals (iTerm2, Alacritty, GNOME Terminal, kitty,
+ * Windows Terminal) bracket pasted text with `ESC[200~ ... ESC[201~`
+ * when bracketed-paste mode is enabled. The input box can detect
+ * these markers and disable newline-as-submit during the paste burst
+ * so a multi-line paste does not fire `onSubmit` mid-paste.
+ *
+ * The constants here are exported so the input box and the unit
+ * test can share the byte sequences without re-implementing them.
+ */
+export const PASTE_START = '\x1b[200~';
+export const PASTE_END = '\x1b[201~';
+export const CTRL_V = '\x16';
+export function classifyChunk(chunk, inPaste) {
+    if (inPaste) {
+        const endIdx = chunk.indexOf(PASTE_END);
+        if (endIdx === -1) {
+            return { kind: 'paste-cont', textInPaste: chunk };
+        }
+        return {
+            kind: 'paste-end',
+            textInPaste: chunk.slice(0, endIdx),
+            textAfter: chunk.slice(endIdx + PASTE_END.length),
+        };
+    }
+    const startIdx = chunk.indexOf(PASTE_START);
+    if (startIdx === -1) {
+        return { kind: 'plain', text: chunk };
+    }
+    const afterStart = chunk.slice(startIdx + PASTE_START.length);
+    const endIdx = afterStart.indexOf(PASTE_END);
+    if (endIdx === -1) {
+        return {
+            kind: 'paste-start',
+            textBefore: chunk.slice(0, startIdx),
+            textInPaste: afterStart,
+        };
+    }
+    return {
+        kind: 'paste-only',
+        text: afterStart.slice(0, endIdx),
+    };
+}
+//# sourceMappingURL=clipboard-read.js.map

package/dist/core/repl/history-search.js

@@ -0,0 +1,175 @@
+/**
+ * FZF-style history search - Sprint α6.14.
+ *
+ * Powers the Ctrl+R (reverse) / Ctrl+S (forward) interactive search
+ * mode in the REPL input box. Hand-rolled scorer (no dep) tuned for
+ * short query strings (operator typing a few chars) over up to
+ * MAX_HISTORY_ENTRIES candidates.
+ *
+ * Scoring model (mirrors fzf v2 mid-priorities, simplified):
+ *
+ *   - Substring match required. Non-matching candidates score 0.
+ *   - Prefix match: +50
+ *   - Word-boundary start (' ', '/', '-', '_'): +20
+ *   - Camel boundary (`abcD` → 'D'): +10
+ *   - Contiguous run bonus: +5 per consecutive char after the first
+ *   - Distance penalty: -1 per gap char between query characters
+ *   - Recency bonus: +0.5 × (recencyRank / total) so newer entries
+ *     break ties in the operator's favour
+ *
+ * The result is a list of matches ordered by descending score with
+ * the matched character positions preserved so the UI can highlight
+ * them. `cycle` steps the focused match index forward (Ctrl+R again)
+ * or backward (Ctrl+S) modulo the result length.
+ *
+ * Contract:
+ *   - `searchHistory(query, entries, options)` is pure. No I/O.
+ *   - Empty query returns ALL entries newest-first so the operator
+ *     can browse without typing.
+ *   - Matching is case-insensitive on ASCII; non-ASCII characters
+ *     compare as-is.
+ *   - `cycle(state, direction)` is a no-op when there are no matches.
+ */
+const DEFAULT_LIMIT = 50;
+const WORD_BOUNDARIES = new Set([' ', '/', '-', '_', '.', ',', ':', ';', '\t']);
+/**
+ * Score one candidate against the query. Returns `null` when the
+ * query cannot be matched as an in-order substring (not necessarily
+ * contiguous). The matched positions are returned so the UI can
+ * underline them.
+ */
+export function scoreCandidate(query, candidate) {
+    if (query.length === 0) {
+        return { score: 0, positions: [] };
+    }
+    const lowerQuery = query.toLowerCase();
+    const lowerCandidate = candidate.toLowerCase();
+    // Walk the candidate, greedily matching each query char in order.
+    const positions = [];
+    let qIdx = 0;
+    for (let i = 0; i < lowerCandidate.length && qIdx < lowerQuery.length; i += 1) {
+        if (lowerCandidate[i] === lowerQuery[qIdx]) {
+            positions.push(i);
+            qIdx += 1;
+        }
+    }
+    if (qIdx < lowerQuery.length)
+        return null;
+    // Score the match.
+    let score = 0;
+    // Prefix bonus.
+    if (positions[0] === 0)
+        score += 50;
+    // Substring contiguity + boundary bonuses.
+    let lastPos = -2;
+    for (let p = 0; p < positions.length; p += 1) {
+        const pos = positions[p];
+        // Contiguous run.
+        if (pos === lastPos + 1) {
+            score += 5;
+        }
+        else if (lastPos >= 0) {
+            // Distance penalty for non-contiguous matches.
+            score -= pos - lastPos - 1;
+        }
+        // Word-boundary start.
+        if (pos === 0) {
+            // Already counted as prefix.
+        }
+        else {
+            const prev = candidate[pos - 1] ?? '';
+            if (WORD_BOUNDARIES.has(prev)) {
+                score += 20;
+            }
+            else {
+                // Camel boundary: prev is lowercase, current is uppercase.
+                const cur = candidate[pos] ?? '';
+                if (prev === prev.toLowerCase() && cur !== cur.toLowerCase()) {
+                    score += 10;
+                }
+            }
+        }
+        lastPos = pos;
+    }
+    return { score, positions };
+}
+/**
+ * Search a history list for matches. Entries are passed oldest-first
+ * (the format `history.read` returns); the recency bonus uses the
+ * original index so newer entries win ties.
+ */
+export function searchHistory(query, entries, options = {}) {
+    const limit = options.limit ?? DEFAULT_LIMIT;
+    const total = entries.length;
+    if (query.length === 0) {
+        // Empty query - browse mode. Return newest-first up to limit, no
+        // scoring needed.
+        const out = [];
+        for (let i = total - 1; i >= 0 && out.length < limit; i -= 1) {
+            const brief = entries[i];
+            out.push({ brief, positions: [], score: 0, originalIndex: i });
+        }
+        return out;
+    }
+    const candidates = [];
+    for (let i = 0; i < total; i += 1) {
+        const brief = entries[i];
+        const scored = scoreCandidate(query, brief);
+        if (!scored)
+            continue;
+        // Recency bonus: 0..0.5 weight scaled by index/total.
+        const recency = total === 0 ? 0 : (i / total) * 0.5;
+        candidates.push({
+            brief,
+            positions: scored.positions,
+            score: scored.score + recency,
+            originalIndex: i,
+        });
+    }
+    candidates.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        // Tie-breaker: newer first.
+        return b.originalIndex - a.originalIndex;
+    });
+    return candidates.slice(0, limit);
+}
+/**
+ * Initial search state for a fresh Ctrl+R press. Empty query +
+ * focusedIndex 0 over the browse list.
+ */
+export function initialSearchState(entries) {
+    const matches = searchHistory('', entries);
+    return { query: '', matches, focusedIndex: 0 };
+}
+/**
+ * Update the search state when the operator types a new query char or
+ * removes one. The focused index is clamped to the new match list so
+ * the UI never points off-the-end.
+ */
+export function applyQuery(state, query, entries) {
+    const matches = searchHistory(query, entries);
+    const focusedIndex = matches.length === 0 ? 0 : Math.min(state.focusedIndex, matches.length - 1);
+    return { query, matches, focusedIndex };
+}
+/**
+ * Move the focused match. `+1` = next (Ctrl+R repeat), `-1` = previous
+ * (Ctrl+S). Wraps around modulo result length so the operator never
+ * has to chase the end.
+ */
+export function cycle(state, direction) {
+    if (state.matches.length === 0)
+        return state;
+    const len = state.matches.length;
+    const next = (state.focusedIndex + direction + len) % len;
+    return { ...state, focusedIndex: next };
+}
+/**
+ * Pull the brief from the currently focused match, or `null` when
+ * the result list is empty (Enter accepts nothing).
+ */
+export function currentBrief(state) {
+    const match = state.matches[state.focusedIndex];
+    return match ? match.brief : null;
+}
+//# sourceMappingURL=history-search.js.map