@deepseek-harness-tui/dsh-tui 0.5.0

package/lib/types/customTheme.js

@@ -0,0 +1,268 @@
+/**
+ * User-defined color themes for dsh-tui.
+ *
+ * A theme is a JSON file in `~/.dsh-cc/themes/<name>.json`:
+ *
+ * ```json
+ * { "name": "sakura", "displayName": "Sakura Pink", "base": "dark",
+ *   "colors": { "claude": "#FF9EC7", "text": "#E8E6E0" } }
+ * ```
+ *
+ * `base` is required (`light`/`dark`/`dark-ansi`) and selects the built-in
+ * palette the file overlays; `colors` holds a subset of Theme keys. `name`
+ * defaults to the file name; `displayName` defaults to `name`.
+ *
+ * Validation is best-effort per key: unknown keys and invalid color values
+ * are skipped with a warning on stderr, never fatal; a file whose JSON is
+ * malformed or whose `base` is invalid is skipped entirely (also warned).
+ * Accepted color value forms (the same forms the built-in palettes and the
+ * Ink color engine use): `#rgb`, `#rrggbb`, `#rrggbbaa`, `rgb(r,g,b)`,
+ * `ansi256(n)` and the 16 `ansi:` names.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { getTheme } from './theme.js';
+/** The base palettes a user theme may overlay. */
+export const THEME_BASE_NAMES = ['light', 'dark', 'dark-ansi'];
+/** The directory user theme files live in (~/.dsh-cc/themes). */
+export const CUSTOM_THEME_DIR = join(homedir(), '.dsh-cc', 'themes');
+// #rgb / #rrggbb / #rrggbbaa
+const HEX_RE = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+// rgb(r,g,b) — the storage form of the built-in truecolor palettes
+const RGB_RE = /^rgb\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*\)$/;
+// ansi256(n) — supported by the Ink color engine
+const ANSI256_RE = /^ansi256\(\s*(\d{1,3})\s*\)$/;
+// The 16 standard ANSI names (the dark-ansi palette's storage form)
+const ANSI_NAMES = new Set([
+    'ansi:black',
+    'ansi:red',
+    'ansi:green',
+    'ansi:yellow',
+    'ansi:blue',
+    'ansi:magenta',
+    'ansi:cyan',
+    'ansi:white',
+    'ansi:blackBright',
+    'ansi:redBright',
+    'ansi:greenBright',
+    'ansi:yellowBright',
+    'ansi:blueBright',
+    'ansi:magentaBright',
+    'ansi:cyanBright',
+    'ansi:whiteBright',
+]);
+/** Resolved custom palettes, keyed by theme name (never caches failures). */
+const cache = new Map();
+/**
+ * `spec.name` → load key (file name), so a theme whose `name` field differs
+ * from its file name still resolves (CC_TUI_THEME, /theme, persistence all
+ * speak the display name). Filled lazily on the first name miss.
+ */
+const nameIndex = new Map();
+let nameIndexed = false;
+function isThemeBase(value) {
+    return THEME_BASE_NAMES.includes(value);
+}
+/**
+ * Whether a name is safe to use as a file name (no path separators or dot
+ * traversal). Theme names are user input from CC_TUI_THEME and /theme, so
+ * they must never escape the themes directory.
+ */
+export function isSafeThemeName(name) {
+    return (name.length > 0 &&
+        name !== '.' &&
+        name !== '..' &&
+        !name.includes('/') &&
+        !name.includes('\\'));
+}
+/**
+ * Whether a value is an accepted color string: #rgb/#rrggbb/#rrggbbaa,
+ * rgb(r,g,b), ansi256(n) or one of the 16 ansi: names — the same forms the
+ * built-in palettes and the Ink color engine accept.
+ * @param value - Candidate color value.
+ * @returns True when the value is a well-formed color string.
+ */
+export function isValidThemeColor(value) {
+    if (typeof value !== 'string')
+        return false;
+    if (HEX_RE.test(value))
+        return true;
+    const rgb = RGB_RE.exec(value);
+    if (rgb !== null) {
+        return rgb.slice(1).every(channel => Number(channel) <= 255);
+    }
+    const ansi = ANSI256_RE.exec(value);
+    if (ansi !== null)
+        return Number(ansi[1]) <= 255;
+    return ANSI_NAMES.has(value);
+}
+function warn(message) {
+    console.warn(`[dsh-tui] ${message}`);
+}
+/**
+ * Parse and validate a theme file's contents. Unknown keys and invalid
+ * color values are skipped (each warned); a file that is not an object,
+ * has an invalid `base`, or has a non-object `colors` is rejected entirely.
+ * @param text - Raw file contents.
+ * @param fileName - File name (with or without the .json extension); the
+ *   load key and the default theme name when the file omits `name`.
+ * @returns The validated spec, or undefined when the file is unusable.
+ */
+export function parseCustomTheme(text, fileName) {
+    const fileKey = fileName.toLowerCase().endsWith('.json')
+        ? fileName.slice(0, -'.json'.length)
+        : fileName;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        warn(`theme file "${fileName}" is not valid JSON; skipped`);
+        return undefined;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        warn(`theme file "${fileName}" is not a JSON object; skipped`);
+        return undefined;
+    }
+    const raw = parsed;
+    const base = raw.base;
+    if (typeof base !== 'string' || !isThemeBase(base)) {
+        warn(`theme "${fileName}": invalid or missing "base" (expected light|dark|dark-ansi); file skipped`);
+        return undefined;
+    }
+    const name = typeof raw.name === 'string' && raw.name.trim() !== '' ? raw.name.trim() : fileKey;
+    if (!isSafeThemeName(name)) {
+        warn(`theme "${fileName}": unsafe "name" ("${name}"); file skipped`);
+        return undefined;
+    }
+    const displayName = typeof raw.displayName === 'string' && raw.displayName.trim() !== ''
+        ? raw.displayName.trim()
+        : name;
+    const colorsRaw = raw.colors;
+    if (colorsRaw === undefined) {
+        return { name, displayName, base, colors: {}, file: fileKey };
+    }
+    if (colorsRaw === null ||
+        typeof colorsRaw !== 'object' ||
+        Array.isArray(colorsRaw)) {
+        warn(`theme "${fileName}": "colors" must be an object; file skipped`);
+        return undefined;
+    }
+    // Key/color validation against the base palette, so unknown keys and bad
+    // values are skipped per key (warned) instead of killing the theme.
+    const baseTheme = getTheme(base);
+    const colors = {};
+    for (const [key, value] of Object.entries(colorsRaw)) {
+        if (!(key in baseTheme)) {
+            warn(`theme "${fileName}": unknown color key "${key}" skipped`);
+            continue;
+        }
+        if (!isValidThemeColor(value)) {
+            warn(`theme "${fileName}": invalid color value for "${key}" (want #rgb/#rrggbb/#rrggbbaa, rgb(r,g,b), ansi256(n) or ansi:name); skipped`);
+            continue;
+        }
+        colors[key] = value;
+    }
+    return { name, displayName, base, colors, file: fileKey };
+}
+/**
+ * Load and validate one user theme by name.
+ * @param name - Theme name (file name without .json).
+ * @param dir - Themes directory (injectable for tests).
+ * @returns The validated spec, or undefined when missing/invalid.
+ */
+export function loadCustomTheme(name, dir = CUSTOM_THEME_DIR) {
+    if (!isSafeThemeName(name))
+        return undefined;
+    try {
+        return parseCustomTheme(readFileSync(join(dir, `${name}.json`), 'utf8'), name);
+    }
+    catch {
+        // Missing or unreadable file: a normal condition during discovery, no warning.
+        return undefined;
+    }
+}
+/**
+ * Discover every usable user theme in the themes directory, sorted by name.
+ * Invalid files are skipped (each warned by parseCustomTheme).
+ * @param dir - Themes directory (injectable for tests).
+ * @returns The validated specs found.
+ */
+export function listCustomThemes(dir = CUSTOM_THEME_DIR) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter(entry => entry.toLowerCase().endsWith('.json'))
+        .map(entry => entry.slice(0, -'.json'.length))
+        .filter(isSafeThemeName)
+        .map(name => loadCustomTheme(name, dir))
+        .filter((spec) => spec !== undefined)
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Overlay a spec's overrides onto its base palette.
+ * @param spec - Validated theme spec.
+ * @returns The full concrete palette.
+ */
+export function buildTheme(spec) {
+    return { ...getTheme(spec.base), ...spec.colors };
+}
+/**
+ * Resolve a user theme name to its full palette, cached after first load.
+ * A `name` field that differs from the file name is indexed on the first
+ * miss, so display names resolve everywhere. Failures are not cached, so a
+ * file fixed while the TUI runs can be picked up on the next attempt.
+ * @param name - User theme name.
+ * @returns The built palette, or undefined when unknown/invalid.
+ */
+export function resolveCustomTheme(name) {
+    if (!isSafeThemeName(name))
+        return undefined;
+    const cached = cache.get(name);
+    if (cached !== undefined)
+        return cached;
+    indexCustomThemeNames();
+    const file = nameIndex.get(name) ?? name;
+    const spec = loadCustomTheme(file);
+    if (spec === undefined)
+        return undefined;
+    const theme = buildTheme(spec);
+    cache.set(name, theme);
+    return theme;
+}
+/**
+ * Index every discovered theme's `name` → file name once, lazily. Kept
+ * separate from the palette cache so a miss is cheap after the first scan.
+ */
+function indexCustomThemeNames() {
+    if (nameIndexed)
+        return;
+    for (const spec of listCustomThemes()) {
+        nameIndex.set(spec.name, spec.file);
+    }
+    nameIndexed = true;
+}
+/**
+ * Whether a name selects a usable theme: a built-in palette or a valid user
+ * theme file. Used for CC_TUI_THEME / persisted-preference validation and
+ * the runtime /theme switch.
+ * @param name - Candidate theme name.
+ * @returns True when the theme resolves.
+ */
+export function isThemeAvailable(name) {
+    if (isThemeBase(name))
+        return true;
+    return resolveCustomTheme(name) !== undefined;
+}
+/** Drop the resolved-theme cache and name index (tests, or after themes change on disk). */
+export function clearCustomThemeCache() {
+    cache.clear();
+    nameIndex.clear();
+    nameIndexed = false;
+}

