@askalf/dario 3.38.5 → 4.0.0

package/README.md

@@ -23,13 +23,35 @@ You're already paying $20, $100, or $200 a month for Claude. Then Cursor wants a
 ```bash
 npm install -g @askalf/dario
 dario login          # uses your existing Claude Code credentials
-dario proxy
+dario proxy          # start the server (separate terminal or background)
 export ANTHROPIC_BASE_URL=http://localhost:3456
 export ANTHROPIC_API_KEY=dario
 ```
 
 That's the whole setup. Every tool that honors those env vars now runs on your subscription.
 
+**New in v4:** type `dario` (no args) in another terminal to open the interactive TUI — live request stream, per-model burn-rate, rate-limit utilization, and a config editor that writes to `~/.dario/config.json`. Migrating from v3? See [MIGRATION.md](MIGRATION.md).
+
+```
+┌─ dario v4.0.0 ───────────────[ q quit · ? help · Tab next panel ]┐
+│  Status   Config   ▎Analytics▎   Hits   Accounts   Backends      │
+├──────────────────────────────────────────────────────────────────┤
+│  Analytics — last 60 min                                         │
+│                                                                  │
+│  Requests:        247  (4.1/min)                                 │
+│  Tokens in:    142,830                                           │
+│  Tokens out:    38,200                                           │
+│                                                                  │
+│  Per-model:                                                      │
+│   opus-4-7    ████████████████████░  72%                         │
+│   sonnet-4-6  █████░░░░░░░░░░░░░░░░  22%                         │
+│                                                                  │
+│  Rate-limit:                                                     │
+│   5h ████░░░░░░░░░░░░░░░░░░░░░░  18%                             │
+│   7d ██░░░░░░░░░░░░░░░░░░░░░░░░   8%                             │
+└──────────────────────────────────────────────────────────────────┘
+```
+
 ---
 
 ## The money

package/dist/analytics.d.ts

@@ -2,9 +2,21 @@
  * Token analytics — per-request billing tracking, utilization trends,
  * window exhaustion predictions, cost estimation.
  *
- * In-memory rolling window; exposed via the /analytics endpoint when
- * pool mode is active.
+ * In-memory rolling window. Exposed via two endpoints on the running
+ * proxy:
+ *
+ *   - GET /analytics         — rolling summary (`AnalyticsSummary`)
+ *   - GET /analytics/stream  — Server-Sent Events of new `RequestRecord`s
+ *                              as they're appended. The v4 TUI's Hits
+ *                              tab subscribes here for the live request
+ *                              feed; non-TUI clients can `curl -N` it.
+ *
+ * Pre-v4 the class only emitted data when pool mode was active; v4
+ * promotes analytics to always-on so single-account users get the same
+ * UX. The EventEmitter mixin below makes the streaming endpoint cheap —
+ * each subscriber listens for `'record'` and writes one SSE frame.
  */
