lumira 1.5.0 → 1.6.1

package/README.md

@@ -24,7 +24,9 @@ Interactive wizard — preset, theme, icons — previewed live before write.
 ![Claude Code](https://img.shields.io/badge/Claude_Code-compatible-2d3748?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMjggMTI4IiB3aWR0aD0iMTI4IiBoZWlnaHQ9IjEyOCI+PHBhdGggZD0iTTY0IDEyOEMzNS44IDEyOCAxMyAxMDUuMiAxMyA3N0MxMyA0OC44IDM1LjggMjYgNjQgMjZjMjguMiAwIDUxIDIyLjggNTEgNTFzLTIyLjggNTEtNTEgNTF6IiBmaWxsPSIjMjQyNTJGIi8+PC9zdmc+)
 ![Qwen Code](https://img.shields.io/badge/Qwen_Code-compatible-6156FF)
 
-> 1,700+ downloads in the first month — [share your setup](https://github.com/cativo23/lumira/discussions) in Discussions.
+> 3,400+ monthly downloads, zero marketing. Try it for one session — `npx lumira install`.
+
+> **What's new in v1.5:** the [`lumira stats` CLI](#stats-cli) prints post-session analytics (cost, tokens, cache hit, tool frequency, burn rate). Combined with the `API N%` latency widget (v1.4.0), 7-day quota projection warning (v1.3.0), and auto-compact proximity glyph ⚠ (v1.4.1), recent releases add several diagnostic signals to the session.
 
 ## Table of contents
 
@@ -310,6 +312,68 @@ lumira --icons=nerd|emoji|none      # Override icon set
 lumira --preset=full|balanced|minimal
 ```
 
+## Custom Commands
+
+User-defined shell commands rendered as statusline segments on any of the 4 lines. Disabled by default.
+
+### Enable
+
+```bash
+lumira custom enable
+```
+
+### Configure
+
+Add a `customCommands` block to `~/.config/lumira/config.json`:
+
+```json
+{
+  "customCommands": {
+    "enabled": true,
+    "commands": [
+      {
+        "id": "git-status",
+        "command": ["git", "status", "--short"],
+        "label": "",
+        "line": 1,
+        "refreshMs": 5000,
+        "onError": "hide"
+      }
+    ]
+  }
+}
+```
+
+**Key fields:**
+
+| Field | Description |
+|---|---|
+| `id` | Unique identifier for the command |
+| `command` | Argv array — no shell expansion, pipes, or redirects |
+| `line` | Statusline line to render on (`1`–`4`) |
+| `refreshMs` | Refresh interval in milliseconds (default: `5000`) |
+| `label` | Optional prefix shown before the command output |
+| `color` | Optional color override for the segment |
+| `onError` | What to show on non-zero exit: `hide` (default), `placeholder`, `output`, or `stale` |
+| `onTimeout` | What to show on timeout: same options as `onError`, defaults to `hide` |
+| `timeoutMs` | Max execution time in ms (clamped to 2000) |
+| `maxBytes` | Max stdout bytes captured (clamped to 4096) |
+| `ansi` | Set `true` to pass through ANSI escape sequences from the command |
+
+`command` must be an argv array (`["git", "status", "--short"]`). Shell strings with pipes or redirects are not supported — wrap them in a script if needed.
+
+Output is cached with a TTL and refreshed in the background, so the hot render path never blocks on subprocess execution.
+
+### CLI subcommands
+
+```bash
+lumira custom list          # list configured commands and their status
+lumira custom enable        # enable the custom commands feature
+lumira custom disable       # disable the custom commands feature
+lumira custom test <id>     # run a command immediately and print its output
+lumira custom logs          # show recent execution logs
+```
+
 ## Architecture
 
 ```text

package/dist/commands/custom-refresh.js

@@ -0,0 +1,124 @@
+/**
+ * Internal helper for the Custom Command widget (#143). Runs ONE custom
+ * command and writes the result into the cache file. Intended to be
+ * launched by the renderer as a detached child process so the renderer
+ * itself can exit immediately without waiting on the spawned command
+ * (B1: the original "fire and forget" via void async-IIFE still kept
+ * the Node event loop refed because data listeners hold stdin/stdout
+ * streams open until child exit + cache write).
+ *
+ * Wire protocol: a single JSON object on stdin describing the spawn
+ * spec, cache path, and (optional) stdin envelope to forward to the
+ * user command:
+ *
+ *   {
+ *     "id": "k8s-context",
+ *     "command": ["kubectl", "config", "current-context"],
+ *     "timeoutMs": 1500,
+ *     "maxBytes": 256,
+ *     "env": { ... },           // optional
+ *     "cwd": "/abs/path",       // optional
+ *     "onError": "hide",        // 'hide' | 'placeholder' | 'output' | 'stale'
+ *     "cachePath": "/abs/path/to/custom-commands.json",
+ *     "stdin": "{}"             // optional
+ *   }
+ *
+ * Errors are swallowed — this process must NEVER print to stdout or
+ * crash visibly. The renderer doesn't read this process's exit code.
+ */
+import { execBg } from '../utils/exec-bg.js';
+import { isAbsolute } from 'node:path';
+import { readCacheFile, writeCacheFile } from '../utils/custom-cache.js';
+function isValidSpec(raw) {
+    if (!raw || typeof raw !== 'object')
+        return false;
+    const s = raw;
+    if (typeof s.id !== 'string' || s.id.length === 0)
+        return false;
+    if (!Array.isArray(s.command) || s.command.length === 0)
+        return false;
+    if (!s.command.every((x) => typeof x === 'string' && x.length > 0))
+        return false;
+    if (typeof s.timeoutMs !== 'number' || !Number.isFinite(s.timeoutMs) || s.timeoutMs > 2000)
+        return false;
+    if (typeof s.maxBytes !== 'number' || !Number.isFinite(s.maxBytes) || s.maxBytes > 4096)
+        return false;
+    if (typeof s.onError !== 'string')
+        return false;
+    if (typeof s.cachePath !== 'string' || s.cachePath.length === 0 || !isAbsolute(s.cachePath))
+        return false;
+    return true;
+}
+/**
+ * Read the JSON spec from stdin, run the command via execBg, persist the
+ * result. Never throws — every failure path returns silently.
+ */
+export async function runCustomRefresh(stdinPayload) {
+    let spec;
+    try {
+        const parsed = JSON.parse(stdinPayload);
+        if (!isValidSpec(parsed))
+            return;
+        spec = parsed;
+    }
+    catch {
+        return;
+    }
+    try {
+        const result = await execBg({
+            command: spec.command,
+            timeoutMs: spec.timeoutMs,
+            maxBytes: spec.maxBytes,
+            env: spec.env,
+            cwd: spec.cwd,
+            stdin: spec.stdin,
+        });
+        const now = Date.now();
+        let entry;
+        switch (result.kind) {
+            case 'ok':
+                entry = { text: result.stdout, capturedAt: now, state: 'ok' };
+                break;
+            case 'timeout':
+                entry = { text: result.stdout, capturedAt: now, state: 'timeout' };
+                break;
+            case 'nonzero': {
+                // For onError:'output' the renderer shows entry.text directly, so
+                // store stdout (partial output before the command failed). For all
+                // other strategies the text is not displayed — store stdout anyway
+                // so the entry is useful if the strategy is later changed.
+                entry = { text: result.stdout, capturedAt: now, state: 'nonzero' };
+                break;
+            }
+            case 'spawn-error':
+                entry = { text: '', capturedAt: now, state: 'nonzero' };
+                break;
+        }
+        const current = readCacheFile(spec.cachePath);
+        current[spec.id] = entry;
+        writeCacheFile(spec.cachePath, current);
+    }
+    catch {
+        /* swallow — helper must never crash visibly */
+    }
+}
+/**
+ * CLI entrypoint used by the renderer. Reads stdin to EOF, then runs.
+ * Wrapped in a Promise so the caller can await before exiting.
+ */
+export async function runCustomRefreshFromStdin() {
+    const chunks = [];
+    try {
+        await new Promise((resolve) => {
+            process.stdin.on('data', (chunk) => chunks.push(chunk));
+            process.stdin.on('end', () => resolve());
+            process.stdin.on('error', () => resolve());
+        });
+    }
+    catch {
+        return;
+    }
+    const payload = Buffer.concat(chunks).toString('utf8');
+    await runCustomRefresh(payload);
+}
+//# sourceMappingURL=custom-refresh.js.map

package/dist/commands/custom.js

@@ -0,0 +1,280 @@
+/**
+ * `lumira custom` subcommand (issue #143 phase 4).
+ *
+ * Provides a CLI interface for managing the custom commands feature:
+ *
+ *   lumira custom list             List configured commands from config file
+ *   lumira custom enable           Set enabled:true in config file
+ *   lumira custom disable          Set enabled:false in config file
+ *   lumira custom test <id>        Run a command once, print output + timing
+ *   lumira custom logs             Show cached outputs from the cache file
+ *
+ * Design constraints:
+ * - No runtime deps beyond Node built-ins.
+ * - All FS reads in try/catch — graceful errors, exit 1 on failure.
+ * - Color: process.stdout.isTTY ? 'named' : 'none'.
+ * - Return type: Promise<{ output: string; exitCode: number }> so the
+ *   dispatcher can set process.exitCode.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { execBg } from '../utils/exec-bg.js';
+import { createColors } from '../render/colors.js';
+import { loadConfig } from '../config.js';
+import { readCacheFile } from '../utils/custom-cache.js';
+// ── constants ──────────────────────────────────────────────────────────────
+const CONFIG_FILE = 'config.json';
+const CONFIG_DIR = join('.config', 'lumira');
+const CACHE_FILE = 'custom-commands.json';
+const CACHE_DIR = join('.cache', 'lumira');
+// ── helpers ────────────────────────────────────────────────────────────────
+function configPath() {
+    return join(homedir(), CONFIG_DIR, CONFIG_FILE);
+}
+function cachePath() {
+    return join(homedir(), CACHE_DIR, CACHE_FILE);
+}
+function ok(output) {
+    return { output, exitCode: 0 };
+}
+function fail(output) {
+    return { output, exitCode: 1 };
+}
+/**
+ * Read the raw config JSON from disk. Returns an empty object `{}` if the
+ * file doesn't exist, throws on malformed JSON so the caller can surface a
+ * useful error.
+ */
+function readConfigRaw() {
+    const p = configPath();
+    if (!existsSync(p))
+        return {};
+    const raw = readFileSync(p, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return {};
+    return parsed;
+}
+/**
+ * Write (or create) the config file. Creates the parent directory if needed.
+ * The value is always pretty-printed with 2-space indents.
+ */
+function writeConfigRaw(value) {
+    const p = configPath();
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(value, null, 2), { encoding: 'utf8', mode: 0o600 });
+}
+/**
+ * Extract the `customCommands` block from the raw config. Returns a minimal
+ * default when the block is missing or malformed.
+ */
+function readCustomCommandsBlock(raw) {
+    const cc = raw.customCommands;
+    if (!cc || typeof cc !== 'object' || Array.isArray(cc)) {
+        return { enabled: false, commands: [] };
+    }
+    const obj = cc;
+    const enabled = typeof obj.enabled === 'boolean' ? obj.enabled : false;
+    const commands = Array.isArray(obj.commands) ? obj.commands : [];
+    return { enabled, commands };
+}
+// ── color ──────────────────────────────────────────────────────────────────
+/**
+ * Only use color when stdout is a real TTY and NO_COLOR is not set.
+ * In pipe/test contexts or when NO_COLOR is in env, produces no escape
+ * sequences, keeping output clean for programmatic use.
+ */
+function makeColors() {
+    const noColor = 'NO_COLOR' in process.env || process.env.TERM === 'dumb';
+    if (noColor || !process.stdout.isTTY)
+        return null;
+    return createColors('named');
+}
+// ── subcommands ────────────────────────────────────────────────────────────
+async function cmdEnable() {
+    try {
+        const raw = readConfigRaw();
+        const cc = readCustomCommandsBlock(raw);
+        const updated = {
+            ...raw,
+            customCommands: {
+                ...cc,
+                enabled: true,
+            },
+        };
+        writeConfigRaw(updated);
+        return ok(`Custom commands enabled.\nConfig written to: ${configPath()}\n`);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return fail(`lumira custom enable: ${msg}\n`);
+    }
+}
+async function cmdDisable() {
+    try {
+        const raw = readConfigRaw();
+        const cc = readCustomCommandsBlock(raw);
+        const updated = {
+            ...raw,
+            customCommands: {
+                ...cc,
+                enabled: false,
+            },
+        };
+        writeConfigRaw(updated);
+        return ok(`Custom commands disabled.\nConfig written to: ${configPath()}\n`);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return fail(`lumira custom disable: ${msg}\n`);
+    }
+}
+async function cmdList() {
+    const c = makeColors();
+    let enabled = false;
+    let commands = [];
+    try {
+        const cfg = loadConfig();
+        enabled = cfg.customCommands.enabled;
+        commands = cfg.customCommands.commands;
+    }
+    catch {
+        // config unreadable — fall through with empty defaults
+    }
+    const statusLine = enabled
+        ? `Custom commands: ${c ? c.green('enabled') : 'enabled'}\n`
+        : `Custom commands: ${c ? c.yellow('disabled') : 'disabled'}\n`;
+    if (commands.length === 0) {
+        return ok(statusLine
+            + '\nNo custom commands configured.\n'
+            + `Add commands to ${configPath()} under customCommands.commands.\n`);
+    }
+    // Table: id | line | refresh | cmd
+    const header = `${'id'.padEnd(20)} ${'line'.padEnd(6)} ${'refresh'.padEnd(10)} cmd`;
+    const sep = '-'.repeat(header.length);
+    const rows = commands.map(cmd => {
+        const id = cmd.id.padEnd(20);
+        const line = String(cmd.line).padEnd(6);
+        const refresh = `${cmd.refreshMs}ms`.padEnd(10);
+        const cmdStr = cmd.command.join(' ');
+        return `${id} ${line} ${refresh} ${cmdStr}`;
+    });
+    const table = [header, sep, ...rows].join('\n');
+    return ok(`${statusLine}\n${table}\n`);
+}
+async function cmdTest(id) {
+    if (!id) {
+        return fail('lumira custom test: missing command id.\n\n'
+            + 'Usage: lumira custom test <id>\n'
+            + "Use 'lumira custom list' to see configured command ids.\n");
+    }
+    let commands;
+    try {
+        commands = loadConfig().customCommands.commands;
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return fail(`lumira custom test: could not read config: ${msg}\n`);
+    }
+    const cmd = commands.find(c => c.id === id);
+    if (!cmd) {
+        const knownIds = commands.map(c => c.id).join(', ');
+        return fail(`lumira custom test: command id "${id}" not found.\n`
+            + (knownIds ? `Known ids: ${knownIds}\n` : 'No commands configured.\n'));
+    }
+    const result = await execBg({
+        command: cmd.command,
+        timeoutMs: cmd.timeoutMs,
+        maxBytes: cmd.maxBytes,
+    });
+    const lines = [
+        `Command: ${cmd.command.join(' ')}`,
+        `Duration: ${result.durationMs}ms`,
+    ];
+    if (result.kind === 'ok') {
+        lines.push(`Exit: 0 (ok)`);
+        lines.push(`Output:\n${result.stdout || '(empty)'}`);
+    }
+    else if (result.kind === 'nonzero') {
+        lines.push(`Exit: ${result.exitCode} (nonzero)`);
+        if (result.stdout)
+            lines.push(`Stdout:\n${result.stdout}`);
+        if (result.stderr)
+            lines.push(`Stderr:\n${result.stderr}`);
+    }
+    else if (result.kind === 'timeout') {
+        lines.push(`Exit: timeout (killed after ${cmd.timeoutMs}ms)`);
+        if (result.stdout)
+            lines.push(`Stdout (partial):\n${result.stdout}`);
+    }
+    else {
+        // spawn-error
+        lines.push(`Exit: spawn-error — ${result.message}`);
+    }
+    return ok(lines.join('\n') + '\n');
+}
+async function cmdLogs() {
+    const p = cachePath();
+    const cacheData = readCacheFile(p);
+    const entries = Object.entries(cacheData);
+    if (entries.length === 0) {
+        return ok(`No cache file found at ${p}.\n`
+            + "Run lumira once with custom commands enabled to populate the cache.\n");
+    }
+    const lines = [`Cache: ${p}`, ''];
+    for (const [id, entry] of entries) {
+        const { text, capturedAt, state } = entry;
+        const dateStr = capturedAt > 0
+            ? new Date(capturedAt).toLocaleString()
+            : 'unknown';
+        const truncated = text.length > 100 ? text.slice(0, 100) + '…' : text;
+        lines.push(`id: ${id}`);
+        lines.push(`  state:      ${state}`);
+        lines.push(`  capturedAt: ${dateStr}`);
+        lines.push(`  text:       ${truncated || '(empty)'}`);
+        lines.push('');
+    }
+    return ok(lines.join('\n'));
+}
+function helpText() {
+    return [
+        'Usage: lumira custom <subcommand>',
+        '',
+        'Subcommands:',
+        '  list               List configured custom commands',
+        '  enable             Enable custom commands in config',
+        '  disable            Disable custom commands in config',
+        '  test <id>          Run a command once and print output + timing',
+        '  logs               Show cached command outputs',
+        '',
+    ].join('\n');
+}
+// ── entry point ────────────────────────────────────────────────────────────
+/**
+ * Execute `lumira custom [subcommand] [...args]`.
+ *
+ * argv is the full process.argv; 'custom' starts at argv[2], the subcommand
+ * at argv[3], additional arguments from argv[4] onward.
+ *
+ * Returns `{ output, exitCode }` — the dispatcher writes output to stdout and
+ * sets process.exitCode from the returned value.
+ */
+export async function runCustomCommand(argv) {
+    const sub = argv[3];
+    switch (sub) {
+        case 'enable':
+            return cmdEnable();
+        case 'disable':
+            return cmdDisable();
+        case 'list':
+            return cmdList();
+        case 'test':
+            return cmdTest(argv[4]);
+        case 'logs':
+            return cmdLogs();
+        default:
+            return fail(helpText());
+    }
+}
+//# sourceMappingURL=custom.js.map

package/dist/config.js

@@ -1,7 +1,42 @@
 import { readFileSync, existsSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { join, dirname, isAbsolute } from 'node:path';
 import { homedir } from 'node:os';
-import { DEFAULT_CONFIG, DEFAULT_DISPLAY, DEFAULT_CONTEXT_WARNING_THRESHOLD, DEFAULT_CONTEXT_CRITICAL_THRESHOLD, POWERLINE_STYLE_NAMES } from './types.js';
+import { DEFAULT_CONFIG, DEFAULT_DISPLAY, DEFAULT_CONTEXT_WARNING_THRESHOLD, DEFAULT_CONTEXT_CRITICAL_THRESHOLD, POWERLINE_STYLE_NAMES, CUSTOM_COMMAND_MAX_TIMEOUT_MS, CUSTOM_COMMAND_MAX_BYTES, CUSTOM_COMMAND_MAX_ENV_ENTRIES, CUSTOM_COMMAND_MIN_REFRESH_MS, CUSTOM_COMMAND_MAX_REFRESH_MS, CUSTOM_COMMAND_VALID_LINES, CUSTOM_COMMAND_ERROR_BEHAVIORS, CUSTOM_COMMAND_COLORS, } from './types.js';
+/**
+ * Ids we refuse to accept on user-supplied custom commands. Object.prototype
+ * lookalikes prevent prototype-pollution-style attacks via the cache map
+ * (cache entries are keyed by id; if an attacker can name an entry
+ * `__proto__` or `constructor`, lookups against arbitrary objects later in
+ * the pipeline could become surprising).
+ */
+const RESERVED_ID_NAMES = new Set([
+    '__proto__',
+    'prototype',
+    'constructor',
+    'hasOwnProperty',
+    'toString',
+    'valueOf',
+    'isPrototypeOf',
+    'propertyIsEnumerable',
+    'toLocaleString',
+]);
+/**
+ * Reject ids containing path separators or ASCII control characters. Slash
+ * and backslash would break cache-map lookups by id (entries are keyed under
+ * a single object; nesting via paths is not supported). Control chars in id
+ * could corrupt log output / status lines downstream.
+ */
+// eslint-disable-next-line no-control-regex
+const DANGEROUS_ID_CHARS = /[\x00-\x1f/\\]/;
+function isValidCustomCommandId(id) {
+    if (id.length === 0 || id.length > 64)
+        return false;
+    if (RESERVED_ID_NAMES.has(id))
+        return false;
+    if (DANGEROUS_ID_CHARS.test(id))
+        return false;
+    return true;
+}
 // Module-level flag: fires the qwen→minimal deprecation warning once per
 // Node process. Process-scoped by design — tests must run in forked workers
 // (see vitest.config.ts `pool: 'forks'`). Issue #20.
@@ -10,6 +45,109 @@ let thresholdWarningShown = false;
 /** Test-only — resets the process-scoped qwenWarningShown flag. Do not call in production. */
 export function _resetMigrationFlags() { qwenWarningShown = false; thresholdWarningShown = false; }
 const clampPct = (n) => Math.max(0, Math.min(100, n));
+const clampInt = (n, min, max) => {
+    const i = Math.trunc(n);
+    return Math.max(min, Math.min(max, i));
+};
+/**
+ * Parse and validate the `customCommands` config block (issue #143).
+ * Drops invalid commands silently, clamps numerics to documented bounds,
+ * defaults missing optional fields, and preserves first-occurrence on
+ * duplicate `id`. Always returns a fresh object (no shared references).
+ */
+function parseCustomCommands(raw) {
+    const empty = { enabled: false, commands: [] };
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return empty;
+    const obj = raw;
+    const enabled = typeof obj.enabled === 'boolean' ? obj.enabled : false;
+    if (!Array.isArray(obj.commands))
+        return { enabled, commands: [] };
+    const seenIds = new Set();
+    const commands = [];
+    for (const entry of obj.commands) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+            continue;
+        const e = entry;
+        // id — non-empty string, unique, no path separators / control chars /
+        // reserved Object.prototype names. Caps length at 64 to prevent absurd
+        // ids from blowing up log lines or cache files.
+        if (typeof e.id !== 'string' || !isValidCustomCommandId(e.id))
+            continue;
+        if (seenIds.has(e.id))
+            continue;
+        // command — non-empty array of non-empty strings (no shell-string form)
+        if (!Array.isArray(e.command) || e.command.length === 0)
+            continue;
+        if (!e.command.every((s) => typeof s === 'string' && s.length > 0))
+            continue;
+        // line — must be one of {1,2,3,4}
+        if (typeof e.line !== 'number' || !CUSTOM_COMMAND_VALID_LINES.includes(e.line))
+            continue;
+        // From here on the entry is valid; default optional fields.
+        const refreshMs = typeof e.refreshMs === 'number' && Number.isFinite(e.refreshMs)
+            ? clampInt(e.refreshMs, CUSTOM_COMMAND_MIN_REFRESH_MS, CUSTOM_COMMAND_MAX_REFRESH_MS)
+            : 5000;
+        const timeoutMs = typeof e.timeoutMs === 'number' && Number.isFinite(e.timeoutMs)
+            ? clampInt(e.timeoutMs, 100, CUSTOM_COMMAND_MAX_TIMEOUT_MS)
+            : 1500;
+        const maxBytes = typeof e.maxBytes === 'number' && Number.isFinite(e.maxBytes)
+            ? clampInt(e.maxBytes, 16, CUSTOM_COMMAND_MAX_BYTES)
+            : 256;
+        // Cast AFTER the membership guard, not before — casting unknown→typed
+        // up front inverts the type-narrowing the guard exists to provide.
+        const rawOnError = e.onError;
+        const onError = typeof rawOnError === 'string' && CUSTOM_COMMAND_ERROR_BEHAVIORS.includes(rawOnError)
+            ? rawOnError
+            : 'hide';
+        const rawOnTimeout = e.onTimeout;
+        const onTimeout = typeof rawOnTimeout === 'string' && CUSTOM_COMMAND_ERROR_BEHAVIORS.includes(rawOnTimeout)
+            ? rawOnTimeout
+            : 'stale';
+        const ansi = typeof e.ansi === 'boolean' ? e.ansi : false;
+        const cmd = {
+            id: e.id,
+            command: e.command.slice(),
+            line: e.line,
+            refreshMs,
+            timeoutMs,
+            maxBytes,
+            onError,
+            onTimeout,
+            ansi,
+        };
+        if (typeof e.label === 'string')
+            cmd.label = e.label;
+        // cwd — must be an absolute path. Relative paths like '../../../etc'
+        // would silently escape the renderer's cwd; drop them to fall back to
+        // process.cwd() instead of accepting hostile relative input.
+        if (typeof e.cwd === 'string' && isAbsolute(e.cwd))
+            cmd.cwd = e.cwd;
+        if (typeof e.color === 'string' && CUSTOM_COMMAND_COLORS.includes(e.color)) {
+            cmd.color = e.color;
+        }
+        // env — record of string→string, truncated to CUSTOM_COMMAND_MAX_ENV_ENTRIES
+        if (e.env && typeof e.env === 'object' && !Array.isArray(e.env)) {
+            const envOut = {};
+            let count = 0;
+            for (const [k, v] of Object.entries(e.env)) {
+                if (count >= CUSTOM_COMMAND_MAX_ENV_ENTRIES)
+                    break;
+                if (typeof k !== 'string' || k.length === 0)
+                    continue;
+                if (typeof v !== 'string')
+                    continue;
+                envOut[k] = v;
+                count++;
+            }
+            if (count > 0)
+                cmd.env = envOut;
+        }
+        seenIds.add(cmd.id);
+        commands.push(cmd);
+    }
+    return { enabled, commands };
+}
 /**
  * Validate context-bar threshold pair. Clamps each to [0, 100]. If `warning`
  * is not strictly less than `critical` after clamping, emits a one-shot warn
@@ -37,15 +175,15 @@ function resolveThresholds(rawWarn, rawCrit) {
 export function loadConfig(configDir = join(homedir(), '.config', 'lumira')) {
     const p = join(configDir, 'config.json');
     if (!existsSync(p))
-        return { ...DEFAULT_CONFIG, display: { ...DEFAULT_DISPLAY } };
+        return { ...DEFAULT_CONFIG, display: { ...DEFAULT_DISPLAY }, customCommands: { enabled: false, commands: [] } };
     try {
         const raw = JSON.parse(readFileSync(p, 'utf8'));
         if (!raw || typeof raw !== 'object' || Array.isArray(raw))
-            return { ...DEFAULT_CONFIG, display: { ...DEFAULT_DISPLAY } };
+            return { ...DEFAULT_CONFIG, display: { ...DEFAULT_DISPLAY }, customCommands: { enabled: false, commands: [] } };
         return mergeConfig(raw);
     }
     catch {
-        return { ...DEFAULT_CONFIG, display: { ...DEFAULT_DISPLAY } };
+        return { ...DEFAULT_CONFIG, display: { ...DEFAULT_DISPLAY }, customCommands: { enabled: false, commands: [] } };
     }
 }
 function mergeConfig(rawIn) {
@@ -64,7 +202,13 @@ function mergeConfig(rawIn) {
         if (['auto', 'named', '256', 'truecolor'].includes(m))
             colors.mode = m;
     }
-    const result = { layout, gsd: typeof raw.gsd === 'boolean' ? raw.gsd : DEFAULT_CONFIG.gsd, display: { ...DEFAULT_DISPLAY }, colors };
+    const result = {
+        layout,
+        gsd: typeof raw.gsd === 'boolean' ? raw.gsd : DEFAULT_CONFIG.gsd,
+        display: { ...DEFAULT_DISPLAY },
+        colors,
+        customCommands: parseCustomCommands(raw.customCommands),
+    };
     // Apply preset FIRST (sets layout + display defaults)
     const validPresets = ['full', 'balanced', 'minimal'];
     if (validPresets.includes(raw.preset))