@askalf/dario 3.38.6 → 4.0.1

package/dist/tui/input.js

@@ -0,0 +1,206 @@
+/**
+ * TUI input handling — stdin raw-mode key parser.
+ *
+ * Why not Node's `readline.emitKeypressEvents`: it works, but the Key
+ * shape (`{ name, ctrl, meta, sequence }`) is loosely typed, the
+ * legacy event flag is awkward to disable cleanly, and its escape-
+ * sequence parser has historically lagged on edge cases (Windows
+ * Terminal modifyOtherKeys, Kitty progressive enhancement, etc).
+ *
+ * Writing ~150 lines that handle the keys we ACTUALLY use is more
+ * predictable. The keys we care about:
+ *
+ *   - Printable ASCII (0x20-0x7e)
+ *   - Enter, Tab, Backspace, Escape
+ *   - Arrow up/down/left/right
+ *   - Home, End, PgUp, PgDn
+ *   - Ctrl+C, Ctrl+D (exit), Ctrl+L (redraw)
+ *
+ * Standalone Esc vs Esc-led sequence (e.g. arrow): we use the same
+ * heuristic xterm uses — if ESC arrives in the same buffer chunk as
+ * subsequent bytes, treat as a CSI sequence. If ESC arrives alone in
+ * a chunk, treat as a standalone Escape keypress. This is reliable
+ * on real terminals and avoids the alternative (a wait-timer + lookahead)
+ * which adds complexity and a delay every Esc keypress.
+ */
+/**
+ * Parse one stdin chunk into zero or more Key events. Pure function;
+ * the caller drives stdin and accumulates the result. Most chunks
+ * yield exactly one key (interactive typing); paste / IME burst can
+ * yield several.
+ */
+export function parseKeys(chunk) {
+    const keys = [];
+    let i = 0;
+    while (i < chunk.length) {
+        const b = chunk[i];
+        // Backspace: ASCII 0x7f on most terminals, 0x08 (BS / Ctrl+H) on
+        // Windows console + a few older ttys. Must check 0x08 BEFORE the
+        // Ctrl+letter range below, otherwise BS gets reported as Ctrl+H.
+        if (b === 0x7f || b === 0x08) {
+            keys.push(k('backspace', ''));
+            i++;
+            continue;
+        }
+        // Control keys (Ctrl+letter): byte 0x01-0x1a (A-Z masked with 0x1f)
+        if (b >= 0x01 && b <= 0x1a) {
+            // Special-case the named ones that aren't really "Ctrl+letter".
+            if (b === 0x09) {
+                keys.push(k('tab', '\t'));
+                i++;
+                continue;
+            }
+            if (b === 0x0a || b === 0x0d) {
+                keys.push(k('enter', '\n'));
+                i++;
+                continue;
+            }
+            // The rest are Ctrl+A through Ctrl+Z (skipping the named ones).
+            keys.push({
+                name: 'printable', ch: String.fromCharCode(b + 96), // 1 → 'a'
+                ctrl: true, shift: false, meta: false,
+            });
+            i++;
+            continue;
+        }
+        // Escape — either standalone or the start of a CSI sequence.
+        if (b === 0x1b) {
+            // Look at what follows in this same chunk
+            if (i + 1 >= chunk.length) {
+                // ESC alone in this chunk → standalone Escape keypress.
+                keys.push(k('escape', ''));
+                i++;
+                continue;
+            }
+            // ESC + '[' → CSI sequence. Read up to the terminating byte
+            // (0x40-0x7e per ECMA-48).
+            if (chunk[i + 1] === 0x5b /* '[' */ || chunk[i + 1] === 0x4f /* 'O' for SS3 */) {
+                const seqStart = i;
+                const ss3 = chunk[i + 1] === 0x4f;
+                i += 2;
+                let paramBytes = '';
+                while (i < chunk.length) {
+                    const c = chunk[i];
+                    if (c >= 0x40 && c <= 0x7e) {
+                        const final = String.fromCharCode(c);
+                        i++;
+                        keys.push(parseCsi(final, paramBytes, ss3, chunk.slice(seqStart, i)));
+                        break;
+                    }
+                    paramBytes += String.fromCharCode(c);
+                    i++;
+                }
+                continue;
+            }
+            // ESC + other byte → Alt/Meta + that byte
+            const next = chunk[i + 1];
+            if (next >= 0x20 && next <= 0x7e) {
+                keys.push({
+                    name: 'printable', ch: String.fromCharCode(next),
+                    ctrl: false, shift: false, meta: true,
+                });
+                i += 2;
+                continue;
+            }
+            // Fallback — emit ESC alone, advance one.
+            keys.push(k('escape', ''));
+            i++;
+            continue;
+        }
+        // Printable ASCII (including space)
+        if (b >= 0x20 && b <= 0x7e) {
+            keys.push({
+                name: 'printable', ch: String.fromCharCode(b),
+                ctrl: false, shift: b >= 0x41 && b <= 0x5a, meta: false,
+            });
+            i++;
+            continue;
+        }
+        // Anything else — pass through as unknown so the caller can see it.
+        keys.push({ name: 'unknown', ch: String.fromCharCode(b), ctrl: false, shift: false, meta: false });
+        i++;
+    }
+    return keys;
+}
+function k(name, ch) {
+    return { name, ch, ctrl: false, shift: false, meta: false };
+}
+/**
+ * Decode the body of a CSI sequence given the terminating byte and
+ * the parameter bytes between `[` and the terminator.
+ *
+ *   ESC[A    → up
+ *   ESC[B    → down
+ *   ESC[C    → right
+ *   ESC[D    → left
+ *   ESC[H    → home
+ *   ESC[F    → end
+ *   ESC[5~   → pageup
+ *   ESC[6~   → pagedown
+ *   ESC[3~   → delete
+ *   ESC[1~   → home (alternate)
+ *   ESC[4~   → end (alternate)
+ *
+ * Modifier-bearing variants (e.g. `ESC[1;5A` for Ctrl-Up) parse the
+ * second parameter as a modifier mask: bit 0 = Shift, bit 1 = Alt,
+ * bit 2 = Ctrl. xterm spec §"Modifier-Encoding".
+ */
+function parseCsi(final, params, ss3, raw) {
+    // Parse semicolon-separated numeric params
+    const parts = params.split(';').map(p => parseInt(p, 10) || 0);
+    // Modifier byte is the second param when present.
+    const mod = parts[1] ?? 1;
+    const ctrl = (mod - 1) & 4 ? true : false;
+    const shift = (mod - 1) & 1 ? true : false;
+    const meta = (mod - 1) & 2 ? true : false;
+    // Tilde-terminated: ESC[<n>~ where n is in parts[0]
+    if (final === '~') {
+        const n = parts[0];
+        const map = {
+            1: 'home', 2: 'home', 3: 'delete', 4: 'end',
+            5: 'pageup', 6: 'pagedown', 7: 'home', 8: 'end',
+        };
+        return { name: map[n] ?? 'unknown', ch: raw.toString(), ctrl, shift, meta };
+    }
+    // Letter-terminated: arrow / home / end (and SS3 variants)
+    void ss3;
+    const letterMap = {
+        A: 'up', B: 'down', C: 'right', D: 'left',
+        H: 'home', F: 'end',
+    };
+    if (letterMap[final]) {
+        return { name: letterMap[final], ch: raw.toString(), ctrl, shift, meta };
+    }
+    return { name: 'unknown', ch: raw.toString(), ctrl, shift, meta };
+}
+// ── Lifecycle helpers ──────────────────────────────────────────────
+/**
+ * Put stdin into raw mode and start emitting Key events to `handler`.
+ * Returns a cleanup function that restores stdin's pre-raw mode and
+ * unbinds the listener. ALWAYS call the cleanup on exit (including
+ * abnormal exits — wire a process exit / signal hook).
+ *
+ * Defaults are picked so the caller doesn't have to think about them:
+ * UTF-8 encoding (we don't see Buffer chunks split mid-character),
+ * resume() so paused stdin doesn't drop key events.
+ *
+ * Throws if stdin isn't a TTY — the TUI doesn't make sense in a pipe.
+ */
+export function attachKeyHandler(stdin, handler) {
+    if (!stdin.isTTY) {
+        throw new Error('TUI requires a TTY on stdin — pipe / redirect not supported');
+    }
+    const prevRawMode = stdin.isRaw;
+    stdin.setRawMode(true);
+    stdin.resume();
+    const onData = (chunk) => {
+        for (const key of parseKeys(chunk))
+            handler(key);
+    };
+    stdin.on('data', onData);
+    return () => {
+        stdin.off('data', onData);
+        stdin.setRawMode(prevRawMode ?? false);
+        stdin.pause();
+    };
+}

