aiden-runtime 4.0.2 → 4.1.0

package/dist/cli/v4/syntaxHighlight.js

@@ -0,0 +1,345 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/syntaxHighlight.ts — Phase v4.1-reply-formatting
+ *
+ * Lightweight regex-based syntax highlighter for fenced code blocks.
+ * No external dependency. Languages with first-class support:
+ *   - typescript / javascript / ts / js
+ *   - python / py
+ *   - shell / bash / sh / zsh
+ *   - json
+ *   - yaml / yml
+ *
+ * Unknown languages fall through with no highlighting (returns the
+ * input verbatim) so the renderer never breaks on exotic fences.
+ *
+ * Tokenization is order-sensitive: comments/strings first (so a
+ * keyword inside a string isn't recoloured), then numbers, then
+ * keywords. The regex passes are conservative — they paint by
+ * token shape, not by full grammar — but they handle the common
+ * 90% case well enough for terminal display.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.highlightCode = highlightCode;
+exports.isSupportedLang = isSupportedLang;
+const skinEngine_1 = require("./skinEngine");
+function normalizeLang(raw) {
+    const s = (raw ?? '').toLowerCase().trim();
+    if (s === 'ts' || s === 'tsx' || s === 'typescript')
+        return 'typescript';
+    if (s === 'js' || s === 'jsx' || s === 'javascript')
+        return 'javascript';
+    if (s === 'py' || s === 'python')
+        return 'python';
+    if (s === 'sh' || s === 'bash' || s === 'zsh' || s === 'shell')
+        return 'shell';
+    if (s === 'json')
+        return 'json';
+    if (s === 'yaml' || s === 'yml')
+        return 'yaml';
+    return 'unknown';
+}
+const TS_KEYWORDS = new Set([
+    'const', 'let', 'var', 'function', 'return', 'if', 'else', 'for', 'while', 'do',
+    'break', 'continue', 'switch', 'case', 'default', 'async', 'await', 'class',
+    'extends', 'implements', 'new', 'this', 'super', 'import', 'export', 'from',
+    'as', 'typeof', 'instanceof', 'interface', 'type', 'enum', 'public', 'private',
+    'protected', 'readonly', 'static', 'void', 'never', 'any', 'unknown', 'true',
+    'false', 'null', 'undefined', 'throw', 'try', 'catch', 'finally', 'yield',
+    'in', 'of',
+]);
+const PY_KEYWORDS = new Set([
+    'def', 'return', 'if', 'elif', 'else', 'for', 'while', 'break', 'continue',
+    'import', 'from', 'as', 'class', 'pass', 'raise', 'try', 'except', 'finally',
+    'with', 'lambda', 'yield', 'global', 'nonlocal', 'True', 'False', 'None',
+    'and', 'or', 'not', 'is', 'in', 'async', 'await', 'assert', 'del',
+]);
+const SH_KEYWORDS = new Set([
+    'if', 'then', 'else', 'elif', 'fi', 'for', 'do', 'done', 'while', 'until', 'case',
+    'esac', 'function', 'return', 'export', 'local', 'readonly', 'in', 'select',
+]);
+/** ANSI-paint a token with the active skin's colour kind. */
+function paint(text, kind) {
+    return (0, skinEngine_1.getSkinEngine)().applyColors(text, kind);
+}
+/**
+ * Walk `code` building an output string. Identifies regions by a
+ * simple state machine: STRING → COMMENT → NUMBER → IDENT (which
+ * may be a keyword). Anything else is emitted verbatim.
+ *
+ * Returns the painted string. Pure — no side effects.
+ */
+function highlightTsJs(code, kw) {
+    let out = '';
+    let i = 0;
+    const n = code.length;
+    while (i < n) {
+        const c = code[i];
+        // Single-line comment
+        if (c === '/' && code[i + 1] === '/') {
+            const end = code.indexOf('\n', i);
+            const stop = end === -1 ? n : end;
+            out += paint(code.slice(i, stop), 'muted');
+            i = stop;
+            continue;
+        }
+        // Block comment
+        if (c === '/' && code[i + 1] === '*') {
+            const end = code.indexOf('*/', i);
+            const stop = end === -1 ? n : end + 2;
+            out += paint(code.slice(i, stop), 'muted');
+            i = stop;
+            continue;
+        }
+        // Strings (', ", `)
+        if (c === '"' || c === "'" || c === '`') {
+            const quote = c;
+            let j = i + 1;
+            while (j < n && code[j] !== quote) {
+                if (code[j] === '\\' && j + 1 < n) {
+                    j += 2;
+                    continue;
+                }
+                j += 1;
+            }
+            const stop = j < n ? j + 1 : n;
+            out += paint(code.slice(i, stop), 'success');
+            i = stop;
+            continue;
+        }
+        // Numbers
+        if (/[0-9]/.test(c) && (i === 0 || !/[a-zA-Z_$]/.test(code[i - 1] ?? ''))) {
+            let j = i;
+            while (j < n && /[0-9.eExX_a-fA-F]/.test(code[j] ?? ''))
+                j += 1;
+            out += paint(code.slice(i, j), 'accent');
+            i = j;
+            continue;
+        }
+        // Identifiers / keywords
+        if (/[a-zA-Z_$]/.test(c)) {
+            let j = i;
+            while (j < n && /[a-zA-Z0-9_$]/.test(code[j] ?? ''))
+                j += 1;
+            const word = code.slice(i, j);
+            out += kw.has(word) ? paint(word, 'brand') : word;
+            i = j;
+            continue;
+        }
+        out += c;
+        i += 1;
+    }
+    return out;
+}
+function highlightPython(code) {
+    // Python: # comments, '/" strings, numbers, keywords. Same engine
+    // as TS/JS but with a `#` comment and Python keyword set.
+    let out = '';
+    let i = 0;
+    const n = code.length;
+    while (i < n) {
+        const c = code[i];
+        if (c === '#') {
+            const end = code.indexOf('\n', i);
+            const stop = end === -1 ? n : end;
+            out += paint(code.slice(i, stop), 'muted');
+            i = stop;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            const quote = c;
+            // Triple-quote support
+            const triple = code[i + 1] === quote && code[i + 2] === quote;
+            let j = triple ? i + 3 : i + 1;
+            const closer = triple ? quote.repeat(3) : quote;
+            while (j < n) {
+                if (code.startsWith(closer, j)) {
+                    j += closer.length;
+                    break;
+                }
+                if (code[j] === '\\' && j + 1 < n) {
+                    j += 2;
+                    continue;
+                }
+                j += 1;
+            }
+            out += paint(code.slice(i, j), 'success');
+            i = j;
+            continue;
+        }
+        if (/[0-9]/.test(c) && (i === 0 || !/[a-zA-Z_]/.test(code[i - 1] ?? ''))) {
+            let j = i;
+            while (j < n && /[0-9._jJ]/.test(code[j] ?? ''))
+                j += 1;
+            out += paint(code.slice(i, j), 'accent');
+            i = j;
+            continue;
+        }
+        if (/[a-zA-Z_]/.test(c)) {
+            let j = i;
+            while (j < n && /[a-zA-Z0-9_]/.test(code[j] ?? ''))
+                j += 1;
+            const word = code.slice(i, j);
+            out += PY_KEYWORDS.has(word) ? paint(word, 'brand') : word;
+            i = j;
+            continue;
+        }
+        out += c;
+        i += 1;
+    }
+    return out;
+}
+function highlightShell(code) {
+    let out = '';
+    let i = 0;
+    const n = code.length;
+    while (i < n) {
+        const c = code[i];
+        if (c === '#' && (i === 0 || code[i - 1] === '\n' || code[i - 1] === ' ')) {
+            const end = code.indexOf('\n', i);
+            const stop = end === -1 ? n : end;
+            out += paint(code.slice(i, stop), 'muted');
+            i = stop;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            const quote = c;
+            let j = i + 1;
+            while (j < n && code[j] !== quote) {
+                if (code[j] === '\\' && j + 1 < n) {
+                    j += 2;
+                    continue;
+                }
+                j += 1;
+            }
+            const stop = j < n ? j + 1 : n;
+            out += paint(code.slice(i, stop), 'success');
+            i = stop;
+            continue;
+        }
+        if (/[a-zA-Z_]/.test(c)) {
+            let j = i;
+            while (j < n && /[a-zA-Z0-9_]/.test(code[j] ?? ''))
+                j += 1;
+            const word = code.slice(i, j);
+            out += SH_KEYWORDS.has(word) ? paint(word, 'brand') : word;
+            i = j;
+            continue;
+        }
+        out += c;
+        i += 1;
+    }
+    return out;
+}
+function highlightJson(code) {
+    // JSON has only strings, numbers, true/false/null, and structure.
+    let out = '';
+    let i = 0;
+    const n = code.length;
+    while (i < n) {
+        const c = code[i];
+        if (c === '"') {
+            let j = i + 1;
+            while (j < n && code[j] !== '"') {
+                if (code[j] === '\\' && j + 1 < n) {
+                    j += 2;
+                    continue;
+                }
+                j += 1;
+            }
+            const stop = j < n ? j + 1 : n;
+            // Treat key (followed by ':') vs value distinct.
+            // Skip whitespace after to peek at the next non-space char.
+            let k = stop;
+            while (k < n && /\s/.test(code[k] ?? ''))
+                k += 1;
+            const isKey = code[k] === ':';
+            out += paint(code.slice(i, stop), isKey ? 'heading' : 'success');
+            i = stop;
+            continue;
+        }
+        if (/[0-9-]/.test(c) && /[0-9]/.test(code[i + 1] ?? c)) {
+            let j = i;
+            while (j < n && /[0-9.eE+-]/.test(code[j] ?? ''))
+                j += 1;
+            out += paint(code.slice(i, j), 'accent');
+            i = j;
+            continue;
+        }
+        if (/[a-zA-Z]/.test(c)) {
+            let j = i;
+            while (j < n && /[a-zA-Z]/.test(code[j] ?? ''))
+                j += 1;
+            const word = code.slice(i, j);
+            if (word === 'true' || word === 'false' || word === 'null') {
+                out += paint(word, 'brand');
+            }
+            else {
+                out += word;
+            }
+            i = j;
+            continue;
+        }
+        out += c;
+        i += 1;
+    }
+    return out;
+}
+function highlightYaml(code) {
+    // Simple per-line: comments to '#', `key:` keys, strings.
+    return code
+        .split('\n')
+        .map((line) => {
+        const trimStart = line.match(/^\s*/)?.[0] ?? '';
+        const rest = line.slice(trimStart.length);
+        if (rest.startsWith('#'))
+            return trimStart + paint(rest, 'muted');
+        // key:
+        const m = /^([A-Za-z_][\w-]*)(\s*):(\s*)(.*)$/.exec(rest);
+        if (m) {
+            const [, key, padBeforeColon, padAfter, value] = m;
+            const valOut = /^['"]/.test(value)
+                ? paint(value, 'success')
+                : /^-?\d/.test(value)
+                    ? paint(value, 'accent')
+                    : value === 'true' || value === 'false' || value === 'null'
+                        ? paint(value, 'brand')
+                        : value;
+            return `${trimStart}${paint(key, 'heading')}${padBeforeColon}:${padAfter}${valOut}`;
+        }
+        // Bullet lists
+        if (rest.startsWith('- ')) {
+            return trimStart + paint('-', 'muted') + ' ' + rest.slice(2);
+        }
+        return line;
+    })
+        .join('\n');
+}
+/**
+ * Highlight `code` according to `lang`. Returns the painted string.
+ * If `lang` is unknown or empty, returns the input verbatim.
+ */
+function highlightCode(code, lang) {
+    const norm = normalizeLang(lang);
+    switch (norm) {
+        case 'typescript':
+        case 'javascript':
+            return highlightTsJs(code, TS_KEYWORDS);
+        case 'python': return highlightPython(code);
+        case 'shell': return highlightShell(code);
+        case 'json': return highlightJson(code);
+        case 'yaml': return highlightYaml(code);
+        case 'unknown':
+        default: return code;
+    }
+}
+/** Tiny helper for tests. */
+function isSupportedLang(lang) {
+    return normalizeLang(lang) !== 'unknown';
+}

package/dist/cli/v4/table.js

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/table.ts — lightweight ASCII table renderer (Tier-3.1).
+ *
+ * Drop-in replacement for `Display.twoColumnBlock` style output at
+ * call sites that want full multi-column tables (`/skills`,
+ * `/cron list`, `/channel list`). No `cli-table3` dependency — the
+ * renderer is ~150 lines, ANSI-aware via `string-width`, and uses
+ * the same SkinEngine colour kinds as the rest of v4.
+ *
+ * Box drawing is sharp ASCII (`─ │ ┌ ┐ └ ┘ ├ ┤`) to stay aligned
+ * with the rest of the v4.1-tier3.1 box pass.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderTable = renderTable;
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const stringWidth = require('string-width');
+const skinEngine_1 = require("./skinEngine");
+const box_1 = require("./box");
+/**
+ * Visible (post-ANSI-strip) column width. Falls back to
+ * `visibleLength` from box.ts when string-width is unavailable
+ * (which would only happen if the dep was removed).
+ */
+function vWidth(s) {
+    try {
+        return stringWidth(s);
+    }
+    catch {
+        return (0, box_1.visibleLength)(s);
+    }
+}
+/** Pad `s` to `w` visible columns using `align`. ANSI-safe. */
+function pad(s, w, align = 'left') {
+    const sw = vWidth(s);
+    if (sw >= w)
+        return s;
+    const gap = w - sw;
+    if (align === 'right')
+        return ' '.repeat(gap) + s;
+    if (align === 'center') {
+        const l = Math.floor(gap / 2);
+        return ' '.repeat(l) + s + ' '.repeat(gap - l);
+    }
+    return s + ' '.repeat(gap);
+}
+/** Truncate to `max` visible columns with a single `…` tail. */
+function truncCell(s, max) {
+    if (vWidth(s) <= max)
+        return s;
+    if (max <= 1)
+        return '…';
+    return (0, box_1.truncateVisible)(s, max - 1) + '…';
+}
+/** Resolve a column's display string for one row. */
+function cellValue(row, col) {
+    const raw = row[col.key];
+    const v = col.format ? col.format(raw, row) : (raw == null ? '' : String(raw));
+    if (col.truncate && vWidth(v) > col.truncate) {
+        return truncCell(v, col.truncate);
+    }
+    return v;
+}
+/**
+ * Tier-3.1b: word-boundary-aware truncate. Tries to cut at the last
+ * space inside `[max*0.5, max-1]` and append `…`. Falls back to the
+ * dumb mid-word cut when no space lives in that range. Never produces
+ * a result wider than `max`.
+ */
+function smartTrunc(s, max) {
+    if (vWidth(s) <= max)
+        return s;
+    if (max <= 1)
+        return '…';
+    const candidate = (0, box_1.truncateVisible)(s, max - 1);
+    // Word-boundary search — only honour spaces that leave at least
+    // half the column populated, otherwise the cell looks empty.
+    const lastSpace = candidate.lastIndexOf(' ');
+    if (lastSpace >= Math.floor(max * 0.5)) {
+        return candidate.slice(0, lastSpace) + '…';
+    }
+    return candidate + '…';
+}
+/**
+ * Tier-3.1b: allocate per-column widths to fit `available` chars.
+ * Non-flex columns prefer their natural width; flex columns absorb
+ * the leftover space proportional to their natural sizes. When even
+ * fixed columns overflow, every column is shrunk proportionally with
+ * a hard floor of 8 chars per column.
+ */
+function allocateWidths(cols, natural, available) {
+    const numCols = cols.length;
+    const totalNatural = natural.reduce((a, b) => a + b, 0);
+    if (totalNatural <= available)
+        return natural.slice();
+    // If any column declared flex:true, treat those as flex; otherwise
+    // the last column carries the flex flag (description-most case).
+    const explicitFlex = cols.some((c) => c.flex === true);
+    const flexFlags = cols.map((c, i) => explicitFlex ? c.flex === true : i === numCols - 1);
+    const fixedSum = natural.reduce((s, w, i) => s + (flexFlags[i] ? 0 : w), 0);
+    const flexNaturalSum = natural.reduce((s, w, i) => s + (flexFlags[i] ? w : 0), 0);
+    if (fixedSum >= available || flexNaturalSum === 0) {
+        // Even fixed columns don't fit — proportional shrink everything.
+        const ratio = available / Math.max(1, totalNatural);
+        return natural.map((w) => Math.max(8, Math.floor(w * ratio)));
+    }
+    const remainingForFlex = available - fixedSum;
+    return natural.map((w, i) => {
+        if (!flexFlags[i])
+            return w;
+        return Math.max(8, Math.floor(remainingForFlex * (w / flexNaturalSum)));
+    });
+}
+/**
+ * Render `rows` as an ASCII table. Returns the multi-line string
+ * (with a trailing `\n`); caller writes it via the display.
+ */
+function renderTable(rows, cols, opts = {}) {
+    const skin = (0, skinEngine_1.getSkinEngine)();
+    const indent = opts.indent ?? 2;
+    const showRule = opts.showHeaderRule !== false;
+    // Pre-compute uncoloured cell values so width math sees exact text.
+    const valueGrid = rows.map((row) => cols.map((c) => cellValue(row, c)));
+    // Natural widths — max(header, longest cell, minWidth).
+    const naturalWidths = cols.map((c, i) => {
+        let w = vWidth(c.header);
+        for (const rowVals of valueGrid) {
+            const cw = vWidth(rowVals[i]);
+            if (cw > w)
+                w = cw;
+        }
+        if (c.minWidth && c.minWidth > w)
+            w = c.minWidth;
+        return w;
+    });
+    // Tier-3.1b: responsive width allocation. Total table chars =
+    // indent + 1 (left border) + sum(width+2) + (numCols-1) inner
+    // separators + 1 (right border). Solve for content budget given
+    // the caller-provided maxWidth (or terminal columns).
+    const numCols = cols.length;
+    const overhead = indent + 3 * numCols + 1;
+    // Honor an explicit override first, then the live TTY width, then
+    // the COLUMNS env var (set by `term`-aware shells and most spawned
+    // subprocess wrappers — process.stdout.columns is `undefined` when
+    // stdout is a pipe, so falling back to env keeps tables responsive
+    // for piped consumers like /ui dashboards). Final fallback: 100.
+    const envCols = process.env.COLUMNS ? parseInt(process.env.COLUMNS, 10) : 0;
+    const maxWidth = opts.maxWidth ??
+        process.stdout.columns ??
+        (envCols > 0 ? envCols : 100);
+    const availableForContent = Math.max(numCols * 8, maxWidth - overhead);
+    const widths = allocateWidths(cols, naturalWidths, availableForContent);
+    // Apply smart truncation to any cell whose content exceeds its
+    // allocated width. Non-flex columns at natural width never trigger
+    // this branch; flex columns may.
+    for (let i = 0; i < numCols; i += 1) {
+        const w = widths[i];
+        for (const rowVals of valueGrid) {
+            if (vWidth(rowVals[i]) > w) {
+                rowVals[i] = smartTrunc(rowVals[i], w);
+            }
+        }
+    }
+    // Border characters (sharp ASCII).
+    const TL = '┌', TR = '┐', BL = '└', BR = '┘';
+    const T = '┬', B = '┴', L = '├', R = '┤';
+    const X = '┼', H = '─', V = '│';
+    const ind = ' '.repeat(indent);
+    // Top border.
+    const top = TL + widths.map((w) => H.repeat(w + 2)).join(T) + TR;
+    // Header row — heading colour, padded. Truncate first if the
+    // header itself is wider than the allocated width (rare, but
+    // keeps borders aligned under aggressive narrow-width pressure).
+    const headerCells = cols.map((c, i) => {
+        const w = widths[i];
+        const text = vWidth(c.header) > w ? smartTrunc(c.header, w) : c.header;
+        const padded = pad(text, w, c.align ?? 'left');
+        return ' ' + skin.applyColors(padded, 'heading') + ' ';
+    });
+    const headerRow = V + headerCells.join(V) + V;
+    // Header rule.
+    const rule = L + widths.map((w) => H.repeat(w + 2)).join(X) + R;
+    // Body rows.
+    const bodyLines = [];
+    const compact = opts.compact === true;
+    valueGrid.forEach((rowVals, rIdx) => {
+        if (!compact && rIdx > 0) {
+            // Tier-3.1a: inter-row separator using `├─…─┼─…─┤` glyphs.
+            bodyLines.push(L + widths.map((w) => H.repeat(w + 2)).join(X) + R);
+        }
+        const cells = cols.map((c, i) => {
+            const raw = rowVals[i];
+            const padded = pad(raw, widths[i], c.align ?? 'left');
+            const colorKind = c.color ? c.color(rows[rIdx][c.key], rows[rIdx]) : undefined;
+            const painted = colorKind ? skin.applyColors(padded, colorKind) : padded;
+            return ' ' + painted + ' ';
+        });
+        bodyLines.push(V + cells.join(V) + V);
+    });
+    // Bottom border.
+    const bot = BL + widths.map((w) => H.repeat(w + 2)).join(B) + BR;
+    const allLines = [
+        top,
+        headerRow,
+        ...(showRule ? [rule] : []),
+        ...bodyLines,
+        bot,
+    ].map((l) => ind + l);
+    return allLines.join('\n') + '\n';
+}

package/dist/cli/v4/themeDetect.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/themeDetect.ts — Phase v4.1-tier3-essentials
+ *
+ * Multi-signal auto theme detection. The skin engine consults this
+ * once at boot when the configured skin is `auto`; otherwise the
+ * explicitly-named skin wins.
+ *
+ * Priority order (first non-undefined hit wins):
+ *
+ *   1. AIDEN_THEME=light|dark         — explicit override
+ *   2. AIDEN_THEME=auto / unset goes through 2..5
+ *   3. NO_COLOR set                   — forced monochrome
+ *   4. COLORFGBG="<fg>;<bg>"          — slot 7 or 15 = light, others = dark
+ *   5. TERM_PROGRAM allow-list        — Apple_Terminal default to light
+ *   6. Fallback: dark
+ *
+ * Returns 'light' / 'dark' / 'mono'. The skin engine maps:
+ *   'mono'  → monochrome skin (no colour)
+ *   'light' → light skin
+ *   'dark'  → default skin
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectTheme = detectTheme;
+exports.detectedToSkinName = detectedToSkinName;
+const LIGHT_DEFAULT_TERM_PROGRAMS = new Set([
+    // Apple Terminal default profile is on a light background.
+    'Apple_Terminal',
+]);
+/**
+ * Run the multi-signal detection. Pure function — env can be
+ * overridden for tests.
+ */
+function detectTheme(env = process.env) {
+    const explicit = (env.AIDEN_THEME ?? '').trim().toLowerCase();
+    if (explicit === 'light')
+        return 'light';
+    if (explicit === 'dark')
+        return 'dark';
+    if (explicit === 'mono' || explicit === 'monochrome')
+        return 'mono';
+    // NO_COLOR (https://no-color.org) — monochrome is its own theme,
+    // independent of light/dark, so it wins over the auto path.
+    if (env.NO_COLOR != null && env.NO_COLOR !== '')
+        return 'mono';
+    // COLORFGBG = "<fg>;<bg>" where slot 7 (light grey) or 15 (white)
+    // signals a light terminal background. Other slots = dark.
+    const colorfgbg = (env.COLORFGBG ?? '').trim();
+    if (colorfgbg) {
+        const parts = colorfgbg.split(';');
+        const lastField = parts[parts.length - 1] ?? '';
+        if (/^\d+$/.test(lastField)) {
+            const bg = Number(lastField);
+            if (bg === 7 || bg === 15)
+                return 'light';
+            if (bg >= 0 && bg < 16)
+                return 'dark';
+        }
+    }
+    // TERM_PROGRAM allow-list.
+    const termProgram = (env.TERM_PROGRAM ?? '').trim();
+    if (LIGHT_DEFAULT_TERM_PROGRAMS.has(termProgram))
+        return 'light';
+    // Fallback.
+    return 'dark';
+}
+/** Surfaced for skinEngine integration: maps DetectedTheme → skin name. */
+function detectedToSkinName(theme) {
+    switch (theme) {
+        case 'light': return 'light';
+        case 'mono': return 'monochrome';
+        case 'dark':
+        default: return 'default';
+    }
+}