@cliftonc/finius 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clifton Cunningham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+<div align="center">
+
+<img src="public/favicon.svg" alt="Finius" width="96" height="96" />
+
+# Finius
+
+**Local-first Claude Code usage & cost tracker.**
+
+A [Hono](https://hono.dev) server ingests OTLP HTTP/JSON metrics & logs (and JSONL transcripts) into
+SQLite; a React + Vite dashboard renders cost, token, session, person, and model breakdowns with live
+SSE updates. Everything runs on your machine — no data leaves your laptop.
+
+<img src="public/finius-dashboard.png" alt="Finius dashboard showing local usage and cost analytics" width="900" />
+
+</div>
+
+## Quick start (local)
+
+The fastest way to get running locally is the `finius` CLI. You need **Node 22.5+** (Finius uses the
+built-in `node:sqlite` module; developed on Node 24).
+
+```bash
+npx @cliftonc/finius # first run: installs finius globally, then walks you through setup
+finius serve         # start the server + dashboard at http://localhost:8787
+finius import all    # optional: import old Claude Code + Codex sessions
+```
+
+Then launch Claude Code in a new terminal and start coding — the dashboard at
+**http://localhost:8787** updates live as telemetry arrives.
+
+That's it. Three things just happened:
+
+1. **`npx @cliftonc/finius`** installed `finius` globally and ran `finius setup`, which saved
+   `~/.finius/config.json` and — with your consent — edited `~/.claude/settings.json` to add the OTLP
+   env vars plus a `SessionEnd` + `PreCompact` hook (`finius hook`) that uploads each session
+   transcript.
+2. **`finius serve`** started a single process exposing the API **and** the dashboard on one port.
+   Its data lives under `~/.finius` (override with `FINIUS_DB_PATH` / `FINIUS_BLOB_DIR`).
+3. Any Claude Code session you run now reports usage to that local server. If you ran
+   `finius import all`, Finius also backfilled historical Claude Code and Codex transcripts already on
+   disk. Use `finius import claude` or `finius import codex` to import only one agent.
+
+Re-run `finius setup` any time to reconfigure, or `finius doctor` to diagnose telemetry that isn't
+arriving.
+
+## Running from source (development)
+
+Prefer to hack on Finius itself? Clone the repo and run the dev servers.
+
+### 1. Install & start
+
+```bash
+npm install
+npm run dev
+```
+
+`npm run dev` runs the API and UI together (via `concurrently`):
+
+- **UI** → http://localhost:5173 (Vite dev server; proxies `/api`, `/otlp`, `/events` to the API)
+- **API** → http://localhost:8787
+
+Run them separately if you prefer: `npm run dev:server` (API only) or `npm run dev:client` (UI only).
+
+### 2. Point Claude Code at the server
+
+In the shell where you launch Claude Code, use the bundled helper — it checks the server is up,
+exports the OTLP env vars, then runs `claude`:
+
+```bash
+./scripts/run-claude.sh                 # forwards any extra args to `claude`
+```
+
+Or export the variables manually:
+
+```bash
+export CLAUDE_CODE_ENABLE_TELEMETRY=1
+export OTEL_METRICS_EXPORTER=otlp
+export OTEL_LOGS_EXPORTER=otlp
+export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/json
+export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/json
+export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://localhost:8787/otlp/v1/metrics
+export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://localhost:8787/otlp/v1/logs
+claude
+```
+
+Run a Claude Code session and the dashboard updates live (SSE) as telemetry arrives.
+
+### 3. (Optional) production build
+
+```bash
+npm run build   # tsc -> dist + vite build -> dist/client
+npm start       # node dist/server/index.js, serves the built UI from dist/client on :8787
+```
+
+When a build exists, `npm start` serves the UI and API from the single port http://localhost:8787.
+
+## Using the dashboard
+
+- **Home** — KPIs (cost, tokens, cache, lines, edits, sessions, people), tokens/cost/lines/edits
+  charts over time, plus Models / Users / Sources breakdowns.
+- **Sessions**, **People**, **Models** — lists ranked by recency / cost. Click any row (or any Home
+  breakdown row) to drill into the Home view filtered to that session, person, or model.
+- **Filters** — time range, source, user, and model selects apply everywhere. All view and filter
+  state lives in the URL query string, so any view is shareable/bookmarkable and back/forward works.
+
+## Importing transcripts
+
+Besides live OTLP telemetry, you can backfill from JSONL transcripts:
+
+- `POST /api/import/jsonl` — body `{ content, source?, sessionId? }` (or raw JSONL text).
+- `POST /api/import/claude-hook` — body `{ transcript_path, session_id?, cwd? }`; reads a local
+  Claude Code transcript file (restricted to `~/.claude/projects` or the given `cwd`).
+
+Imports are idempotent — re-sending the same file (matched by content hash) is detected and skipped.
+The original transcript is stored as a file and can be viewed from the session drill-down
+(`GET /api/sessions/:id/transcript`).
+
+## Storage
+
+Data is stored in `data/finius.sqlite` by default. Override with `FINIUS_DB_PATH=/path/to/db.sqlite`.
+Override the API port with `PORT`. Imported transcript files live under `<db-dir>/transcripts`
+(override with `FINIUS_BLOB_DIR`).
+
+Dashboard reads are served from a pre-aggregated hourly `metric_rollup`; raw `metric_points` keep
+the full-resolution data for the live view and drill-downs.
+
+### Raw batch retention
+
+The full OTLP payload of each ingest batch is kept in `raw_batches` only to allow replaying history
+into new metric classifications. Control it with:
+
+- `FINIUS_RAW_PAYLOADS=retain` (default) | `off` — `off` keeps only the dedup hash, not the payload.
+- `FINIUS_RAW_RETENTION_DAYS=7` (default) — age cutoff used by the prune endpoint below.
+- `FINIUS_CRON_TOKEN=<secret>` — enables `POST /api/maintenance/prune-raw-batches`. Without it the
+  endpoint is disabled (returns 503). Wire a cron to it:
+
+  ```bash
+  curl -fsS -X POST -H "Authorization: Bearer $FINIUS_CRON_TOKEN" \
+    http://127.0.0.1:8787/api/maintenance/prune-raw-batches
+  ```
+
+## Other commands
+
+```bash
+npm test         # vitest run
+npm run typecheck # tsc --noEmit (strict)
+```

package/dist/branding.js

@@ -0,0 +1,28 @@
+import pc from "picocolors";
+// Shared brand presentation with NO interactive-prompt dependency, so both the CLI (cli/ui.ts) and
+// the long-running server (server/index.ts) can render the wordmark without pulling in @clack/prompts.
+export const BANNER_LINES = [
+    "███████╗██╗███╗   ██╗██╗██╗   ██╗███████╗",
+    "██╔════╝██║████╗  ██║██║██║   ██║██╔════╝",
+    "█████╗  ██║██╔██╗ ██║██║██║   ██║███████╗",
+    "██╔══╝  ██║██║╚██╗██║██║██║   ██║╚════██║",
+    "██║     ██║██║ ╚████║██║╚██████╔╝███████║",
+    "╚═╝     ╚═╝╚═╝  ╚═══╝╚═╝ ╚═════╝ ╚══════╝"
+];
+export const TAGLINE = "Local-first AI coding usage & cost tracker";
+// The colored wordmark + tagline. `subtitle` names the running command (e.g. "setup", "serve").
+export function renderBanner(subtitle) {
+    const art = BANNER_LINES.map((line) => pc.cyan(line)).join("\n");
+    const sub = subtitle ? `  ${pc.dim("·")}  ${pc.cyan(subtitle)}` : "";
+    return `\n${art}\n${pc.dim(TAGLINE)}${sub}\n`;
+}
+export function banner(subtitle) {
+    process.stdout.write(renderBanner(subtitle));
+}
+// An aligned label/value block (dim labels, padded to a common width). ANSI-safe because padding is
+// computed on the plain label text before any coloring is applied to the value.
+export function panel(rows) {
+    const width = Math.max(0, ...rows.map(([label]) => label.length));
+    return rows.map(([label, value]) => `  ${pc.dim(label.padEnd(width))}   ${value}`).join("\n");
+}
+export { pc };

package/dist/cli/backfill.js

@@ -0,0 +1,122 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { log, spinner } from "@clack/prompts";
+import { loadConfig, resolveAuthToken, resolveServerUrl } from "./config.js";
+import { resolveIdentity } from "./identity.js";
+import { pc } from "./ui.js";
+const CLAUDE_PROJECTS_DIR = join(homedir(), ".claude", "projects");
+// Recursively collect files under `dir` whose basename matches `match`. Safe on missing dirs.
+export function walkFiles(dir, match) {
+    const out = [];
+    const walk = (d) => {
+        let names;
+        try {
+            names = readdirSync(d);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const p = join(d, name);
+            let st;
+            try {
+                st = statSync(p);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory())
+                walk(p);
+            else if (st.isFile() && match(name))
+                out.push(p);
+        }
+    };
+    walk(dir);
+    return out;
+}
+// Every Claude Code transcript on disk (~/.claude/projects/**/<session>.jsonl).
+export function findClaudeTranscripts() {
+    return walkFiles(CLAUDE_PROJECTS_DIR, (n) => n.endsWith(".jsonl"));
+}
+// Upload one transcript file to the server. Idempotent server-side (content hash / replace-by-session).
+// Attributes the upload to a user: an explicit `identity` if given, else resolved from config by format
+// (so both the setup backfill and the Codex hook attach a user with no extra threading).
+export async function uploadTranscript(path, opts) {
+    let content;
+    try {
+        content = readFileSync(path, "utf8");
+    }
+    catch {
+        return "failed";
+    }
+    if (!content.trim())
+        return "failed";
+    const config = loadConfig();
+    const endpoint = `${resolveServerUrl()}/api/import/jsonl`;
+    const headers = { "content-type": "application/json" };
+    const token = resolveAuthToken(config);
+    if (token)
+        headers.authorization = `Bearer ${token}`;
+    const identity = opts.identity ?? resolveIdentity(opts.format === "codex" ? "codex" : "claude", config, opts.cwd);
+    try {
+        const res = await fetch(endpoint, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+                content,
+                source: opts.source,
+                format: opts.format,
+                sessionId: opts.sessionId,
+                userEmail: identity?.email,
+                userAccountId: identity?.accountId,
+                userId: identity?.userId,
+                githubLogin: identity?.githubLogin,
+                displayName: identity?.displayName
+            }),
+            signal: AbortSignal.timeout(60_000)
+        });
+        if (!res.ok) {
+            process.stderr.write(`\nfinius: ${endpoint} returned ${res.status}\n`);
+            return "failed";
+        }
+        const body = (await res.json().catch(() => ({})));
+        return body.duplicate ? "duplicate" : "ok";
+    }
+    catch (err) {
+        process.stderr.write(`\nfinius: upload to ${endpoint} failed (${err.message})\n`);
+        return "failed";
+    }
+}
+// Upload a list of transcripts ONE AT A TIME — never concurrently, which would swamp the server with
+// large bodies — rendering a live spinner with progress. Returns tallied outcomes.
+export async function backfill(files, opts) {
+    const result = { uploaded: 0, duplicate: 0, failed: 0, total: files.length };
+    if (files.length === 0) {
+        log.info(`${opts.label}: nothing to import.`);
+        return result;
+    }
+    const total = files.length;
+    const s = spinner();
+    s.start(`Importing ${opts.label}`);
+    let done = 0;
+    for (const file of files) {
+        const outcome = await uploadTranscript(file, { source: opts.source, format: opts.format });
+        if (outcome === "ok")
+            result.uploaded++;
+        else if (outcome === "duplicate")
+            result.duplicate++;
+        else
+            result.failed++;
+        done++;
+        s.message(`Importing ${opts.label} ${pc.dim(`(${done}/${total})`)}`);
+    }
+    const summary = `${opts.label}: ${pc.green(`${result.uploaded} new`)}, ${result.duplicate} already-present` +
+        (result.failed > 0 ? `, ${pc.red(`${result.failed} failed`)}` : "") +
+        ` (of ${result.total}).`;
+    s.stop(summary);
+    if (result.failed > 0) {
+        log.warn("Failures usually mean the server isn't running — `finius serve`, then re-run setup.");
+    }
+    return result;
+}