package/dist/tui/layout.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Higher-level layout primitives built on top of `render.ts`.
+ *
+ * These compose the lower-level ANSI strings into the structural
+ * patterns the v4 TUI actually uses: a header bar, a tab strip,
+ * a body region, a footer with key hints. Each returns a string
+ * (or appends to a Frame) — no terminal state, no side effects.
+ */
+/**
+ * Render the top header bar: brand + version on the left, contextual
+ * status text on the right (e.g. proxy URL when connected).
+ *
+ *   ╭ dario v4.0.0 ───────────────────── http://localhost:3456 ─╮
+ *
+ * Width is the full terminal columns; the caller positions it at row 1.
+ */
+export declare function renderHeader(width: number, opts: {
+    version: string;
+    status?: string;
+}): string;
+/**
+ * Render the bottom footer with key-hint pairs. Wide gaps so it doesn't
+ * look mashed-together:
+ *
+ *   [Tab] switch panel   [q] quit   [?] help
+ */
+export declare function renderFooter(width: number, hints: Array<{
+    key: string;
+    label: string;
+}>): string;
+/**
+ * Render a tab strip — one row of clickable-looking tab labels, with
+ * the active tab inverse-highlighted. Borders flank both sides.
+ *
+ *   │  Status   ▎Analytics▎   Config   Hits   Accounts   Backends   │
+ *
+ * The `activeTab` is the index of the highlighted tab. Caller draws
+ * the surrounding box separately.
+ */
+export declare function renderTabStrip(width: number, tabs: string[], activeTab: number): string;
+/**
+ * Render a vertical scroll indicator on the right edge of a panel.
+ * Shows "n / total" + a position blob if there's overflow.
+ *
+ *   ─ 24 / 412
+ */
+export declare function renderScrollIndicator(visible: number, total: number, selectedIdx: number): string;
+/**
+ * Word-wrap or hard-break `text` to lines of at most `width` visible
+ * chars. ANSI sequences are preserved across line boundaries; visible
+ * width is what's counted.
+ *
+ * Used for free-form prose in the Status / About panels.
+ */
+export declare function wrap(text: string, width: number): string[];
+/**
+ * Render a left-key / right-value row (the shape every config/status
+ * line uses).
+ *
+ *   Port:               3456
+ *   Mode:               passthrough
+ *
+ * Key is left-padded to `keyWidth` so a column of rows aligns. Value
+ * is truncated to fit the remaining space.
+ */
+export declare function renderKvRow(key: string, value: string, totalWidth: number, keyWidth?: number): string;