package/lib/types/effortPrefs.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Persisted reasoning-effort preference (`~/.dsh-cc/effort.json`). Shift+Tab
+ * cycles the live route's adapter-owned levels (dsh-llm `LlmModelReasoningInfo`);
+ * the choice lands here so the next boot starts on it. The file is
+ * best-effort: a missing/corrupt file or a level the current adapter does not
+ * offer just falls back to the provider default — the first request/header
+ * event always re-asserts the truth on the status line.
+ */
+/**
+ * The persisted reasoning-effort id, or undefined when unset or invalid.
+ * @param dir - Prefs directory (injectable for tests).
+ * @returns The persisted effort id, if any.
+ */
+export declare function readEffortPref(dir?: string): string | undefined;
+/**
+ * Persist the chosen reasoning-effort id (best effort).
+ * @param effort - Adapter-owned effort id to persist.
+ * @param dir - Prefs directory (injectable for tests).
+ * @returns True when the file was written, false on failure.
+ */
+export declare function writeEffortPref(effort: string, dir?: string): boolean;
+//# sourceMappingURL=effortPrefs.d.ts.map

package/lib/types/effortPrefs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effortPrefs.d.ts","sourceRoot":"","sources":["../../src/effortPrefs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAkB,GAAG,MAAM,GAAG,SAAS,CAS1E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,GAAE,MAAkB,GAAG,OAAO,CAQhF"}

