@askdkc/dsh-cli 0.11.3

package/lib/types/ink/terminal-querier.js

@@ -0,0 +1,286 @@
+/**
+ * Query the terminal and await responses without timeouts.
+ *
+ * Terminal queries (DECRQM, DA1, OSC 11, etc.) share the stdin stream
+ * with keyboard input. Response sequences are syntactically
+ * distinguishable from key events, so the input parser recognizes them
+ * and dispatches them here.
+ *
+ * To avoid timeouts, each query batch is terminated by a DA1 sentinel
+ * (CSI c) — every terminal since VT100 responds to DA1, and terminals
+ * answer queries in order. So: if your query's response arrives before
+ * DA1's, the terminal supports it; if DA1 arrives first, it doesn't.
+ *
+ * Usage:
+ *   const [sync, grapheme] = await Promise.all([
+ *     querier.send(decrqm(2026)),
+ *     querier.send(decrqm(2027)),
+ *     querier.flush(),
+ *   ])
+ *   // sync and grapheme are DECRPM responses or undefined if unsupported
+ */
+import { csi } from './termio/csi.js';
+import { osc } from './termio/osc.js';
+// -- Query builders --
+/**
+ * DECRQM: request DEC private mode status (CSI ? mode $ p).
+ * Terminal replies with DECRPM (CSI ? mode ; status $ y) or ignores.
+ * @param mode - the DEC private mode number to query.
+ * @returns a query whose response is the DECRPM reply for mode.
+ */
+export function decrqm(mode) {
+    return {
+        request: csi(`?${mode}$p`),
+        match: (r) => r.type === 'decrpm' && r.mode === mode,
+    };
+}
+/**
+ * Primary Device Attributes query (CSI c). Every terminal answers this —
+ * used internally by flush() as a universal sentinel. Call directly if
+ * you want the DA1 params.
+ * @returns a query whose response is the DA1 reply.
+ */
+export function da1() {
+    return {
+        request: csi('c'),
+        match: (r) => r.type === 'da1',
+    };
+}
+/**
+ * Secondary Device Attributes query (CSI > c). Returns terminal version.
+ * @returns a query whose response is the DA2 reply.
+ */
+export function da2() {
+    return {
+        request: csi('>c'),
+        match: (r) => r.type === 'da2',
+    };
+}
+/**
+ * Query current Kitty keyboard protocol flags (CSI ? u).
+ * Terminal replies with CSI ? flags u or ignores.
+ * @returns a query whose response is the Kitty keyboard reply.
+ */
+export function kittyKeyboard() {
+    return {
+        request: csi('?u'),
+        match: (r) => r.type === 'kittyKeyboard',
+    };
+}
+/**
+ * Query direct-data and zlib support for the Kitty graphics protocol with one
+ * transparent 1×1 RGBA pixel. The terminal echoes the image id in its reply.
+ */
+export function kittyGraphics(imageId) {
+    const id = Number.isSafeInteger(imageId) && imageId > 0 ? imageId : 31;
+    return {
+        // One transparent RGBA pixel compressed with RFC 1950 zlib. Probe the
+        // same direct-data + compression path used by real renderer uploads.
+        request: `\u001b_Gi=${id},s=1,v=1,a=q,t=d,f=32,o=z;eAFjYGBgAAAABAAB\u001b\\`,
+        match: (r) => r.type === 'kittyGraphics' && r.imageId === id,
+    };
+}
+/** XTWINOPS: query the physical pixel dimensions of one terminal cell. */
+export function terminalCellSizePixels() {
+    return {
+        request: csi('16t'),
+        match: (r) => r.type === 'terminalPixelSize' && r.scope === 'cell',
+    };
+}
+/** XTWINOPS: query the terminal text area's physical pixel dimensions. */
+export function terminalWindowSizePixels() {
+    return {
+        request: csi('14t'),
+        match: (r) => r.type === 'terminalPixelSize' && r.scope === 'window',
+    };
+}
+/**
+ * DECXCPR: request cursor position with DEC-private marker (CSI ? 6 n).
+ * Terminal replies with CSI ? row ; col R. The `?` marker is critical —
+ * the plain DSR form (CSI 6 n → CSI row;col R) is ambiguous with
+ * modified F3 keys (Shift+F3 = CSI 1;2 R, etc.).
+ * @returns a query whose response is the cursor-position reply.
+ */
+export function cursorPosition() {
+    return {
+        request: csi('?6n'),
+        match: (r) => r.type === 'cursorPosition',
+    };
+}
+/**
+ * OSC dynamic color query (e.g. OSC 11 for bg color, OSC 10 for fg).
+ * The `?` data slot asks the terminal to reply with the current value.
+ * @param code - the OSC color code to query (10 = fg, 11 = bg, etc.).
+ * @returns a query whose response is the OSC color reply.
+ */
+export function oscColor(code) {
+    return {
+        request: osc(code, '?'),
+        match: (r) => r.type === 'osc' && r.code === code,
+    };
+}
+/**
+ * XTVERSION: request terminal name/version (CSI > 0 q).
+ * Terminal replies with DCS > | name ST (e.g. "xterm.js(5.5.0)") or ignores.
+ * This survives SSH — the query goes through the pty, not the environment,
+ * so it identifies the *client* terminal even when TERM_PROGRAM isn't
+ * forwarded. Used to detect xterm.js for wheel-scroll compensation.
+ * @returns a query whose response is the XTVERSION reply.
+ */
+export function xtversion() {
+    return {
+        request: csi('>0q'),
+        match: (r) => r.type === 'xtversion',
+    };
+}
+// -- Querier --
+/** Sentinel request sequence (DA1). Kept internal; flush() writes it. */
+const SENTINEL = csi('c');
+/**
+ * Sends terminal queries to stdout and resolves their responses, using a
+ * flush() sentinel barrier so queries never time out.
+ */
+export class TerminalQuerier {
+    stdout;
+    setRawMode;
+    /**
+     * Interleaved queue of queries and sentinels in send order. Terminals
+     * respond in order, so each flush() barrier only drains queries queued
+     * before it — concurrent batches from independent callers stay isolated.
+     */
+    queue = [];
+    /**
+     * Set by dispose(). Post-dispose send()/flush() must not touch the
+     * terminal: they would re-enable raw mode (holdRawMode) and emit query
+     * bytes after the exit funnel's cleanup has already restored cooked
+     * mode — the replies then leak into the shell (#507). Resolving as
+     * "no answer" keeps callers' .then() chains inert instead of pending.
+     */
+    disposed = false;
+    suspended = false;
+    constructor(stdout, setRawMode) {
+        this.stdout = stdout;
+        this.setRawMode = setRawMode;
+    }
+    /** Whether terminal query I/O is paused for an external process handoff. */
+    get isSuspended() {
+        return this.suspended;
+    }
+    holdRawMode() {
+        this.setRawMode?.(true);
+        return () => this.setRawMode?.(false);
+    }
+    /**
+     * Send a query and wait for its response.
+     *
+     * Resolves with the response when `query.match` matches an incoming
+     * TerminalResponse, or with `undefined` when a flush() sentinel arrives
+     * before any matching response (meaning the terminal ignored the query).
+     *
+     * Never rejects; never times out on its own. If you never call flush()
+     * and the terminal doesn't respond, the promise remains pending.
+     * @param query - the query to send and await a response for.
+     * @returns the matched response, or undefined when the terminal did not
+     *   answer before the next flush() sentinel.
+     */
+    send(query) {
+        if (this.disposed || this.suspended)
+            return Promise.resolve(undefined);
+        return new Promise(resolve => {
+            this.queue.push({
+                kind: 'query',
+                match: query.match,
+                resolve: r => resolve(r),
+                releaseRawMode: this.holdRawMode(),
+            });
+            this.stdout.write(query.request);
+        });
+    }
+    flush(options) {
+        if (this.disposed || this.suspended)
+            return Promise.resolve();
+        return new Promise(resolve => {
+            this.queue.push({
+                kind: 'sentinel',
+                resolve: attributes => resolve(options?.attributes ? attributes : undefined),
+                releaseRawMode: this.holdRawMode(),
+            });
+            this.stdout.write(SENTINEL);
+        });
+    }
+    /** Resolve and release all pending queries when their owning app unmounts. */
+    dispose() {
+        this.disposed = true;
+        this.suspended = true;
+        this.drainPending();
+    }
+    /**
+     * Dispatch a response parsed from stdin. Called by App.tsx's
+     * processKeysInBatch for every `kind: 'response'` item.
+     *
+     * Matching strategy:
+     * - First, try to match a pending query (FIFO, first match wins).
+     *   This lets callers send(da1()) explicitly if they want the DA1
+     *   params — a separate DA1 write means the terminal sends TWO DA1
+     *   responses. The first matches the explicit query; the second
+     *   (unmatched) fires the sentinel.
+     * - Otherwise, if this is a DA1, fire the FIRST pending sentinel:
+     *   resolve any queries queued before that sentinel with undefined
+     *   (the terminal answered DA1 without answering them → unsupported)
+     *   and signal its flush() completion. Only draining up to the first
+     *   sentinel keeps later batches intact when multiple callers have
+     *   concurrent queries in flight.
+     * - Unsolicited responses (no match, no sentinel) are silently dropped.
+     * @param r - the response parsed from stdin.
+     */
+    onResponse(r) {
+        if (this.suspended)
+            return;
+        const idx = this.queue.findIndex(p => p.kind === 'query' && p.match(r));
+        if (idx !== -1) {
+            const [q] = this.queue.splice(idx, 1);
+            if (q?.kind === 'query') {
+                q.resolve(r);
+                q.releaseRawMode();
+            }
+            return;
+        }
+        if (r.type === 'da1') {
+            const s = this.queue.findIndex(p => p.kind === 'sentinel');
+            if (s === -1)
+                return;
+            for (const p of this.queue.splice(0, s + 1)) {
+                if (p.kind === 'query')
+                    p.resolve(undefined);
+                else
+                    p.resolve(r);
+                p.releaseRawMode();
+            }
+        }
+    }
+    /**
+     * Resolve outstanding queries before stdin is handed to another process.
+     * Their replies can no longer be routed reliably once the child owns the
+     * terminal; later queries remain available after the handoff.
+     */
+    suspend() {
+        if (this.disposed)
+            return;
+        this.suspended = true;
+        this.drainPending();
+    }
+    /** Resume queries after the caller's terminal-reply quarantine has ended. */
+    resume() {
+        if (!this.disposed)
+            this.suspended = false;
+    }
+    drainPending() {
+        for (const pending of this.queue.splice(0)) {
+            if (pending.kind === 'query')
+                pending.resolve(undefined);
+            else
+                pending.resolve();
+            pending.releaseRawMode();
+        }
+    }
+}