package/dist/tui/layout.js

@@ -0,0 +1,152 @@
+/**
+ * Higher-level layout primitives built on top of `render.ts`.
+ *
+ * These compose the lower-level ANSI strings into the structural
+ * patterns the v4 TUI actually uses: a header bar, a tab strip,
+ * a body region, a footer with key hints. Each returns a string
+ * (or appends to a Frame) — no terminal state, no side effects.
+ */
+import { brand, fg, inverse, BOX, pad, truncate, visibleWidth } from './render.js';
+/**
+ * Render the top header bar: brand + version on the left, contextual
+ * status text on the right (e.g. proxy URL when connected).
+ *
+ *   ╭ dario v4.0.0 ───────────────────── http://localhost:3456 ─╮
+ *
+ * Width is the full terminal columns; the caller positions it at row 1.
+ */
+export function renderHeader(width, opts) {
+    const left = ` ${brand('dario')} v${opts.version} `;
+    const right = opts.status ? ` ${opts.status} ` : '';
+    const dashWidth = Math.max(0, width - visibleWidth(left) - visibleWidth(right) - 2);
+    return BOX.topLeft + left + BOX.horizontal.repeat(dashWidth) + right + BOX.topRight;
+}
+/**
+ * Render the bottom footer with key-hint pairs. Wide gaps so it doesn't
+ * look mashed-together:
+ *
+ *   [Tab] switch panel   [q] quit   [?] help
+ */
+export function renderFooter(width, hints) {
+    const items = hints.map(h => `${fg('cyan', `[${h.key}]`)} ${h.label}`);
+    const joined = items.join('   ');
+    // Truncate if the hints don't fit (small terminal); never wrap to a
+    // second line — the footer is a single row by design.
+    return ' ' + truncate(joined, width - 2);
+}
+/**
+ * Render a tab strip — one row of clickable-looking tab labels, with
+ * the active tab inverse-highlighted. Borders flank both sides.
+ *
+ *   │  Status   ▎Analytics▎   Config   Hits   Accounts   Backends   │
+ *
+ * The `activeTab` is the index of the highlighted tab. Caller draws
+ * the surrounding box separately.
+ */
+export function renderTabStrip(width, tabs, activeTab) {
+    const sep = '   ';
+    const rendered = tabs.map((label, idx) => {
+        if (idx === activeTab) {
+            // Active: inverse-highlight with thin side-bars to evoke a
+            // selected pill. The ▎ left-eighth-block is visually subtle but
+            // unmistakable on every terminal that supports box-drawing.
+            return inverse(` ${label} `);
+        }
+        return ` ${label} `;
+    });
+    const inner = rendered.join(sep);
+    const padded = pad(inner, width, 'left');
+    return padded;
+}
+/**
+ * Render a vertical scroll indicator on the right edge of a panel.
+ * Shows "n / total" + a position blob if there's overflow.
+ *
+ *   ─ 24 / 412
+ */
+export function renderScrollIndicator(visible, total, selectedIdx) {
+    if (total <= visible)
+        return '';
+    return ` ${selectedIdx + 1} / ${total} `;
+}
+/**
+ * Word-wrap or hard-break `text` to lines of at most `width` visible
+ * chars. ANSI sequences are preserved across line boundaries; visible
+ * width is what's counted.
+ *
+ * Used for free-form prose in the Status / About panels.
+ */
+export function wrap(text, width) {
+    if (width <= 0)
+        return [];
+    const out = [];
+    for (const para of text.split('\n')) {
+        if (para === '') {
+            out.push('');
+            continue;
+        }
+        let line = '';
+        let lineWidth = 0;
+        for (const word of para.split(' ')) {
+            const w = visibleWidth(word);
+            // Word itself longer than width → hard-break it into chunks
+            // of `width` chars. Push the current accumulated line first so
+            // we don't lose pre-existing content.
+            if (w > width) {
+                if (lineWidth > 0) {
+                    out.push(line);
+                    line = '';
+                    lineWidth = 0;
+                }
+                let remaining = word;
+                while (visibleWidth(remaining) > width) {
+                    out.push(remaining.slice(0, width));
+                    remaining = remaining.slice(width);
+                }
+                line = remaining;
+                lineWidth = visibleWidth(remaining);
+                continue;
+            }
+            // Normal-width word: fit on current line if there's room, else
+            // wrap to a new line.
+            if (lineWidth === 0) {
+                line = word;
+                lineWidth = w;
+                continue;
+            }
+            if (lineWidth + 1 + w <= width) {
+                line += ' ' + word;
+                lineWidth += 1 + w;
+            }
+            else {
+                out.push(line);
+                line = word;
+                lineWidth = w;
+            }
+        }
+        if (line.length > 0)
+            out.push(line);
+    }
+    return out;
+}
+/**
+ * Render a left-key / right-value row (the shape every config/status
+ * line uses).
+ *
+ *   Port:               3456
+ *   Mode:               passthrough
+ *
+ * Key is left-padded to `keyWidth` so a column of rows aligns. Value
+ * is truncated to fit the remaining space.
+ */
+export function renderKvRow(key, value, totalWidth, keyWidth = 22) {
+    // Clamp keyWidth so a narrow terminal (totalWidth < keyWidth default)
+    // still produces a well-formed totalWidth-char row. The key gets
+    // truncated proportionally; the value column gets the rest.
+    const effectiveKeyWidth = Math.min(keyWidth, Math.max(1, totalWidth - 1));
+    const keyPart = pad(key + ':', effectiveKeyWidth);
+    // Value pad-to-width (not just truncate) so a full row reaches the
+    // panel edge — keeps backgrounds + borders aligned.
+    const valuePart = pad(value, totalWidth - effectiveKeyWidth);
+    return keyPart + valuePart;
+}