package/dist/cli/claude-settings.js

@@ -0,0 +1,54 @@
+// Pure helpers for merging Finius configuration into Claude Code's ~/.claude/settings.json.
+// Kept side-effect-free (no fs) so they're easy to unit test; setup.ts handles the actual read/write.
+// Hook events that upload the session transcript. SessionEnd covers /clear and exit; PreCompact
+// captures the full transcript before a compaction shrinks the context window.
+export const TELEMETRY_HOOK_EVENTS = ["SessionEnd", "PreCompact"];
+export const HOOK_TIMEOUT_SECONDS = 60;
+// Substring used to recognize (and replace) a previously-installed Finius hook. The package is named
+// "finius" and is virtually always installed under a path containing it, so this reliably matches our
+// own hook command without touching unrelated user hooks.
+const FINIUS_MARKER = "finius";
+// Point Claude Code's OTLP exporters at the given Finius server. Preserves any existing env vars.
+// When `authToken` is set (Secure Mode), also send it on every OTLP export via the standard
+// Authorization header; when absent, strip any header we previously wrote so toggling auth off cleans
+// up. Tokens are URL-safe hex, so the single space in "Bearer " is the only special char and the OTel
+// JS header parser (comma/equals-delimited key=value) preserves it.
+export function withTelemetryEnv(settings, serverUrl, authToken) {
+    settings.env = {
+        ...settings.env,
+        CLAUDE_CODE_ENABLE_TELEMETRY: "1",
+        OTEL_METRICS_EXPORTER: "otlp",
+        OTEL_LOGS_EXPORTER: "otlp",
+        // Finius ingests OTLP/JSON. Set both the generic and per-signal protocol keys — some OTel SDK
+        // versions only read the generic one, and its default (http/protobuf) would be rejected.
+        OTEL_EXPORTER_OTLP_PROTOCOL: "http/json",
+        OTEL_EXPORTER_OTLP_METRICS_PROTOCOL: "http/json",
+        OTEL_EXPORTER_OTLP_LOGS_PROTOCOL: "http/json",
+        OTEL_EXPORTER_OTLP_METRICS_ENDPOINT: `${serverUrl}/otlp/v1/metrics`,
+        OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: `${serverUrl}/otlp/v1/logs`,
+        // Flush quickly so usage shows up in seconds rather than the 60s/5s defaults.
+        OTEL_METRIC_EXPORT_INTERVAL: "10000",
+        OTEL_LOGS_EXPORT_INTERVAL: "5000"
+    };
+    if (authToken) {
+        settings.env.OTEL_EXPORTER_OTLP_HEADERS = `Authorization=Bearer ${authToken}`;
+    }
+    else {
+        delete settings.env.OTEL_EXPORTER_OTLP_HEADERS;
+    }
+    return settings;
+}
+// Install the Finius transcript-upload hook for each telemetry event. Any prior Finius hook group is
+// dropped first so re-running setup never duplicates the entry; unrelated user hooks are preserved.
+export function withFiniusHook(settings, command) {
+    const group = { hooks: [{ type: "command", command, timeout: HOOK_TIMEOUT_SECONDS }] };
+    const hooks = settings.hooks ?? (settings.hooks = {});
+    for (const event of TELEMETRY_HOOK_EVENTS) {
+        const kept = (hooks[event] ?? []).filter((g) => !isFiniusGroup(g));
+        hooks[event] = [...kept, group];
+    }
+    return settings;
+}
+function isFiniusGroup(group) {
+    return group.hooks?.some((h) => h.command?.includes(FINIUS_MARKER)) ?? false;
+}