package/lib/types/effortPrefs.js

@@ -0,0 +1,45 @@
+/**
+ * Persisted reasoning-effort preference (`~/.dsh-cc/effort.json`). Shift+Tab
+ * cycles the live route's adapter-owned levels (dsh-llm `LlmModelReasoningInfo`);
+ * the choice lands here so the next boot starts on it. The file is
+ * best-effort: a missing/corrupt file or a level the current adapter does not
+ * offer just falls back to the provider default — the first request/header
+ * event always re-asserts the truth on the status line.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const PREFS_DIR = join(homedir(), '.dsh-cc');
+/**
+ * The persisted reasoning-effort id, or undefined when unset or invalid.
+ * @param dir - Prefs directory (injectable for tests).
+ * @returns The persisted effort id, if any.
+ */
+export function readEffortPref(dir = PREFS_DIR) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(dir, 'effort.json'), 'utf8'));
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return undefined;
+        const effort = parsed.effort;
+        return typeof effort === 'string' && effort !== '' ? effort : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Persist the chosen reasoning-effort id (best effort).
+ * @param effort - Adapter-owned effort id to persist.
+ * @param dir - Prefs directory (injectable for tests).
+ * @returns True when the file was written, false on failure.
+ */
+export function writeEffortPref(effort, dir = PREFS_DIR) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, 'effort.json'), JSON.stringify({ effort }, null, 2));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/lib/types/history.d.ts

@@ -0,0 +1,24 @@
+/** One persisted input-history entry. */
+export type HistoryEntry = {
+    text: string;
+    /** Unix ms timestamp. */
+    ts: number;
+};
+/**
+ * Append an input to the persisted history, deduping the immediately
+ * previous entry and capping the file at 200 entries.
+ * @param text - Input to persist; blank inputs are ignored.
+ */
+export declare function appendHistory(text: string): void;
+/**
+ * Read the persisted history, newest first.
+ * @returns The persisted entries in reverse-chronological order.
+ */
+export declare function loadHistory(): HistoryEntry[];
+/**
+ * Stable id for a history entry (dedupes React keys across identical texts).
+ * @param entry - The history entry to hash.
+ * @returns A 12-char hex id derived from the entry text.
+ */
+export declare function historyEntryId(entry: HistoryEntry): string;
+//# sourceMappingURL=history.d.ts.map