package/dist/tui/proxy-client.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Proxy HTTP client for the TUI.
+ *
+ * The TUI runs as its own process (`dario` with no args). It talks to
+ * a separately-running `dario proxy` over HTTP on localhost. This
+ * module is the thin client layer: JSON fetch + Server-Sent Events
+ * subscription + a `/health` reachability probe.
+ *
+ * Why not use fetch(): Node 22's global fetch works fine for one-shot
+ * JSON, but SSE streaming through it is awkward (the response.body
+ * is a WHATWG ReadableStream that needs an extra Node-stream adapter
+ * to handle line splitting cleanly across chunks). Using `node:http`
+ * directly keeps the SSE flow simple and matches the streaming hot-
+ * path the proxy itself uses.
+ *
+ * Zero deps as ever.
+ */
+export interface ProxyClientOpts {
+    /** Base URL of the running proxy, e.g. `http://127.0.0.1:3456`. */
+    baseUrl: string;
+    /** Optional API key — sent as `x-api-key` header. */
+    apiKey?: string;
+    /** Timeout for one-shot requests (ms). SSE subscriptions ignore this. */
+    timeoutMs?: number;
+}
+export declare class ProxyClient {
+    private baseUrl;
+    private apiKey?;
+    private timeoutMs;
+    constructor(opts: ProxyClientOpts);
+    /**
+     * GET a JSON endpoint. Rejects on non-2xx, network failure, JSON
+     * parse error, or timeout.
+     */
+    getJson<T = unknown>(path: string): Promise<T>;
+    /**
+     * Reachability probe — GET /health, returns parsed payload on
+     * success or null on any failure. Never throws; callers use the
+     * null as "proxy not running / unreachable".
+     */
+    health(): Promise<HealthResponse | null>;
+    /**
+     * Subscribe to /analytics/stream SSE. Calls `onMessage` for each
+     * data frame (parsed as JSON). Returns a `close()` function that
+     * unsubscribes — the caller MUST call this on unmount or the
+     * underlying socket leaks.
+     *
+     * Auto-reconnect is intentionally NOT included. The Hits tab decides
+     * when to retry (and how often) — pushing that policy into here would
+     * couple the client to UI semantics.
+     */
+    subscribeAnalyticsStream<T = unknown>(onMessage: (msg: T) => void, onError?: (err: Error) => void): () => void;
+    private headers;
+}
+export interface HealthResponse {
+    status: string;
+    oauth: string;
+    expiresIn?: string;
+    requests?: number;
+}

