lumira 1.4.1 → 1.6.0

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
 
@@ -34,6 +36,7 @@ Interactive wizard — preset, theme, icons — previewed live before write.
 - [Install](#install)
 - [Display modes](#display)
 - [Themes](#themes)
+- [Stats CLI](#stats-cli)
 - [Powerline](#powerline)
 - [Configuration](#configuration)
 - [Architecture](#architecture)
@@ -190,6 +193,28 @@ lumira themes preview --all --powerline      # the powerline grid (great for scr
 
 Adding a theme is a single new file plus a one-line registration. Every PR runs the **WCAG AA contrast guard** — if any powerline cell drops below 4.5:1 against the foreground, CI rejects it. See [CONTRIBUTING.md → Adding a theme](CONTRIBUTING.md#adding-a-theme) for the walkthrough.
 
+## Stats CLI
+
+`lumira stats` reads a Claude Code or Qwen Code transcript `.jsonl` and prints a one-shot analytics summary — session duration, total cost, token totals, cache hit rate, tool call frequency, and burn rate (`$/h`). Useful for post-session review, scripting, and CI dashboards.
+
+```bash
+# Just works — auto-discovers the newest transcript for the current cwd.
+lumira stats
+# Session: 2h 15m — $4.23 — 156k tokens — 87% cache
+# Tools: Bash×45 Read×32 Write×18 Edit×12 Agent×8
+# Burn: $1.88/h
+```
+
+**Auto-discovery:** with no flags, `lumira stats` derives the Claude Code project slug from `cwd` (`/home/me/proj` → `-home-me-proj`) and reads the newest `.jsonl` under `~/.claude/projects/<slug>/`. If the current directory has no matching project dir, it falls back to the globally most-recently-modified transcript under `~/.claude/projects/` and prints a notice to stderr ("reading most recent session from …") so JSON pipelines on stdout stay clean.
+
+**Flags:**
+
+- `--session-id <path-or-uuid>` — override auto-discovery. A path (anything containing `/` or ending in `.jsonl`) is used as-is. A bare uuid is resolved first under `~/.claude/projects/<cwd-slug>/<uuid>.jsonl`, then by scanning every project dir for that filename.
+- `--no-color` — strip ANSI escapes (also honored when the `NO_COLOR` env var is set, per [no-color.org](https://no-color.org)).
+- `--json` — emit the raw `SessionStats` object as pretty-printed JSON for `jq` / CI composability.
+
+**Qwen Code sessions** are parsed the same way, but cost and burn-rate lines are suppressed when the transcript lacks usage blocks (`hasCostData: false` in the JSON output) — no misleading `$0.00`.
+
 ## Powerline
 
 `style: "powerline"` (or `--powerline`) renders the statusline with colored segment backgrounds and glyph separators inspired by powerline-go / oh-my-posh. Available separator presets via `powerline.style` (or `--powerline-style=<name>`):
@@ -287,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.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+/**
+ * Read the JSON spec from stdin, run the command via execBg, persist the
+ * result. Never throws — every failure path returns silently.
+ */
+export declare function runCustomRefresh(stdinPayload: string): Promise<void>;
+/**
+ * CLI entrypoint used by the renderer. Reads stdin to EOF, then runs.
+ * Wrapped in a Promise so the caller can await before exiting.
+ */
+export declare function runCustomRefreshFromStdin(): Promise<void>;

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-refresh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-refresh.js","sourceRoot":"","sources":["../../src/commands/custom-refresh.ts"],"names":[],"mappings":"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"}

package/dist/commands/custom.d.ts

@@ -0,0 +1,15 @@
+type Result = {
+    output: string;
+    exitCode: number;
+};
+/**
+ * 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 declare function runCustomCommand(argv: string[]): Promise<Result>;
+export {};

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/commands/custom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom.js","sourceRoot":"","sources":["../../src/commands/custom.ts"],"names":[],"mappings":"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"}

package/dist/commands/stats.d.ts

@@ -0,0 +1,71 @@
+import { type SessionStats } from '../parsers/transcript-stats.js';
+export interface StatsArgs {
+    sessionId?: string;
+    noColor: boolean;
+    json: boolean;
+}
+/**
+ * Result of invoking the stats subcommand. Mirrors `ThemesCommandResult` so
+ * the dispatcher in `index.ts` can treat both subcommands uniformly.
+ */
+export interface StatsCommandResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/**
+ * Optional overrides for `runStatsCommand`. `cwd` and `homeDir` are injected
+ * here (rather than read from `process`) so tests can build isolated fake
+ * `~/.claude/projects/` trees in tmpdir without touching the real one.
+ */
+export interface StatsCommandOpts {
+    cwd?: string;
+    homeDir?: string;
+}
+/**
+ * Parse argv for `lumira stats [...flags]`. argv is the full process.argv;
+ * the 'stats' command starts at argv[2], flags from argv[3].
+ *
+ * Per https://no-color.org, the NO_COLOR env var (any non-empty value)
+ * disables color. An empty string is *not* a trigger — the variable being
+ * unset and the variable being empty must behave identically, otherwise
+ * shell environments that pre-export NO_COLOR='' would silently disable
+ * color everywhere.
+ *
+ * Unknown flags are ignored to stay forward-compatible: a future minor that
+ * adds a new flag shouldn't crash older binaries piped against new shells.
+ */
+export declare function parseStatsArgs(argv: string[]): StatsArgs;
+/**
+ * Render a SessionStats either as human-readable text or as pretty JSON.
+ *
+ * In `json` mode we emit `JSON.stringify(stats, null, 2)` — the 2-space
+ * indent makes the output diff-friendly without being absurdly verbose, and
+ * matches the convention used elsewhere in the tree for CLI JSON output.
+ *
+ * In human mode we always render the `Session:` and `Tools:` lines so the
+ * user gets a consistent skeleton regardless of which renderer produced the
+ * transcript. Cost and burn-rate lines are gated on `hasCostData` so Qwen
+ * (and other no-usage backends) never surface a misleading "$0.00".
+ */
+export declare function formatStatsOutput(stats: SessionStats, opts: {
+    noColor: boolean;
+    json: boolean;
+}): string;
+/**
+ * Execute `lumira stats [...]`. Resolution order for the transcript:
+ *   1. `--session-id <path>` (contains `/` or ends in `.jsonl`) — used as-is.
+ *   2. `--session-id <uuid>` — looked up under cwd-slug, then globally.
+ *   3. No flag — auto-discover newest in cwd-slug dir, then globally.
+ *
+ * The parser's own allow-list check (LUMIRA_ALLOWED_ROOTS) remains the
+ * security boundary — anything we hand it must pass `isUnderAllowedRoot`.
+ * Discovered paths live under `~/.claude/projects/` (covered by the home
+ * root) or under tmpdir in tests (also covered).
+ *
+ * `cols` is accepted for parity with `runThemesCommand` but the human
+ * renderer here doesn't wrap or align to terminal width — keep it in the
+ * signature so a future widened renderer (sparklines, multi-column tool
+ * frequency) can opt in without breaking the dispatcher contract.
+ */
+export declare function runStatsCommand(argv: string[], _cols?: number, opts?: StatsCommandOpts): Promise<StatsCommandResult>;