package/dist/cli/codex-config.js

@@ -0,0 +1,60 @@
+// Pure helpers for merging Finius config into OpenAI Codex's ~/.codex/config.toml. Like
+// claude-settings.ts these are side-effect-free (no fs) so they unit-test cleanly; codex.ts does the
+// read/write. Codex's config is TOML and we ship no TOML parser, so Finius owns a single clearly
+// delimited block appended at EOF — valid TOML because it only opens fresh top-level tables. Re-running
+// setup replaces that block in place; existing user tables are never touched, and we refuse to add a
+// table the user already defines (so we can never produce a duplicate-key parse error).
+export const CODEX_HOOK_EVENT = "Stop";
+const BLOCK_BEGIN = "# >>> finius (managed — safe to delete this whole block) >>>";
+const BLOCK_END = "# <<< finius (managed) <<<";
+export function withFiniusCodexBlock(toml, opts) {
+    const outside = stripFiniusBlock(toml);
+    const hasUserHooks = /^\s*\[\[?\s*hooks(\.|\s*\])/m.test(outside);
+    const hasUserOtel = /^\s*\[\s*otel\s*\]/m.test(outside);
+    const wantHook = !!opts.hookCommand;
+    const wantOtel = !!opts.otlpLogsEndpoint;
+    const addedHook = wantHook && !hasUserHooks;
+    const addedOtel = wantOtel && !hasUserOtel;
+    const parts = [];
+    if (addedHook) {
+        parts.push(`[[hooks.${CODEX_HOOK_EVENT}]]`, `[[hooks.${CODEX_HOOK_EVENT}.hooks]]`, `type = "command"`, `command = ${tomlString(opts.hookCommand)}`, "");
+    }
+    if (addedOtel) {
+        const headers = opts.authToken
+            ? `, headers = { Authorization = ${tomlString(`Bearer ${opts.authToken}`)} }`
+            : "";
+        parts.push("[otel]", `environment = "finius"`, "log_user_prompt = false", `exporter = { otlp-http = { endpoint = ${tomlString(opts.otlpLogsEndpoint)}, protocol = "json"${headers} } }`, "");
+    }
+    const result = {
+        toml: outside,
+        changed: outside !== toml,
+        addedHook,
+        addedOtel,
+        skippedHook: wantHook && hasUserHooks,
+        skippedOtel: wantOtel && hasUserOtel
+    };
+    if (parts.length === 0)
+        return result;
+    const block = [BLOCK_BEGIN, ...parts, BLOCK_END].join("\n");
+    const base = outside.replace(/\s*$/, "");
+    result.toml = base.length ? `${base}\n\n${block}\n` : `${block}\n`;
+    result.changed = true;
+    return result;
+}
+// Remove a previously-written Finius block (between the markers), leaving the rest untouched.
+export function stripFiniusBlock(toml) {
+    const begin = toml.indexOf(BLOCK_BEGIN);
+    if (begin === -1)
+        return toml;
+    const endIdx = toml.indexOf(BLOCK_END, begin);
+    const before = toml.slice(0, begin).replace(/\s*$/, "");
+    const after = endIdx === -1 ? "" : toml.slice(endIdx + BLOCK_END.length).replace(/^\s*\n/, "");
+    const joined = after ? `${before}\n${after}` : `${before}\n`;
+    return joined.replace(/\n{3,}/g, "\n\n");
+}
+export function hasFiniusCodexBlock(toml) {
+    return toml.includes(BLOCK_BEGIN);
+}
+function tomlString(value) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}