package/lib/types/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/history.ts"],"names":[],"mappings":"AAQA,yCAAyC;AACzC,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,yBAAyB;IACzB,EAAE,EAAE,MAAM,CAAA;CACX,CAAA;AA0BD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAuBhD;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,YAAY,EAAE,CAE5C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAE1D"}

package/lib/types/history.js

@@ -0,0 +1,75 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const HISTORY_DIR = join(homedir(), '.dsh-cc');
+const HISTORY_FILE = join(HISTORY_DIR, 'history.jsonl');
+const HISTORY_LIMIT = 200;
+function loadRaw() {
+    if (!existsSync(HISTORY_FILE))
+        return [];
+    const entries = [];
+    try {
+        for (const line of readFileSync(HISTORY_FILE, 'utf8').split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (typeof parsed.text === 'string' && parsed.text.length > 0) {
+                    entries.push({ text: parsed.text, ts: typeof parsed.ts === 'number' ? parsed.ts : 0 });
+                }
+            }
+            catch {
+                // Skip malformed lines; the file is best-effort.
+            }
+        }
+    }
+    catch {
+        return [];
+    }
+    return entries;
+}
+/**
+ * Append an input to the persisted history, deduping the immediately
+ * previous entry and capping the file at 200 entries.
+ * @param text - Input to persist; blank inputs are ignored.
+ */
+export function appendHistory(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return;
+    const entries = loadRaw();
+    // Skip consecutive duplicates (CC behavior: repeated submits of the same
+    // command only advance the existing entry's timestamp).
+    const last = entries[entries.length - 1];
+    if (last && last.text === trimmed) {
+        last.ts = Date.now();
+    }
+    else {
+        entries.push({ text: trimmed, ts: Date.now() });
+    }
+    const sliced = entries.slice(-HISTORY_LIMIT);
+    try {
+        mkdirSync(HISTORY_DIR, { recursive: true });
+        writeFileSync(HISTORY_FILE, sliced.map(e => JSON.stringify(e)).join('\n') + '\n', 'utf8');
+    }
+    catch {
+        // Best-effort persistence; history still works for the session.
+    }
+}
+/**
+ * Read the persisted history, newest first.
+ * @returns The persisted entries in reverse-chronological order.
+ */
+export function loadHistory() {
+    return loadRaw().reverse();
+}
+/**
+ * Stable id for a history entry (dedupes React keys across identical texts).
+ * @param entry - The history entry to hash.
+ * @returns A 12-char hex id derived from the entry text.
+ */
+export function historyEntryId(entry) {
+    return createHash('sha1').update(entry.text).digest('hex').slice(0, 12);
+}

package/lib/types/hooks/useBlink.d.ts

@@ -0,0 +1,11 @@
+import type { DOMElement } from '../ink/dom.js';
+/**
+ * Hook for synchronized blinking animations that pause when offscreen
+ * (ported from the leak's `src/hooks/useBlink.ts`).
+ *
+ * @param enabled - Whether blinking is active
+ * @param intervalMs - Blink cycle length in ms; defaults to 600.
+ * @returns [ref, isVisible] - Ref to attach to element, true when visible in blink cycle
+ */
+export declare function useBlink(enabled: boolean, intervalMs?: number): [ref: (element: DOMElement | null) => void, isVisible: boolean];
+//# sourceMappingURL=useBlink.d.ts.map

package/lib/types/hooks/useBlink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBlink.d.ts","sourceRoot":"","sources":["../../../src/hooks/useBlink.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAM/C;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,OAAO,EAChB,UAAU,GAAE,MAA0B,GACrC,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,KAAK,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,CASjE"}

package/lib/types/hooks/useBlink.js

@@ -0,0 +1,20 @@
+import { useAnimationFrame } from '../ink/hooks/use-animation-frame.js';
+import { useTerminalFocus } from '../ink/hooks/use-terminal-focus.js';
+const BLINK_INTERVAL_MS = 600;
+/**
+ * Hook for synchronized blinking animations that pause when offscreen
+ * (ported from the leak's `src/hooks/useBlink.ts`).
+ *
+ * @param enabled - Whether blinking is active
+ * @param intervalMs - Blink cycle length in ms; defaults to 600.
+ * @returns [ref, isVisible] - Ref to attach to element, true when visible in blink cycle
+ */
+export function useBlink(enabled, intervalMs = BLINK_INTERVAL_MS) {
+    const focused = useTerminalFocus();
+    const [ref, time] = useAnimationFrame(enabled && focused ? intervalMs : null);
+    if (!enabled || !focused)
+        return [ref, true];
+    // Derive blink state from time - all instances see the same time so they sync
+    const isVisible = Math.floor(time / intervalMs) % 2 === 0;
+    return [ref, isVisible];
+}