+import { EventEmitter } from 'node:events';
 export interface RequestRecord {
     timestamp: number;
     account: string;
@@ -43,11 +55,28 @@ export type BillingBucket = 'subscription' | 'subscription_fallback' | 'extra_us
  * billing bucket. Pure function; no state; safe to call from any context.
  */
 export declare function billingBucketFromClaim(claim: string | null | undefined): BillingBucket;
-export declare class Analytics {
+export declare class Analytics extends EventEmitter {
     private records;
     private maxRecords;
     constructor(maxRecords?: number);
+    /**
+     * Append a request record to the rolling window and fan it out to
+     * any `'record'` listeners (the SSE stream subscribers). Emit happens
+     * AFTER the push so a subscriber that re-queries `recent()` from
+     * inside its handler sees the new record.
+     *
+     * The emit is wrapped in try/catch so a misbehaving subscriber can't
+     * crash the proxy hot-path; errors land on stderr (visible in
+     * --verbose) but don't propagate.
+     */
     record(r: RequestRecord): void;
+    /**
+     * Return the most recent `n` records (newest last). Used by the SSE
+     * endpoint to send a backlog snapshot before the live tail starts,
+     * so a freshly-attached TUI sees the recent state instead of an
+     * empty list.
+     */
+    recent(n?: number): RequestRecord[];
     /** Parse usage from a non-streaming Anthropic response body. */
     static parseUsage(body: Record<string, unknown>): {
         inputTokens: number;

package/dist/analytics.js

@@ -2,9 +2,21 @@
  * Token analytics — per-request billing tracking, utilization trends,
  * window exhaustion predictions, cost estimation.
  *
- * In-memory rolling window; exposed via the /analytics endpoint when
- * pool mode is active.
+ * In-memory rolling window. Exposed via two endpoints on the running
+ * proxy:
+ *
+ *   - GET /analytics         — rolling summary (`AnalyticsSummary`)
+ *   - GET /analytics/stream  — Server-Sent Events of new `RequestRecord`s
+ *                              as they're appended. The v4 TUI's Hits
+ *                              tab subscribes here for the live request
+ *                              feed; non-TUI clients can `curl -N` it.
+ *
+ * Pre-v4 the class only emitted data when pool mode was active; v4
+ * promotes analytics to always-on so single-account users get the same
+ * UX. The EventEmitter mixin below makes the streaming endpoint cheap —
+ * each subscriber listens for `'record'` and writes one SSE frame.
  */
+import { EventEmitter } from 'node:events';
 /**
  * Map the raw `representative-claim` header value to a human-friendly
  * billing bucket. Pure function; no state; safe to call from any context.
@@ -39,17 +51,50 @@ function estimateCost(record) {
         (record.cacheReadTokens * p.cacheRead) +
         (record.cacheCreateTokens * p.cacheCreate)) / 1_000_000;
 }
-export class Analytics {
+export class Analytics extends EventEmitter {
     records = [];
     maxRecords;
     constructor(maxRecords = 10_000) {
+        super();
+        // High default — the /analytics/stream SSE endpoint creates one
+        // listener per active subscriber, and Node warns at 10 by default.
+        // 100 is generous for the TUI use case (one process, ~5 tabs)
+        // without hiding genuine leaks.
+        this.setMaxListeners(100);
         this.maxRecords = maxRecords;
     }
+    /**
+     * Append a request record to the rolling window and fan it out to
+     * any `'record'` listeners (the SSE stream subscribers). Emit happens
+     * AFTER the push so a subscriber that re-queries `recent()` from
+     * inside its handler sees the new record.
+     *
+     * The emit is wrapped in try/catch so a misbehaving subscriber can't
+     * crash the proxy hot-path; errors land on stderr (visible in
+     * --verbose) but don't propagate.
+     */
     record(r) {
         this.records.push(r);
         if (this.records.length > this.maxRecords) {
             this.records = this.records.slice(-this.maxRecords);
         }
+        try {
+            this.emit('record', r);
+        }
+        catch (err) {
+            // Subscriber threw — log + swallow. Not catastrophic; the record
+            // itself is already in the rolling window.
+            console.error('[dario] analytics subscriber threw:', err.message);
+        }
+    }
+    /**
+     * Return the most recent `n` records (newest last). Used by the SSE
+     * endpoint to send a backlog snapshot before the live tail starts,
+     * so a freshly-attached TUI sees the recent state instead of an
+     * empty list.
+     */
+    recent(n = 100) {
+        return this.records.slice(-n);
     }
     /** Parse usage from a non-streaming Anthropic response body. */
     static parseUsage(body) {

package/dist/cc-template.js

@@ -833,16 +833,24 @@ const TOOL_MAP = {
     //   • hybrid mode → dropped, so the model doesn't see a broken tool;
     //   • --preserve-tools → client's real schema flows through untouched
     //     (recommended for agents that depend on ask-user flows).
-    todo_read: {
-        ccTool: 'TodoWrite',
-        translateArgs: () => ({ todos: [] }),
-        translateBack: () => ({}),
-    },
-    todo_write: {
-        ccTool: 'TodoWrite',
-        translateArgs: (a) => ({ todos: a.todos || [] }),
-        translateBack: (a) => ({ todos: a.todos ?? [] }),
-    },
+    // Intentionally unmapped (CC v2.1.142): Anthropic removed TodoWrite /
+    // TodoRead from the CC tool catalog in favor of the Task* family
+    // (TaskCreate / TaskGet / TaskList / TaskOutput / TaskStop / TaskUpdate).
+    // The previous `todo_read`/`todo_write` → `TodoWrite` mappings now point
+    // at a destination tool that no longer exists in the bundled or live
+    // template, so the schema-contract test correctly fails for them.
+    //
+    // We drop the mappings rather than remap to Task* because the semantics
+    // diverge: TodoWrite replaced an entire flat todo list per call; Task*
+    // is single-task-by-ID. A `todo_write` → `TaskCreate` rewrite would
+    // silently truncate a list-write to creating only the first item. The
+    // unmapped-tool path handles legacy clients honestly:
+    //   • default mode → round-robin to a fallback CC tool (lossy but the
+    //     upstream accepts the request);
+    //   • hybrid mode → dropped, so the model doesn't see a phantom tool;
+    //   • --preserve-tools → client's real schema flows through untouched
+    //     (recommended for clients that actually depend on todo semantics).
+    //
     // Intentionally unmapped (dario#43): CC has no notebook-read tool, and
     // routing a read to NotebookEdit with empty new_source either fails the
     // schema (`new_source` required) or executes a destructive no-op edit.

package/dist/cli.js

@@ -31,7 +31,28 @@ import { parseOutboundProxy, installOutboundProxyWrapper } from './outbound-prox
 // `args` to read their own flags. Reading argv is harmless on import; only
 // the handler dispatch at the bottom is gated behind the main-entry check.
 const args = process.argv.slice(2);
-const command = args[0] ?? 'proxy';
+/**
+ * Default command when invoked with no args.
+ *
+ * v3.x: `dario` started the proxy (default = 'proxy').
+ * v4.0: `dario` opens the interactive TUI (default = 'tui').
+ *
+ * Migration: scripts that ran bare `dario` to launch the proxy need
+ * to switch to `dario proxy`. The TUI itself surfaces a "proxy
+ * unreachable" hint with the exact command if it doesn't see one
+ * running, so users discovering the change get pointed to the fix.
+ *
+ * `--no-tui` opt-out runs help instead (escape hatch for users who
+ * want the v3-style behavior without explicitly typing `proxy`, e.g.
+ * inside CI scripts that grep `dario` output).
+ */
+const DEFAULT_COMMAND = args.includes('--no-tui') ? 'help' : 'tui';
+// --no-tui is a meta-flag (controls DEFAULT_COMMAND above) not a command
+// itself, so when it appears as args[0] we still resolve to the default.
+// All other args pass through unchanged — `dario proxy`, `dario --help`,
+// `dario --version` etc. still dispatch as expected.
+const positionalArgs = args.filter((a) => a !== '--no-tui');
+const command = positionalArgs[0] ?? DEFAULT_COMMAND;
 async function login() {
     console.log('');
     console.log('  dario — Claude Login');
@@ -190,18 +211,33 @@ async function logout() {
     }
 }
 async function proxy() {
+    // v4: load ~/.dario/config.json once at startup so file-stored values
+    // serve as defaults below where no CLI flag / env var supplies one.
+    // Precedence per M1: defaults < file < env < CLI. Missing-file is
+    // treated as "no file values" — the existing CLI/env paths see no
+    // change. Invalid file is logged but doesn't abort; we still start
+    // with whatever the env+flags provide.
+    const { loadConfig } = await import('./config-file.js');
+    const fileResult = loadConfig();
+    const fileCfg = fileResult.config;
+    if (fileResult.source === 'invalid') {
+        console.warn(`[dario] config file present but invalid (${fileResult.error}) — using defaults + env + flags only.`);
+    }
     const portArg = args.find(a => a.startsWith('--port='));
-    const port = portArg ? parseInt(portArg.split('=')[1]) : 3456;
+    // Precedence: --port flag > DARIO_PORT env > config file > built-in default 3456
+    const portFromCli = portArg ? parseInt(portArg.split('=')[1], 10) : undefined;
+    const portFromEnv = process.env['DARIO_PORT'] ? parseInt(process.env['DARIO_PORT'], 10) : undefined;
+    const port = portFromCli ?? portFromEnv ?? fileCfg.port ?? 3456;
     if (isNaN(port) || port < 1 || port > 65535) {
         console.error('[dario] Invalid port. Must be 1-65535.');
         process.exit(1);
     }
-    // Bind address — accepts --host=<addr>; falls through to DARIO_HOST env
-    // var or the default of 127.0.0.1 inside startProxy. The sanity check
-    // here only rejects obviously bad shapes; real address validation
-    // happens when the OS tries to bind.
+    // Bind address — --host > DARIO_HOST > config file > startProxy's
+    // built-in 127.0.0.1 default. The regex sanity-check rejects
+    // obviously bad shapes; real address validation happens at bind time.
     const hostArg = args.find(a => a.startsWith('--host='));
-    const host = hostArg ? hostArg.split('=')[1] : undefined;
+    const host = hostArg ? hostArg.split('=')[1]
+        : (process.env['DARIO_HOST'] || fileCfg.host || undefined);
     if (host !== undefined && !/^[a-zA-Z0-9._:-]+$/.test(host)) {
         console.error('[dario] Invalid --host. Must be an IP address or hostname.');
         process.exit(1);
@@ -247,34 +283,33 @@ async function proxy() {
     const model = modelArg ? modelArg.split('=')[1] : undefined;
     // --pace-min=MS / --pace-jitter=MS (v3.24, direction #6 — behavioral
     // smoothing). Inter-request gap floor + optional uniform-random jitter.
-    // Defaults preserve v3.23 behavior (500ms floor, no jitter). The pure
-    // calc lives in src/pacing.ts; the flags just feed it.
-    const pacingMinMs = parsePositiveIntFlag('--pace-min=');
-    const pacingJitterMs = parsePositiveIntFlag('--pace-jitter=');
+    // v4: ~/.dario/config.json's `pacing.{minMs,jitterMs}` is the fallback
+    // when no CLI flag is set, so the TUI's Config tab can persist edits.
+    // The pure calc lives in src/pacing.ts; flags+config just feed it.
+    const pacingMinMs = parsePositiveIntFlag('--pace-min=') ?? fileCfg.pacing?.minMs;
+    const pacingJitterMs = parsePositiveIntFlag('--pace-jitter=') ?? fileCfg.pacing?.jitterMs;
     // --think-time-* / --session-start-* — behavioral smoothing extension.
-    // Closes the temporal axis the wire-fidelity work doesn't touch:
-    // response-length-correlated read time between requests, and per-
-    // session opening latency. All defaults 0 = off (opt-in).
-    const thinkTimeBaseMs = parsePositiveIntFlag('--think-time-base=');
-    const thinkTimePerTokenMs = parsePositiveIntFlag('--think-time-per-token=');
-    const thinkTimeJitterMs = parsePositiveIntFlag('--think-time-jitter=');
-    const thinkTimeMaxMs = parsePositiveIntFlag('--think-time-max=');
-    const sessionStartMinMs = parsePositiveIntFlag('--session-start-min=');
-    const sessionStartJitterMs = parsePositiveIntFlag('--session-start-jitter=');
+    // Same v4 precedence (flag > file > built-in default).
+    const thinkTimeBaseMs = parsePositiveIntFlag('--think-time-base=') ?? fileCfg.thinkTime?.baseMs;
+    const thinkTimePerTokenMs = parsePositiveIntFlag('--think-time-per-token=') ?? fileCfg.thinkTime?.perTokenMs;
+    const thinkTimeJitterMs = parsePositiveIntFlag('--think-time-jitter=') ?? fileCfg.thinkTime?.jitterMs;
+    const thinkTimeMaxMs = parsePositiveIntFlag('--think-time-max=') ?? fileCfg.thinkTime?.maxMs;
+    const sessionStartMinMs = parsePositiveIntFlag('--session-start-min=') ?? fileCfg.sessionStart?.minMs;
+    const sessionStartJitterMs = parsePositiveIntFlag('--session-start-jitter=') ?? fileCfg.sessionStart?.jitterMs;
     // --stealth flips all three pacing layers (pace, think, session-start)
-    // into their behavioral-stealth presets so the request inter-arrival
-    // distribution matches real interactive CC. One knob instead of six.
-    // Per-knob explicit flags / env vars still win, so operators can
-    // toggle stealth on and then tune individual axes.
+    // into their behavioral-stealth presets. Same v4 precedence (flag >
+    // env > file > false). Per-knob flags above still win even when
+    // stealth is on, so operators can flip on then tune individual axes.
     const stealth = args.includes('--stealth')
         || parseBooleanEnv(process.env['DARIO_STEALTH'])
+        || fileCfg.stealth
         || undefined;
     // --drain-on-close (v3.25, direction #5). When set, a client
     // disconnect no longer aborts the upstream SSE — dario keeps
     // draining the stream to EOF so Anthropic sees the CC-shaped
     // read-to-completion pattern. Costs tokens (the response is fully
     // generated even if nobody reads it), so it's opt-in.
-    const drainOnClose = args.includes('--drain-on-close') || undefined;
+    const drainOnClose = args.includes('--drain-on-close') || fileCfg.drainOnClose || undefined;
     // --session-* knobs (v3.28, direction #1). Control the single-account
     // session-id lifecycle: idle threshold, jitter on that threshold, hard
     // max-age, and whether to give each upstream client its own session.
@@ -1711,6 +1746,56 @@ async function usage() {
     }
     console.log('');
 }
+/**
+ * `dario tui` (or `dario` with no args) — opens the interactive
+ * terminal UI. v4 entry point.
+ *
+ * The TUI is a viewer/configurator; it expects a `dario proxy`
+ * already running locally for live analytics. When no proxy is
+ * reachable, each tab degrades gracefully — Status shows
+ * "unreachable" with the start-command hint, Analytics + Hits show
+ * the same. Accounts + Backends + Config don't need the proxy at
+ * all (they read disk directly).
+ *
+ * Bails out early if stdin isn't a TTY — the TUI can't function in
+ * a pipe / redirect. The error message points at `dario proxy` (the
+ * non-interactive entry) for that case.
+ *
+ * --port=<n>     target a non-default proxy port (default 3456)
+ * --api-key=KEY  authenticate against a DARIO_API_KEY-protected proxy
+ */
+async function tui() {
+    if (!process.stdin.isTTY) {
+        console.error('[dario] TUI requires an interactive terminal.');
+        console.error('  Pipe / redirect detected on stdin.');
+        console.error('  Run `dario proxy` for the non-interactive proxy server,');
+        console.error('  or `dario --no-tui` to print help instead.');
+        process.exit(1);
+    }
+    const portArg = args.find((a) => a.startsWith('--port='));
+    const port = portArg ? parseInt(portArg.split('=')[1], 10) : 3456;
+    const apiKeyArg = args.find((a) => a.startsWith('--api-key='));
+    const apiKey = apiKeyArg
+        ? apiKeyArg.split('=')[1]
+        : (process.env['DARIO_API_KEY'] || undefined);
+    const { startTuiApp } = await import('./tui/tui-app.js');
+    await startTuiApp({
+        version: pkgVersion(),
+        proxyUrl: `http://127.0.0.1:${port}`,
+        apiKey,
+    });
+}
+function pkgVersion() {
+    try {
+        // Read from the same package.json the rest of the CLI uses.
+        const pkgUrl = new URL('../package.json', import.meta.url);
+        const fs = require('node:fs');
+        return JSON.parse(fs.readFileSync(pkgUrl, 'utf-8')).version || 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
 // Main
 const commands = {
     login,
@@ -1727,6 +1812,7 @@ const commands = {
     config,
     upgrade,
     usage,
+    tui,
     help,
     version,
     '--help': help,

package/dist/config-file.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Config file foundation — v4.
+ *
+ * Persists user-tunable settings to `~/.dario/config.json` so the TUI
+ * can read + write them without having to manage shell scripts. Establishes
+ * the precedence chain that every effective value passes through:
+ *
+ *   defaults  <  config.json  <  env var  <  CLI flag
+ *
+ * Existing CLI flags + env vars continue to work unchanged. The config
+ * file is purely additive — a missing file resolves to defaults, exactly
+ * as v3 already behaved (since v3 had no config file).
+ *
+ * Atomic write: write to `config.json.tmp`, fsync, rename. Same primitive
+ * shape `atomicWriteJson` in src/live-fingerprint.ts uses for the
+ * captured CC template.
+ *
+ * Unknown keys in the loaded file are preserved (forward-compat for
+ * future schema versions); validation is best-effort, not strict — a
+ * corrupt or partial file falls back to defaults rather than aborting
+ * the process.
+ */
+/**
+ * Bumped on any incompatible shape change. v4.0.0 ships schema v1. A
+ * future shape change would either add a new optional field (no bump)
+ * or rename / restructure (bump to v2 with a migration in `loadConfig`).
+ */
+export declare const CONFIG_SCHEMA_VERSION = 1;
+/**
+ * Default `~/.dario/config.json` location. Override in tests via
+ * `loadConfig(path)` / `saveConfig(path, …)`.
+ */
+export declare const DEFAULT_CONFIG_PATH: string;
+/**
+ * Every user-tunable setting. Grouped into sub-objects when the knobs
+ * cluster naturally (pacing, thinkTime, session, queue) so the TUI's
+ * Config tab can render each cluster as a folder without extra glue.
+ *
+ * Optional everywhere — a partially-populated config file is valid; the
+ * proxy fills in defaults for whatever's absent.
+ */
+export interface DarioConfig {
+    /** Schema version of this file. Required for forward-compat. */
+    version: number;
+    port?: number;
+    host?: string;
+    model?: string | null;
+    passthrough?: boolean;
+    preserveTools?: boolean;
+    hybridTools?: boolean;
+    mergeTools?: boolean;
+    noAutoDetect?: boolean;
+    strictTls?: boolean;
+    strictTemplate?: boolean;
+    noLiveCapture?: boolean;
+    drainOnClose?: boolean;
+    stealth?: boolean;
+    pacing?: {
+        minMs?: number;
+        jitterMs?: number;
+    };
+    thinkTime?: {
+        baseMs?: number;
+        perTokenMs?: number;
+        jitterMs?: number;
+        maxMs?: number;
+    };
+    sessionStart?: {
+        minMs?: number;
+        jitterMs?: number;
+    };
+    session?: {
+        idleRotateMs?: number;
+        rotateJitterMs?: number;
+        maxAgeMs?: number | null;
+        perClient?: boolean;
+    };
+    queue?: {
+        maxConcurrent?: number | null;
+        maxQueued?: number | null;
+        timeoutMs?: number | null;
+    };
+    effort?: string | null;
+    maxTokens?: number | 'client' | null;
+    passthroughBetas?: string[];
+    systemPrompt?: string | null;
+    preserveOrchestrationTags?: boolean;
+    logFile?: string | null;
+}
+/**
+ * Defaults match the v3.x CLI flag defaults exactly. Any value not
+ * specified in config.json resolves to its corresponding default here.
+ * Updates to a flag default MUST land here too so they stay in sync.
+ */
+export declare function defaultConfig(): DarioConfig;
+/**
+ * Load the config file at `path` (default ~/.dario/config.json).
+ *
+ * Returns `{ config, source }` where `source` describes the load outcome
+ * for the caller's UI:
+ *
+ *   - 'file'    — successfully loaded
+ *   - 'missing' — file doesn't exist; defaults returned (not an error)
+ *   - 'invalid' — file exists but parse / shape check failed; defaults
+ *                 returned. The TUI surfaces this so the user knows
+ *                 their saved settings were ignored.
+ *
+ * The loaded shape is type-checked field-by-field: unknown keys pass
+ * through (forward-compat), known keys with wrong types are dropped.
+ * Strict validation would force a config migration on every shape
+ * tweak; loose-but-typed lets the file evolve without breaking older
+ * dario installs that haven't been restarted.
+ */
+export declare function loadConfig(path?: string): {
+    config: DarioConfig;
+    source: 'file' | 'missing' | 'invalid';
+    error?: string;
+};
+/**
+ * Atomically write `config` to `path`. Writes to `<path>.tmp`, then
+ * renames into place — guarantees a reader never observes a half-written
+ * file. Creates parent directories if missing.
+ *
+ * Throws on permission / disk failures (caller handles + surfaces to
+ * the TUI's status line). Does NOT throw on a no-op rewrite of the
+ * same content; that's a cheap idempotent path.
+ */
+export declare function saveConfig(path: string | undefined, config: DarioConfig): void;
+/**
+ * Deep-merge `over` into `base`, preferring `over` values where defined.
+ * Nested objects are merged recursively; arrays and primitives are
+ * replaced wholesale (no array-element merge — that'd be surprising).
+ *
+ * `undefined` in `over` is treated as "absent" and falls through to
+ * the `base` value. `null` is a real value and overrides.
+ */
+export declare function mergeOver<T extends object>(base: T, over: Partial<T>): T;
+/**
+ * Resolve the effective config: load file, layer env vars on top, layer
+ * CLI flags on top.
+ *
+ *   defaults  <  config.json  <  env  <  cli
+ *
+ * `cliOverrides` and `envOverrides` are partial — only the keys the
+ * caller actually wants to override should be set. `undefined` keys
+ * are skipped, so the existing flag parsers in cli.ts can pass through
+ * their normalized output without filtering nulls.
+ */
+export declare function resolveConfig(opts: {
+    path?: string;
+    envOverrides?: Partial<DarioConfig>;
+    cliOverrides?: Partial<DarioConfig>;
+}): {
+    config: DarioConfig;
+    source: 'file' | 'missing' | 'invalid';
+    error?: string;
+};