package/dist/cli/codex.js

@@ -0,0 +1,97 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { withFiniusCodexBlock } from "./codex-config.js";
+import { uploadTranscript, walkFiles } from "./backfill.js";
+// Codex stores everything under ~/.codex (override with CODEX_HOME, as the app itself does).
+export const CODEX_HOME = process.env.CODEX_HOME ? resolve(process.env.CODEX_HOME) : join(homedir(), ".codex");
+export const CODEX_CONFIG_PATH = join(CODEX_HOME, "config.toml");
+const CODEX_SESSIONS_DIR = join(CODEX_HOME, "sessions");
+export const CODEX_SOURCE = "codex-cli-jsonl";
+// Codex is "installed" if its home dir or the macOS app bundle is present.
+export function isCodexInstalled() {
+    return existsSync(CODEX_HOME) || existsSync("/Applications/Codex.app");
+}
+// Apply (or refresh) the Finius-managed block in ~/.codex/config.toml. Pure merge in codex-config.ts;
+// this just does the read/write. Creates the file if missing.
+export function applyCodexConfig(opts) {
+    const current = existsSync(CODEX_CONFIG_PATH) ? readFileSync(CODEX_CONFIG_PATH, "utf8") : "";
+    const result = withFiniusCodexBlock(current, opts);
+    if (result.changed) {
+        mkdirSync(dirname(CODEX_CONFIG_PATH), { recursive: true });
+        writeFileSync(CODEX_CONFIG_PATH, result.toml, "utf8");
+    }
+    return result;
+}
+// Every Codex rollout transcript on disk (~/.codex/sessions/**/rollout-*.jsonl).
+export function findCodexRollouts() {
+    return walkFiles(CODEX_SESSIONS_DIR, (n) => n.startsWith("rollout-") && n.endsWith(".jsonl"));
+}
+// `finius codex-hook` — invoked by Codex's Stop hook. Codex passes a JSON payload on stdin (shape not
+// fully documented), so we read it best-effort but don't depend on it: we locate the session's rollout
+// file ourselves (by session id if present, else the most-recently-modified rollout) and upload it.
+// The server replaces the session's prior Codex points on every upload, so re-firing per turn is safe.
+// Always resolves 0 — a hook must never block or fail the agent.
+export async function runCodexHook() {
+    let payload = {};
+    try {
+        const raw = await readStdin();
+        if (raw.trim())
+            payload = JSON.parse(raw);
+    }
+    catch {
+        // unparseable stdin — fall back to "newest rollout"
+    }
+    const sessionId = firstString(payload, ["session_id", "sessionId", "conversation_id", "id", "thread_id"]);
+    const explicit = firstString(payload, ["rollout_path", "transcript_path", "path", "rollout"]);
+    const cwd = firstString(payload, ["cwd", "workdir", "working_directory"]);
+    const rollout = explicit && existsSync(explicit) ? explicit : findRollout(sessionId);
+    if (!rollout)
+        return 0;
+    // uploadTranscript resolves the Codex identity from config (git-fallback uses cwd) on its own.
+    await uploadTranscript(rollout, { source: CODEX_SOURCE, format: "codex", sessionId, cwd });
+    return 0;
+}
+// Newest rollout under ~/.codex/sessions/**, optionally restricted to those whose filename contains
+// the given session id (Codex names files `rollout-<ts>-<sessionId>.jsonl`).
+export function findRollout(sessionId) {
+    const all = findCodexRollouts();
+    if (!all.length)
+        return null;
+    const pool = sessionId ? all.filter((f) => f.includes(sessionId)) : all;
+    const candidates = pool.length ? pool : all;
+    let best = candidates[0];
+    let bestMtime = mtime(best);
+    for (const f of candidates.slice(1)) {
+        const m = mtime(f);
+        if (m > bestMtime) {
+            best = f;
+            bestMtime = m;
+        }
+    }
+    return best;
+}
+function mtime(path) {
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+function firstString(obj, keys) {
+    for (const key of keys) {
+        const value = obj[key];
+        if (typeof value === "string" && value.length > 0)
+            return value;
+    }
+    return undefined;
+}
+async function readStdin() {
+    if (process.stdin.isTTY)
+        return "";
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}

package/dist/cli/config.js

@@ -0,0 +1,41 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+// Everything the CLI owns lives under ~/.finius (override with FINIUS_HOME).
+export const FINIUS_HOME = process.env.FINIUS_HOME ? resolve(process.env.FINIUS_HOME) : join(homedir(), ".finius");
+export const CONFIG_PATH = join(FINIUS_HOME, "config.json");
+export const DEFAULT_SERVER_URL = "http://localhost:8787";
+export function configExists() {
+    return existsSync(CONFIG_PATH);
+}
+export function loadConfig() {
+    if (!existsSync(CONFIG_PATH))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+        return {
+            ...raw,
+            serverUrl: normalizeUrl(raw.serverUrl) || DEFAULT_SERVER_URL
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// This machine's credential for Secure Mode. Only minted session tokens are valid on protected
+// endpoints; the master password is accepted solely by /api/auth/login.
+export function resolveAuthToken(config) {
+    return config?.authToken ?? undefined;
+}
+export function saveConfig(config) {
+    mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+    writeFileSync(CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+// Resolution order: explicit env override → saved config → built-in default.
+export function resolveServerUrl() {
+    return normalizeUrl(process.env.FINIUS_SERVER_URL) || loadConfig()?.serverUrl || DEFAULT_SERVER_URL;
+}
+// Trim whitespace and any trailing slashes so we can safely append paths.
+export function normalizeUrl(value) {
+    return (value ?? "").trim().replace(/\/+$/, "");
+}