@askdkc/dsh-cli 0.11.3

package/lib/types/ink/termio/osc.js

@@ -0,0 +1,475 @@
+/**
+ * OSC (Operating System Command) Types and Parser
+ */
+import { Buffer } from 'buffer';
+import { env } from '../../utils/env.js';
+import { execFileNoThrow } from '../../utils/execFileNoThrow.js';
+import { BEL, ESC, ESC_TYPE, SEP } from './ansi.js';
+/** OSC introducer prefix: ESC followed by `]`. */
+export const OSC_PREFIX = ESC + String.fromCharCode(ESC_TYPE.OSC);
+/** String Terminator (ESC \) - alternative to BEL for terminating OSC */
+export const ST = ESC + '\\';
+/**
+ * Characters that must never appear inside an OSC payload: C0/C1 controls
+ * terminate or smuggle sequences past the payload boundary (BEL and ST are
+ * terminators, ESC starts a new sequence, C1 bytes mean the same on 8-bit
+ * terminals). Space is NOT stripped here — titles and notification texts
+ * legitimately contain it; the one payload where a raw space is unsafe
+ * (the OSC 8 URI) strips it at the hyperlink entry (sanitizeHyperlinkUrl).
+ * Untrusted text (model output, plugin messages, session titles) reaches
+ * OSC constructors; stripping here is the single choke point that keeps
+ * injected sequences out of the terminal.
+ */
+const OSC_PAYLOAD_UNSAFE = /[\x00-\x1f\x7f-\x9f]/g;
+function sanitizeOscPart(part) {
+    return typeof part === 'number' ? part : part.replace(OSC_PAYLOAD_UNSAFE, '');
+}
+/**
+ * Generate an OSC sequence: ESC ] p1;p2;...;pN <terminator>.
+ * Uses the ST terminator for Kitty (avoids beeps) and BEL for others.
+ * @param parts - the sequence parts, joined by semicolons. Control
+ * characters inside string parts are stripped (see OSC_PAYLOAD_UNSAFE).
+ * @returns the complete OSC sequence string.
+ */
+export function osc(...parts) {
+    const terminator = env.terminal === 'kitty' ? ST : BEL;
+    return `${OSC_PREFIX}${parts.map(sanitizeOscPart).join(SEP)}${terminator}`;
+}
+/**
+ * Wrap an escape sequence for terminal multiplexer passthrough.
+ * tmux and GNU screen intercept escape sequences; DCS passthrough
+ * tunnels them to the outer terminal unmodified.
+ *
+ * tmux 3.3+ gates this behind `allow-passthrough` (default off). When off,
+ * tmux silently drops the whole DCS — no junk, no worse than unwrapped OSC.
+ * Users who want passthrough set it in their .tmux.conf; we don't mutate it.
+ *
+ * Do NOT wrap BEL: raw \x07 triggers tmux's bell-action (window flag);
+ * wrapped \x07 is opaque DCS payload and tmux never sees the bell.
+ * @param sequence - the escape sequence to wrap.
+ * @returns the DCS-passthrough-wrapped sequence inside tmux or GNU screen,
+ *   or the sequence unchanged otherwise.
+ */
+export function wrapForMultiplexer(sequence) {
+    if (process.env['TMUX']) {
+        const escaped = sequence.replaceAll('\x1b', '\x1b\x1b');
+        return `\x1bPtmux;${escaped}\x1b\\`;
+    }
+    if (process.env['STY']) {
+        return `\x1bP${sequence}\x1b\\`;
+    }
+    return sequence;
+}
+/**
+ * Determine the clipboard path setClipboard() will take, based on env state.
+ * @returns 'native' when a local clipboard tool is available, 'tmux-buffer'
+ *   inside tmux, or 'osc52' otherwise.
+ */
+export function getClipboardPath() {
+    const nativeAvailable = process.platform === 'darwin' && !process.env['SSH_CONNECTION'];
+    if (nativeAvailable)
+        return 'native';
+    if (process.env['TMUX'])
+        return 'tmux-buffer';
+    return 'osc52';
+}
+/**
+ * Wrap a payload in tmux's DCS passthrough: ESC P tmux ; <payload> ESC \
+ * tmux forwards the payload to the outer terminal, bypassing its own parser.
+ * Inner ESCs must be doubled. Requires `set -g allow-passthrough on` in
+ * ~/.tmux.conf; without it, tmux silently drops the whole DCS (no regression).
+ */
+function tmuxPassthrough(payload) {
+    return `${ESC}Ptmux;${payload.replaceAll(ESC, ESC + ESC)}${ST}`;
+}
+/**
+ * Load text into tmux's paste buffer via `tmux load-buffer`.
+ * -w (tmux 3.2+) propagates to the outer terminal's clipboard via tmux's
+ * own OSC 52 emission. -w is dropped for iTerm2: tmux's OSC 52 emission
+ * crashes the iTerm2 session over SSH.
+ *
+ * @param text - the text to load into the tmux paste buffer.
+ * @returns true when the buffer was loaded successfully, false when not in
+ *   tmux or the tmux command failed.
+ */
+export async function tmuxLoadBuffer(text) {
+    if (!process.env['TMUX'])
+        return false;
+    const args = process.env['LC_TERMINAL'] === 'iTerm2'
+        ? ['load-buffer', '-']
+        : ['load-buffer', '-w', '-'];
+    const { code } = await execFileNoThrow('tmux', args, {
+        input: text,
+        useCwd: false,
+        timeout: 2000,
+    });
+    return code === 0;
+}
+/**
+ * OSC 52 clipboard write: ESC ] 52 ; c ; <base64> BEL/ST
+ * 'c' selects the clipboard (vs 'p' for primary selection on X11).
+ *
+ * When inside tmux ($TMUX set), `tmux load-buffer -w -` is the primary
+ * path. tmux's buffer is always reachable — works over SSH, survives
+ * detach/reattach, immune to stale env vars. The -w flag (tmux 3.2+) tells
+ * tmux to also propagate to the outer terminal via its own OSC 52 path,
+ * which tmux wraps correctly for the attached client. On older tmux, -w is
+ * ignored and the buffer is still loaded. -w is dropped for iTerm2
+ * because tmux's own OSC 52 emission (empty selection param: ESC]52;;b64)
+ * crashes iTerm2 over SSH.
+ *
+ * After load-buffer succeeds, we ALSO return a DCS-passthrough-wrapped
+ * OSC 52 for the caller to write to stdout. Our sequence uses explicit `c`
+ * (not tmux's crashy empty-param variant), so it sidesteps the empty-selector path.
+ * With `allow-passthrough on` + an OSC-52-capable outer terminal, selection
+ * reaches the system clipboard; with either off, tmux silently drops the
+ * DCS and prefix+] still works.
+ *
+ * If load-buffer fails entirely, fall through to raw OSC 52.
+ *
+ * Outside tmux, write raw OSC 52 to stdout (caller handles the write).
+ *
+ * Local (no SSH_CONNECTION): also shell out to a native clipboard utility.
+ * OSC 52 and tmux -w both depend on terminal settings — iTerm2 disables
+ * OSC 52 by default, VS Code shows a permission prompt on first use. Native
+ * utilities (pbcopy/wl-copy/xclip/xsel/clip.exe) always work locally. Over
+ * SSH these would write to the remote clipboard — OSC 52 is the right path there.
+ *
+ * @param text - the text to place on the clipboard.
+ * @returns the sequence for the caller to write to stdout (raw OSC 52
+ *   outside tmux, DCS-wrapped inside).
+ */
+export async function setClipboard(text) {
+    const b64 = Buffer.from(text, 'utf8').toString('base64');
+    const raw = osc(OSC.CLIPBOARD, 'c', b64);
+    // Native safety net — fire FIRST, before the tmux await, so a quick
+    // focus-switch after selecting doesn't race pbcopy. Previously this ran
+    // AFTER awaiting tmux load-buffer, adding ~50-100ms of subprocess latency
+    // before pbcopy even started — fast cmd+tab → paste would beat it.
+    // Gated on SSH_CONNECTION (not SSH_TTY) since tmux panes inherit SSH_TTY
+    // forever but SSH_CONNECTION is in tmux's default update-environment and
+    // clears on local attach. Fire-and-forget.
+    if (!process.env['SSH_CONNECTION'])
+        copyNative(text);
+    const tmuxBufferLoaded = await tmuxLoadBuffer(text);
+    // Inner OSC uses BEL directly (not osc()) — ST's ESC would need doubling
+    // too, and BEL works everywhere for OSC 52.
+    if (tmuxBufferLoaded)
+        return tmuxPassthrough(`${ESC}]52;c;${b64}${BEL}`);
+    return raw;
+}
+// Linux clipboard tool: undefined = not yet probed, null = none available.
+// Probe order: wl-copy (Wayland) → xclip (X11) → xsel (X11 fallback).
+// Cached after first attempt so repeated mouse-ups skip the probe chain.
+let linuxCopy;
+/**
+ * Shell out to a native clipboard utility as a safety net for OSC 52.
+ * Only called when not in an SSH session (over SSH, these would write to
+ * the remote machine's clipboard — OSC 52 is the right path there).
+ * Fire-and-forget: failures are silent since OSC 52 may have succeeded.
+ */
+function copyNative(text) {
+    const opts = { input: text, useCwd: false, timeout: 2000 };
+    switch (process.platform) {
+        case 'darwin':
+            void execFileNoThrow('pbcopy', [], opts);
+            return;
+        case 'linux': {
+            if (linuxCopy === null)
+                return;
+            if (linuxCopy === 'wl-copy') {
+                void execFileNoThrow('wl-copy', [], opts);
+                return;
+            }
+            if (linuxCopy === 'xclip') {
+                void execFileNoThrow('xclip', ['-selection', 'clipboard'], opts);
+                return;
+            }
+            if (linuxCopy === 'xsel') {
+                void execFileNoThrow('xsel', ['--clipboard', '--input'], opts);
+                return;
+            }
+            // First call: probe wl-copy (Wayland) then xclip/xsel (X11), cache winner.
+            void execFileNoThrow('wl-copy', [], opts).then(r => {
+                if (r.code === 0) {
+                    linuxCopy = 'wl-copy';
+                    return;
+                }
+                void execFileNoThrow('xclip', ['-selection', 'clipboard'], opts).then(r2 => {
+                    if (r2.code === 0) {
+                        linuxCopy = 'xclip';
+                        return;
+                    }
+                    void execFileNoThrow('xsel', ['--clipboard', '--input'], opts).then(r3 => {
+                        linuxCopy = r3.code === 0 ? 'xsel' : null;
+                    });
+                });
+            });
+            return;
+        }
+        case 'win32':
+            // clip.exe is always available on Windows. Unicode handling is
+            // imperfect (system locale encoding) but good enough for a fallback.
+            void execFileNoThrow('clip', [], opts);
+            return;
+    }
+}
+/**
+ * Reset the cached Linux clipboard tool probe, forcing the next copy to
+ * re-probe wl-copy/xclip/xsel.
+ * @internal test-only
+ */
+export function _resetLinuxCopyCache() {
+    linuxCopy = undefined;
+}
+/**
+ * OSC command numbers
+ */
+export const OSC = {
+    SET_TITLE_AND_ICON: 0,
+    SET_ICON: 1,
+    SET_TITLE: 2,
+    SET_COLOR: 4,
+    SET_CWD: 7,
+    HYPERLINK: 8,
+    ITERM2: 9, // iTerm2 proprietary sequences
+    SET_FG_COLOR: 10,
+    SET_BG_COLOR: 11,
+    SET_CURSOR_COLOR: 12,
+    CLIPBOARD: 52,
+    KITTY: 99, // Kitty notification protocol
+    RESET_COLOR: 104,
+    RESET_FG_COLOR: 110,
+    RESET_BG_COLOR: 111,
+    RESET_CURSOR_COLOR: 112,
+    SEMANTIC_PROMPT: 133,
+    GHOSTTY: 777, // Ghostty notification protocol
+    TAB_STATUS: 21337, // Tab status extension
+};
+/**
+ * Parse an OSC sequence into an action.
+ *
+ * @param content - The sequence content (without ESC ] and terminator).
+ * @returns the parsed action; unrecognized commands yield an
+ *   unknown-sequence action.
+ */
+export function parseOSC(content) {
+    const semicolonIdx = content.indexOf(';');
+    const command = semicolonIdx >= 0 ? content.slice(0, semicolonIdx) : content;
+    const data = semicolonIdx >= 0 ? content.slice(semicolonIdx + 1) : '';
+    const commandNum = parseInt(command, 10);
+    // Window/icon title
+    if (commandNum === OSC.SET_TITLE_AND_ICON) {
+        return { type: 'title', action: { type: 'both', title: data } };
+    }
+    if (commandNum === OSC.SET_ICON) {
+        return { type: 'title', action: { type: 'iconName', name: data } };
+    }
+    if (commandNum === OSC.SET_TITLE) {
+        return { type: 'title', action: { type: 'windowTitle', title: data } };
+    }
+    // Hyperlinks (OSC 8)
+    if (commandNum === OSC.HYPERLINK) {
+        const parts = data.split(';');
+        const paramsStr = parts[0] ?? '';
+        const url = parts.slice(1).join(';');
+        if (url === '') {
+            return { type: 'link', action: { type: 'end' } };
+        }
+        const params = {};
+        if (paramsStr) {
+            for (const pair of paramsStr.split(':')) {
+                const eqIdx = pair.indexOf('=');
+                if (eqIdx >= 0) {
+                    params[pair.slice(0, eqIdx)] = pair.slice(eqIdx + 1);
+                }
+            }
+        }
+        return {
+            type: 'link',
+            action: {
+                type: 'start',
+                url,
+                params: Object.keys(params).length > 0 ? params : undefined,
+            },
+        };
+    }
+    // Tab status (OSC 21337)
+    if (commandNum === OSC.TAB_STATUS) {
+        return { type: 'tabStatus', action: parseTabStatus(data) };
+    }
+    return { type: 'unknown', sequence: `\x1b]${content}` };
+}
+/**
+ * Parse an XParseColor-style color spec into an RGB Color.
+ * Accepts `#RRGGBB` and `rgb:R/G/B` (1–4 hex digits per component, scaled
+ * to 8-bit). Returns null on parse failure.
+ * @param spec - the color spec string to parse.
+ * @returns the parsed RGB color, or null when the spec does not match.
+ */
+export function parseOscColor(spec) {
+    const hex = spec.match(/^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i);
+    if (hex) {
+        return {
+            type: 'rgb',
+            r: parseInt(hex[1], 16),
+            g: parseInt(hex[2], 16),
+            b: parseInt(hex[3], 16),
+        };
+    }
+    const rgb = spec.match(/^rgb:([0-9a-f]{1,4})\/([0-9a-f]{1,4})\/([0-9a-f]{1,4})$/i);
+    if (rgb) {
+        // XParseColor: N hex digits → value / (16^N - 1), scale to 0-255
+        const scale = (s) => Math.round((parseInt(s, 16) / (16 ** s.length - 1)) * 255);
+        return {
+            type: 'rgb',
+            r: scale(rgb[1]),
+            g: scale(rgb[2]),
+            b: scale(rgb[3]),
+        };
+    }
+    return null;
+}
+/**
+ * Parse OSC 21337 payload: `key=value;key=value;...` with `\;` and `\\`
+ * escapes inside values. Bare key or `key=` clears that field; unknown
+ * keys are ignored.
+ */
+function parseTabStatus(data) {
+    const action = {};
+    for (const [key, value] of splitTabStatusPairs(data)) {
+        switch (key) {
+            case 'indicator':
+                action.indicator = value === '' ? null : parseOscColor(value);
+                break;
+            case 'status':
+                action.status = value === '' ? null : value;
+                break;
+            case 'status-color':
+                action.statusColor = value === '' ? null : parseOscColor(value);
+                break;
+        }
+    }
+    return action;
+}
+/** Split `k=v;k=v` honoring `\;` and `\\` escapes. Yields [key, unescapedValue]. */
+function* splitTabStatusPairs(data) {
+    let key = '';
+    let val = '';
+    let inVal = false;
+    let esc = false;
+    for (const c of data) {
+        if (esc) {
+            if (inVal)
+                val += c;
+            else
+                key += c;
+            esc = false;
+        }
+        else if (c === '\\') {
+            esc = true;
+        }
+        else if (c === ';') {
+            yield [key, val];
+            key = '';
+            val = '';
+            inVal = false;
+        }
+        else if (c === '=' && !inVal) {
+            inVal = true;
+        }
+        else if (inVal) {
+            val += c;
+        }
+        else {
+            key += c;
+        }
+    }
+    if (key || inVal)
+        yield [key, val];
+}
+// Output generators
+/**
+ * Start a hyperlink (OSC 8). Auto-assigns an id= param derived from the URL
+ * so terminals group wrapped lines of the same link together (the spec says
+ * cells with matching URI *and* nonempty id are joined; without an id each
+ * wrapped line is a separate link — inconsistent hover, partial tooltips).
+ * Empty url = close sequence (empty params per spec).
+ * @param url - the link target URL; an empty string emits the close sequence.
+ * @param params - optional OSC 8 parameters, merged over the auto-assigned id.
+ * @returns the OSC 8 sequence.
+ */
+export function link(url, params) {
+    if (!url)
+        return LINK_END;
+    // A raw space is unsafe in the OSC 8 URI form specifically; titles and
+    // notification payloads keep theirs, so this lives here, not in osc().
+    // Encoded, not deleted — `file:///C:/My Project/x` must keep pointing
+    // at the same path when round-tripped through the terminal.
+    const safeUrl = url.replaceAll(' ', '%20');
+    const p = { id: osc8Id(safeUrl), ...params };
+    const paramStr = Object.entries(p)
+        .map(([k, v]) => `${k}=${v.replaceAll(' ', '')}`)
+        .join(':');
+    return osc(OSC.HYPERLINK, paramStr, safeUrl);
+}
+function osc8Id(url) {
+    let h = 0;
+    for (let i = 0; i < url.length; i++)
+        h = ((h << 5) - h + url.charCodeAt(i)) | 0;
+    return (h >>> 0).toString(36);
+}
+/** End a hyperlink (OSC 8) */
+export const LINK_END = osc(OSC.HYPERLINK, '', '');
+// iTerm2 OSC 9 subcommands
+/** iTerm2 OSC 9 subcommand numbers */
+export const ITERM2 = {
+    NOTIFY: 0,
+    BADGE: 2,
+    PROGRESS: 4,
+};
+/** Progress operation codes (for use with ITERM2.PROGRESS) */
+export const PROGRESS = {
+    CLEAR: 0,
+    SET: 1,
+    ERROR: 2,
+    INDETERMINATE: 3,
+};
+/**
+ * Clear iTerm2 progress bar sequence (OSC 9;4;0;BEL)
+ * Uses BEL terminator since this is for cleanup (not runtime notification)
+ * and we want to ensure it's always sent regardless of terminal type.
+ */
+export const CLEAR_ITERM2_PROGRESS = `${OSC_PREFIX}${OSC.ITERM2};${ITERM2.PROGRESS};${PROGRESS.CLEAR};${BEL}`;
+/**
+ * Clear terminal title sequence (OSC 0 with empty string + BEL).
+ * Uses BEL terminator for cleanup — safe on all terminals.
+ */
+export const CLEAR_TERMINAL_TITLE = `${OSC_PREFIX}${OSC.SET_TITLE_AND_ICON};${BEL}`;
+/** Clear all three OSC 21337 tab-status fields. Used on exit. */
+export const CLEAR_TAB_STATUS = osc(OSC.TAB_STATUS, 'indicator=;status=;status-color=');
+/** Enable experimental tab status only when explicitly requested by the terminal owner. */
+export function supportsTabStatus() {
+    return process.env.DSH_TUI_TAB_STATUS === '1';
+}
+/**
+ * Emit an OSC 21337 tab-status sequence. Omitted fields are left unchanged
+ * by the receiving terminal; `null` sends an empty value to clear.
+ * `;` and `\` in status text are escaped per the spec.
+ * @param fields - the tab-status fields to emit; omitted fields are left
+ *   unchanged by the terminal, null values clear the field.
+ * @returns the OSC 21337 sequence.
+ */
+export function tabStatus(fields) {
+    const parts = [];
+    const rgb = (c) => c.type === 'rgb'
+        ? `#${[c.r, c.g, c.b].map(n => n.toString(16).padStart(2, '0')).join('')}`
+        : '';
+    if ('indicator' in fields)
+        parts.push(`indicator=${fields.indicator ? rgb(fields.indicator) : ''}`);
+    if ('status' in fields)
+        parts.push(`status=${fields.status?.replaceAll('\\', '\\\\').replaceAll(';', '\\;') ?? ''}`);
+    if ('statusColor' in fields)
+        parts.push(`status-color=${fields.statusColor ? rgb(fields.statusColor) : ''}`);
+    return osc(OSC.TAB_STATUS, parts.join(';'));
+}