package/dist/tui/proxy-client.js

@@ -0,0 +1,166 @@
+/**
+ * Proxy HTTP client for the TUI.
+ *
+ * The TUI runs as its own process (`dario` with no args). It talks to
+ * a separately-running `dario proxy` over HTTP on localhost. This
+ * module is the thin client layer: JSON fetch + Server-Sent Events
+ * subscription + a `/health` reachability probe.
+ *
+ * Why not use fetch(): Node 22's global fetch works fine for one-shot
+ * JSON, but SSE streaming through it is awkward (the response.body
+ * is a WHATWG ReadableStream that needs an extra Node-stream adapter
+ * to handle line splitting cleanly across chunks). Using `node:http`
+ * directly keeps the SSE flow simple and matches the streaming hot-
+ * path the proxy itself uses.
+ *
+ * Zero deps as ever.
+ */
+import { request as httpRequest } from 'node:http';
+import { URL } from 'node:url';
+export class ProxyClient {
+    baseUrl;
+    apiKey;
+    timeoutMs;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/$/, '');
+        this.apiKey = opts.apiKey;
+        this.timeoutMs = opts.timeoutMs ?? 3000;
+    }
+    /**
+     * GET a JSON endpoint. Rejects on non-2xx, network failure, JSON
+     * parse error, or timeout.
+     */
+    async getJson(path) {
+        const url = new URL(this.baseUrl + path);
+        return new Promise((resolve, reject) => {
+            const req = httpRequest({
+                hostname: url.hostname,
+                port: url.port || 80,
+                path: url.pathname + url.search,
+                method: 'GET',
+                headers: this.headers(),
+            }, (res) => {
+                const chunks = [];
+                res.on('data', (c) => chunks.push(c));
+                res.on('end', () => {
+                    const body = Buffer.concat(chunks).toString('utf-8');
+                    if (!res.statusCode || res.statusCode < 200 || res.statusCode >= 300) {
+                        reject(new Error(`HTTP ${res.statusCode}: ${body.slice(0, 200)}`));
+                        return;
+                    }
+                    try {
+                        resolve(JSON.parse(body));
+                    }
+                    catch (e) {
+                        reject(new Error(`JSON parse: ${e.message}`));
+                    }
+                });
+                res.on('error', reject);
+            });
+            req.on('error', reject);
+            req.setTimeout(this.timeoutMs, () => {
+                req.destroy(new Error(`timeout after ${this.timeoutMs}ms`));
+            });
+            req.end();
+        });
+    }
+    /**
+     * Reachability probe — GET /health, returns parsed payload on
+     * success or null on any failure. Never throws; callers use the
+     * null as "proxy not running / unreachable".
+     */
+    async health() {
+        try {
+            return await this.getJson('/health');
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Subscribe to /analytics/stream SSE. Calls `onMessage` for each
+     * data frame (parsed as JSON). Returns a `close()` function that
+     * unsubscribes — the caller MUST call this on unmount or the
+     * underlying socket leaks.
+     *
+     * Auto-reconnect is intentionally NOT included. The Hits tab decides
+     * when to retry (and how often) — pushing that policy into here would
+     * couple the client to UI semantics.
+     */
+    subscribeAnalyticsStream(onMessage, onError) {
+        const url = new URL(this.baseUrl + '/analytics/stream');
+        let closed = false;
+        let res = null;
+        const req = httpRequest({
+            hostname: url.hostname,
+            port: url.port || 80,
+            path: url.pathname + url.search,
+            method: 'GET',
+            headers: { ...this.headers(), 'Accept': 'text/event-stream' },
+        }, (response) => {
+            if (closed) {
+                response.destroy();
+                return;
+            }
+            res = response;
+            if (!response.statusCode || response.statusCode < 200 || response.statusCode >= 300) {
+                onError?.(new Error(`HTTP ${response.statusCode}`));
+                response.destroy();
+                return;
+            }
+            response.setEncoding('utf-8');
+            let buf = '';
+            response.on('data', (chunk) => {
+                if (closed)
+                    return;
+                buf += chunk;
+                // SSE frames are separated by a blank line. Each frame can
+                // have a `data:` field (possibly across multiple `data:` lines
+                // — we concatenate them with \n per the SSE spec).
+                let idx;
+                while ((idx = buf.indexOf('\n\n')) >= 0) {
+                    const frame = buf.slice(0, idx);
+                    buf = buf.slice(idx + 2);
+                    const dataLines = frame.split('\n')
+                        .filter(l => l.startsWith('data:'))
+                        .map(l => l.slice(5).replace(/^ /, ''));
+                    if (dataLines.length === 0)
+                        continue;
+                    const payload = dataLines.join('\n');
+                    try {
+                        const parsed = JSON.parse(payload);
+                        onMessage(parsed);
+                    }
+                    catch (e) {
+                        onError?.(new Error(`SSE parse: ${e.message}`));
+                    }
+                }
+            });
+            response.on('error', (e) => { if (!closed)
+                onError?.(e); });
+            response.on('end', () => { if (!closed)
+                onError?.(new Error('stream ended')); });
+        });
+        req.on('error', (e) => { if (!closed)
+            onError?.(e); });
+        // No timeout on SSE — the heartbeat keeps the connection alive.
+        req.end();
+        return () => {
+            closed = true;
+            try {
+                req.destroy();
+            }
+            catch { /* ignored */ }
+            try {
+                res?.destroy();
+            }
+            catch { /* ignored */ }
+        };
+    }
+    headers() {
+        const h = {};
+        if (this.apiKey)
+            h['x-api-key'] = this.apiKey;
+        return h;
+    }
+}