package/lib/types/ink/terminal.d.ts

@@ -0,0 +1,192 @@
+import type { Writable } from 'stream';
+import type { Diff } from './frame.js';
+/**
+ * Progress-report state for OSC 9;4: a state plus an optional percentage.
+ */
+export type Progress = {
+    state: 'running' | 'completed' | 'error' | 'indeterminate';
+    percentage?: number;
+};
+/**
+ * Checks if the terminal supports OSC 9;4 progress reporting.
+ * Supported terminals:
+ * - ConEmu (Windows) - all versions
+ * - Ghostty 1.2.0+
+ * - iTerm2 3.6.6+
+ *
+ * Note: Windows Terminal interprets OSC 9;4 as notifications, not progress.
+ * @returns true when the terminal supports OSC 9;4 progress reporting.
+ */
+export declare function isProgressReportingAvailable(): boolean;
+/**
+ * True when running inside a JetBrains IDE terminal (JediTerm). The IDE
+ * injects `TERMINAL_EMULATOR=JetBrains-JediTerm` into the pty environment of
+ * its local terminal sessions and sets no TERM_PROGRAM, so this is the only
+ * reliable local-JediTerm marker; it is also not forwarded over SSH by
+ * default (sshd only sends TERM), matching the local-terminal scope of the
+ * behaviors it gates.
+ *
+ * JediTerm's emulation diverges from xterm.js in exactly the places the
+ * renderer cares about (DEC 2026 support, DECSTBM semantics), so it is
+ * detected explicitly rather than left to TERM/TERM_PROGRAM fallbacks.
+ * @returns true when the process runs in a JetBrains IDE terminal.
+ */
+export declare function isJetBrainsIdeTerminal(): boolean;
+/**
+ * Detects zellij, which multiplexes the outer terminal instead of emulating
+ * it. Capability probes therefore describe the *outer* terminal — zellij even
+ * forwards KITTY_WINDOW_ID into the pane, so kitty detection matches — while
+ * zellij's own grid decides how control sequences actually apply.
+ * @returns true when the process runs inside a zellij pane.
+ */
+export declare function isZellij(): boolean;
+/**
+ * Checks if the terminal supports DEC mode 2026 (synchronized output).
+ * When supported, BSU/ESU sequences prevent visible flicker during redraws.
+ * @returns true when the terminal supports DEC 2026.
+ */
+export declare function isSynchronizedOutputSupported(): boolean;
+/**
+ * Record the XTVERSION response. Called once from App.tsx when the reply
+ * arrives on stdin. No-op if already set (defend against re-probe).
+ * @param name - the terminal name reported by the XTVERSION reply.
+ */
+export declare function setXtversionName(name: string): void;
+/**
+ * True if running in an xterm.js-based terminal (VS Code, Cursor, Windsurf
+ * integrated terminals). Combines TERM_PROGRAM env check (fast, sync, but
+ * not forwarded over SSH) with the XTVERSION probe result (async, survives
+ * SSH — query/reply goes through the pty). Early calls may miss the probe
+ * reply — call lazily (e.g. in an event handler) if SSH detection matters.
+ * @returns true when the terminal is xterm.js-based.
+ */
+export declare function isXtermJs(): boolean;
+/**
+ * True when the terminal can be safely probed with DECRQM
+ * (`CSI ? <mode> $ p`).
+ *
+ * DECRQM carries a `$` intermediate byte before its final `p`. A conforming
+ * parser consumes the whole sequence and either answers with DECRPM or stays
+ * silent, so callers have historically treated an unanswered probe as
+ * "unsupported" and sent it unconditionally. macOS Terminal.app breaks that
+ * assumption: it does not implement DECRQM *and* its CSI parser gives up at
+ * the `$`, printing the trailing `p` to the screen as literal text. Every
+ * probe therefore leaks a visible `p` at the cursor.
+ *
+ * Terminal.app reports `TERM=xterm-256color`, so TERM sniffing cannot tell it
+ * apart from a real xterm — `TERM_PROGRAM=Apple_Terminal` is the only marker.
+ * It is not forwarded over SSH, which matches the scope of the bug: the leak
+ * only happens when the sequence reaches Terminal.app's own parser, and a
+ * remote session is parsed by whatever terminal is actually attached.
+ *
+ * Kept as an exclusion rather than an allowlist so unknown terminals keep the
+ * (correct, spec-conforming) probe and only the known-broken one opts out.
+ * Same failure mode as the extended-keys allowlist below: assuming terminals
+ * silently ignore unknown CSI is not safe in practice.
+ * @returns true when it is safe to send a DECRQM probe.
+ */
+export declare function supportsDecrqmProbe(): boolean;
+/**
+ * True if this terminal correctly handles extended key reporting
+ * (Kitty keyboard protocol + xterm modifyOtherKeys).
+ * WT_SESSION catches Windows Terminal regardless of TERM_PROGRAM (which WT
+ * doesn't set and SSH doesn't forward) — its modifyOtherKeys implementation
+ * covers navigation keys. It does NOT cover Enter (microsoft/terminal#530);
+ * Shift+Enter on native Windows needs win32-input-mode instead — see
+ * supportsWin32InputMode (issue #147).
+ * @returns true when the terminal is on the extended-keys allowlist.
+ */
+export declare function supportsExtendedKeys(): boolean;
+/**
+ * True when win32-input-mode (DECSET 9001, `CSI ? 9001 h`) should drive
+ * keyboard input. This is a ConPTY feature — both Windows Terminal and
+ * classic conhost switch into it when the app emits the sequence. In this
+ * mode every key arrives as a full INPUT_RECORD
+ * (`CSI Vk;Sc;Uc;Kd;Cs;Rc _`), the only encoding that
+ * preserves Enter's Shift/Ctrl bits on Windows (issue #147). It replaces
+ * the kitty/modifyOtherKeys push — callers must treat them as mutually
+ * exclusive. Non-ConPTY Windows terminals (mintty via winpty) ignore the
+ * unknown private mode and fall back to classic VT input unchanged.
+ *
+ * Embedded xterm.js hosts may identify as `TERM_PROGRAM=vscode` while using
+ * the xterm.js engine version as TERM_PROGRAM_VERSION (Termy 1.4.1 reports
+ * 6.0.0). They do not provide native ConPTY's input-mode contract: enabling
+ * 9001 can reduce arrows/mouse sequences to their trailing A-D/M bytes and
+ * interfere with IME commits (issue #215). Native VS Code reports its own
+ * 1.x application version and retains win32-input-mode support.
+ * @returns true on native Windows (never in WSL — platform is linux there).
+ */
+export declare function supportsWin32InputMode(platform?: NodeJS.Platform, termProgram?: string | undefined, termProgramVersion?: string | undefined): boolean;
+/**
+ * True if the terminal scrolls the viewport when it receives cursor-up
+ * sequences that reach above the visible area. On Windows, conhost's
+ * SetConsoleCursorPosition follows the cursor into scrollback
+ * (microsoft/terminal#14774), yanking users to the top of their buffer
+ * mid-stream. WT_SESSION catches WSL-in-Windows-Terminal where platform
+ * is linux but output still routes through conhost.
+ * @returns true when the cursor-up viewport-yank bug applies.
+ */
+export declare function hasCursorUpViewportYankBug(): boolean;
+/**
+ * Whether synchronized output (DEC 2026) is available, computed once at
+ * module load — terminal capabilities don't change mid-session. Exported
+ * so callers can pass a sync-skip hint gated to specific modes.
+ */
+export declare const SYNC_OUTPUT_SUPPORTED: boolean;
+/**
+ * Whether the DECSTBM hardware-scroll optimization may be used to paint
+ * ScrollBox scrolls. Called once per frame — the same env reads as the
+ * SYNC_OUTPUT_SUPPORTED gate, so the extra cost is a single comparison.
+ *
+ * JediTerm is explicitly excluded even though it implements DEC 2026: its
+ * scroll-region (DECSTBM) + CSI S/T handling deviates from xterm and, when
+ * driven per-frame by a diffing renderer, corrupts the screen progressively
+ * as content scrolls (the "JetBrains terminal slowly garbles" bug class).
+ * The diff engine falls back to repainting the shifted rows cell-by-cell,
+ * which every terminal renders identically. Disable DECSTBM on JetBrains terminals.
+ *
+ * zellij is excluded for the same class of reason. Its `CSI T`
+ * (grid.rs rotate_scroll_region_up) shifts rows only while the cursor sits
+ * inside the scroll region, and its `CSI r` does not home the cursor outside
+ * origin mode — but the renderer parks the cursor on the last screen row,
+ * below every ScrollBox. The shift is silently dropped while the diff assumes
+ * it happened, so stale rows survive every scroll-up frame (tearing, leftover
+ * transcript lines). Only DECSTBM is withdrawn: zellij does implement DEC
+ * 2026, so BSU/ESU stay on and frames remain atomic.
+ * @returns true when DECSTBM scroll optimization is safe on this terminal.
+ */
+export declare function isDecstbmSafe(): boolean;
+/**
+ * The output streams a terminal renders to.
+ */
+export type Terminal = {
+    stdout: Writable;
+    stderr: Writable;
+};
+/**
+ * Write a frame diff to the terminal as a single buffered write. Wraps
+ * the output in BSU/ESU synchronized-update markers unless skipSyncMarkers
+ * is set. No-op when the diff contains no patches.
+ * @param terminal - the terminal to write to.
+ * @param diff - the frame diff patches to render.
+ * @param skipSyncMarkers - when true, omit the BSU/ESU wrapping.
+ */
+/**
+ * Serialize a frame diff into a single ANSI string (BSU/ESU-wrapped unless
+ * skipSyncMarkers is set). Empty string when the diff has no patches.
+ * Extracted from writeDiffToTerminal so shutdown paths can write the last
+ * frame synchronously (issue #522: an async frame write racing the
+ * synchronous EXIT_ALT_SCREEN lands on the MAIN screen after the alt
+ * screen is gone, leaving misplaced residue).
+ */
+export declare function serializeDiff(terminal: Terminal, diff: Diff, skipSyncMarkers?: boolean): string;
+/**
+ * Write a frame diff to the terminal as a single buffered write. Wraps
+ * the output in BSU/ESU synchronized-update markers unless skipSyncMarkers
+ * is set. No-op when the diff contains no patches.
+ * @param terminal - the terminal to write to.
+ * @param diff - the frame diff patches to render.
+ * @param skipSyncMarkers - when true, omit the BSU/ESU wrapping.
+ */
+export declare function writeDiffToTerminal(terminal: Terminal, diff: Diff, skipSyncMarkers?: boolean): void;
+//# sourceMappingURL=terminal.d.ts.map

package/lib/types/ink/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../../../src/ink/terminal.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAKtC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAYtC;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,OAAO,GAAG,eAAe,CAAA;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,IAAI,OAAO,CAuCtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CAElC;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,IAAI,OAAO,CAwDvD;AAcD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEnD;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAGnC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAyBD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAG9C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAC5C,WAAW,GAAE,MAAM,GAAG,SAAoC,EAC1D,kBAAkB,GAAE,MAAM,GAAG,SAA4C,GACxE,OAAO,CAOT;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,SAAkC,CAAA;AAEpE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAuBD;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,MAAM,EAAE,QAAQ,CAAA;IAChB,MAAM,EAAE,QAAQ,CAAA;CACjB,CAAA;AAED;;;;;;;GAOG;AACH;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,IAAI,EACV,eAAe,UAAQ,GACtB,MAAM,CAwFR;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,IAAI,EACV,eAAe,UAAQ,GACtB,IAAI,CAMN"}