package/lib/types/ink/termio/parser.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ANSI Parser - Semantic Action Generator
+ *
+ * A streaming parser for ANSI escape sequences that produces semantic actions.
+ * Uses the tokenizer for escape sequence boundary detection, then interprets
+ * each sequence to produce structured actions.
+ *
+ * Key design decisions:
+ * - Streaming: can process input incrementally
+ * - Semantic output: produces structured actions, not string tokens
+ * - Style tracking: maintains current text style state
+ */
+import type { Action, TextStyle } from './types.js';
+/**
+ * Parser class - maintains state for streaming/incremental parsing
+ *
+ * Usage:
+ * ```typescript
+ * const parser = new Parser()
+ * const actions1 = parser.feed('partial\x1b[')
+ * const actions2 = parser.feed('31mred')  // state maintained internally
+ * ```
+ */
+export declare class Parser {
+    private tokenizer;
+    /** Current text style, updated as SGR sequences are applied. */
+    style: TextStyle;
+    /** Whether the parser is currently inside an OSC 8 hyperlink. */
+    inLink: boolean;
+    /** URL of the active OSC 8 hyperlink; undefined when not in a link. */
+    linkUrl: string | undefined;
+    /**
+     * Reset all parser state: tokenizer buffer, text style, and link state.
+     */
+    reset(): void;
+    /**
+     * Feed input and get the resulting actions.
+     * @param input - the input chunk to process.
+     * @returns the semantic actions produced by this chunk.
+     */
+    feed(input: string): Action[];
+    private processToken;
+    private processText;
+    private processSequence;
+}
+//# sourceMappingURL=parser.d.ts.map

package/lib/types/ink/termio/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../../src/ink/termio/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH,OAAO,KAAK,EAAE,MAAM,EAAY,SAAS,EAAE,MAAM,YAAY,CAAA;AAgP7D;;;;;;;;;GASG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,SAAS,CAA+B;IAEhD,gEAAgE;IAChE,KAAK,EAAE,SAAS,CAAiB;IAEjC,iEAAiE;IACjE,MAAM,UAAQ;IAEd,uEAAuE;IACvE,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAE3B;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE;IAY7B,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,WAAW;IA8BnB,OAAO,CAAC,eAAe;CAuDxB"}