quotacap 0.0.1

package/dist/http/server.js

@@ -0,0 +1,142 @@
+import Fastify from "fastify";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { webHtml } from "../webHtml.js";
+import { webAssets } from "../webAssets.js";
+// per-app state registry for backward-compat helpers
+const appStates = new WeakMap();
+const allStates = new Set();
+export function buildApp(db) {
+    const state = { lastPollAt: null, lastRefreshAt: 0, lastRefreshResult: null };
+    const app = Fastify({ logger: false });
+    appStates.set(app, state);
+    allStates.add(state);
+    app.addHook("onClose", async () => {
+        appStates.delete(app);
+        allStates.delete(state);
+    });
+    // expose for per-app helpers
+    app._quotacapState = state;
+    app.get("/health", async () => ({ ok: true, uptime: process.uptime(), lastPollAt: state.lastPollAt }));
+    app.get("/api/quotas", async () => {
+        const { getAllLatest } = await import("../store/quotas.js");
+        const quotas = getAllLatest(db);
+        const now = Date.now();
+        return quotas.map((q) => {
+            const fetched = q.fetchedAt ? new Date(q.fetchedAt).getTime() : 0;
+            const ageMs = fetched ? now - fetched : Infinity;
+            const stale = ageMs > 60 * 60 * 1000;
+            return { ...q, stale, ageMs };
+        });
+    });
+    app.get("/api/recommendation", async (req) => {
+        const { getAllLatest } = await import("../store/quotas.js");
+        const quotas = getAllLatest(db);
+        if (!quotas.length) {
+            return { use: "none", reason: "no quotas yet", alternatives: [], advisories: [] };
+        }
+        let recommend;
+        try {
+            recommend = (await import("../advisory/engine.js")).recommend;
+        }
+        catch {
+            return { use: quotas[0]?.provider ?? "none", reason: "advisory not yet implemented", alternatives: quotas };
+        }
+        try {
+            const task = req.query?.task ?? "any";
+            return recommend(quotas, task);
+        }
+        catch (e) {
+            return { use: quotas[0]?.provider ?? "none", reason: `advisory error: ${e?.message ?? String(e)}`, alternatives: quotas };
+        }
+    });
+    app.post("/api/refresh", async () => {
+        const now = Date.now();
+        if (now - state.lastRefreshAt < 60_000 && state.lastRefreshResult) {
+            return state.lastRefreshResult;
+        }
+        try {
+            const { pollOnce } = await import("../daemon.js");
+            const { readConfig } = await import("../config.js");
+            const cfg = await readConfig();
+            const results = await pollOnce(db, cfg.enabledProviders);
+            const fulfilled = results.filter((r) => r.status === "fulfilled").map((r) => r.value);
+            const rejected = results.filter((r) => r.status === "rejected").map((r) => ({ provider: r.provider, reason: String(r.reason?.message ?? r.reason) }));
+            state.lastPollAt = new Date().toISOString();
+            state.lastRefreshAt = now;
+            state.lastRefreshResult = { fulfilled, rejected, lastPollAt: state.lastPollAt, results, degraded: rejected.length > 0 };
+            return state.lastRefreshResult;
+        }
+        catch (e) {
+            return { fulfilled: [], rejected: [{ provider: "all", reason: String(e?.message ?? e) }], lastPollAt: state.lastPollAt, degraded: true, error: String(e?.message ?? e) };
+        }
+    });
+    // serve built vite assets at /assets/* (web/dist/assets/*)
+    app.get("/assets/*", async (req, reply) => {
+        const assetPath = req.params["*"] ?? "";
+        // guard path traversal
+        if (assetPath.includes(".."))
+            return reply.status(400).send("bad path");
+        const candidates = [
+            path.join(path.dirname(fileURLToPath(import.meta.url)), "../../web/dist/assets", assetPath),
+            path.join(process.cwd(), "web/dist/assets", assetPath),
+        ];
+        for (const p of candidates) {
+            try {
+                const data = fs.readFileSync(p);
+                const ext = path.extname(p);
+                const type = ext === ".js" ? "application/javascript" : ext === ".css" ? "text/css" : ext === ".map" ? "application/json" : "application/octet-stream";
+                return reply.type(type).send(data);
+            }
+            catch { }
+        }
+        const embedded = webAssets[assetPath];
+        if (embedded !== undefined) {
+            const ext = path.extname(assetPath);
+            const type = ext === ".js" ? "application/javascript" : ext === ".css" ? "text/css" : ext === ".map" ? "application/json" : "application/octet-stream";
+            return reply.type(type).send(embedded);
+        }
+        return reply.status(404).send("not found");
+    });
+    app.get("/", async (_req, reply) => {
+        const candidates = [
+            path.join(path.dirname(fileURLToPath(import.meta.url)), "../../web/dist/index.html"),
+            path.join(path.dirname(fileURLToPath(import.meta.url)), "../../web/index.html"),
+            path.join(process.cwd(), "web/dist/index.html"),
+            path.join(process.cwd(), "web/index.html"),
+        ];
+        for (const p of candidates) {
+            try {
+                const html = fs.readFileSync(p, "utf8");
+                return reply.type("text/html").send(html);
+            }
+            catch { }
+        }
+        return reply.type("text/html").send(webHtml ?? `<!doctype html><title>QuotaCap</title><div id=app>loading…</div>`);
+    });
+    return app;
+}
+export function getLastPollAt(app) {
+    if (app && appStates.has(app))
+        return appStates.get(app).lastPollAt;
+    // fallback: most recent state (for tests without app arg)
+    let last = null;
+    for (const s of allStates)
+        last = s.lastPollAt;
+    return last;
+}
+export function resetRefreshState(app) {
+    if (app && appStates.has(app)) {
+        const s = appStates.get(app);
+        s.lastPollAt = null;
+        s.lastRefreshAt = 0;
+        s.lastRefreshResult = null;
+        return;
+    }
+    for (const s of allStates) {
+        s.lastPollAt = null;
+        s.lastRefreshAt = 0;
+        s.lastRefreshResult = null;
+    }
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,41 @@
+export declare const tools: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            task?: undefined;
+            provider?: undefined;
+        };
+        required: never[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            task: {
+                type: string;
+                enum: string[];
+            };
+            provider?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            provider: {
+                type: string;
+            };
+            task?: undefined;
+        };
+        required: string[];
+    };
+})[];
+export declare function handleTool(name: string, args: any): Promise<any>;
+export declare function runMcpServer(): Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,101 @@
+export const tools = [
+    { name: "get_quotas", description: "All quotas with resets and health", inputSchema: { type: "object", properties: {}, required: [] } },
+    { name: "get_recommendation", description: "Which provider to use next", inputSchema: { type: "object", properties: { task: { type: "string", enum: ["any", "heavy", "light"] } } } },
+    { name: "forecast", description: "Burn vs ideal + waste for a provider", inputSchema: { type: "object", properties: { provider: { type: "string" } }, required: ["provider"] } },
+];
+async function fetchJson(path) {
+    const base = process.env.QUOTACAP_URL ?? "http://localhost:8787";
+    try {
+        const r = await fetch(`${base}${path}`, { signal: AbortSignal.timeout(5000) });
+        if (!r.ok)
+            throw new Error(`HTTP ${r.status}`);
+        return r.json();
+    }
+    catch (e) {
+        // any transport failure (node or bun wording) is a daemon-down situation
+        throw new Error(`daemon not running, run quotacap web — ${e?.message ?? String(e)}`);
+    }
+}
+export async function handleTool(name, args) {
+    if (name === "get_quotas")
+        return fetchJson("/api/quotas");
+    if (name === "get_recommendation")
+        return fetchJson(`/api/recommendation?task=${args?.task ?? "any"}`);
+    if (name === "forecast") {
+        if (!args?.provider)
+            throw new Error("provider required");
+        const [quotas, rec] = await Promise.all([fetchJson("/api/quotas"), fetchJson(`/api/recommendation`)]);
+        const q = quotas.find((x) => x.provider === args.provider);
+        if (!q)
+            throw new Error(`unknown provider ${args.provider}`);
+        return { quota: q, advisory: rec.advisories?.find((a) => a.provider === args.provider) };
+    }
+    throw new Error(`unknown tool ${name}`);
+}
+export async function runMcpServer() {
+    // Minimal MCP JSON-RPC stdio server — handles initialize, tools/list, tools/call, ping
+    const readline = await import("node:readline");
+    const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+    const respond = (id, result) => {
+        process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n");
+    };
+    const error = (id, code, message) => {
+        process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }) + "\n");
+    };
+    rl.on("line", async (line) => {
+        if (!line.trim())
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        const { id, method, params } = msg;
+        // notifications have no id — no response
+        const isNotification = id === undefined;
+        try {
+            if (method === "initialize") {
+                if (!isNotification)
+                    respond(id, { protocolVersion: "2024-11-05", capabilities: { tools: {} }, serverInfo: { name: "quotacap", version: "0.0.1" } });
+            }
+            else if (method === "notifications/initialized") {
+                // no-op
+            }
+            else if (method === "tools/list") {
+                if (!isNotification)
+                    respond(id, { tools });
+            }
+            else if (method === "tools/call") {
+                const toolName = params?.name;
+                const toolArgs = params?.arguments ?? {};
+                try {
+                    const result = await handleTool(toolName, toolArgs);
+                    const content = [{ type: "text", text: JSON.stringify(result, null, 2) }];
+                    if (!isNotification)
+                        respond(id, { content });
+                }
+                catch (e) {
+                    const content = [{ type: "text", text: e?.message ?? String(e) }];
+                    if (!isNotification)
+                        respond(id, { content, isError: true });
+                }
+            }
+            else if (method === "ping") {
+                if (!isNotification)
+                    respond(id, {});
+            }
+            else {
+                if (!isNotification)
+                    error(id, -32601, `Method not found: ${method}`);
+            }
+        }
+        catch (e) {
+            if (!isNotification)
+                error(id, -32603, e?.message ?? String(e));
+        }
+    });
+    // keep alive
+    process.stdin.resume();
+}

package/dist/src/adapters/claude.d.ts

@@ -0,0 +1,7 @@
+import type { Quota } from "./types.js";
+export declare function parseClaudeUsage(result: string, now?: Date): Quota;
+export declare const claudeAdapter: {
+    id: string;
+    requiresAuth: string;
+    poll(): Promise<Quota>;
+};

package/dist/src/adapters/claude.js

@@ -0,0 +1,78 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { parse, isValid } from "date-fns";
+import { fromZonedTime, formatInTimeZone } from "date-fns-tz";
+const exec = promisify(execFile);
+const BRISBANE_TZ = "Australia/Brisbane";
+const RESET_FORMATS = [
+    "MMM d 'at' h:mma yyyy",
+    "MMM d 'at' ha yyyy",
+    "MMM d 'at' h:mm a yyyy",
+    "MMM d 'at' h a yyyy",
+];
+function tryParseWithYear(raw, year) {
+    const withYear = `${raw.trim()} ${year}`;
+    const normalized = withYear.replace(/([ap]m)\b/gi, (m) => m.toUpperCase());
+    for (const fmt of RESET_FORMATS) {
+        const d = parse(normalized, fmt, new Date());
+        if (isValid(d)) {
+            return fromZonedTime(d, BRISBANE_TZ);
+        }
+    }
+    return null;
+}
+function parseBrisbaneReset(resetsRaw, now) {
+    const trimmed = resetsRaw.trim();
+    if (!trimmed)
+        return null;
+    const yearStr = formatInTimeZone(now, BRISBANE_TZ, "yyyy");
+    const year = parseInt(yearStr, 10);
+    let utc = tryParseWithYear(trimmed, year);
+    if (!utc)
+        return null;
+    if (utc.getTime() < now.getTime()) {
+        const utcNext = tryParseWithYear(trimmed, year + 1);
+        if (utcNext) {
+            const diff = utcNext.getTime() - now.getTime();
+            if (diff >= 0 && diff < 8 * 86400000) {
+                utc = utcNext;
+            }
+            else {
+                // stale / out-of-range (e.g. monthly-plan string) — fallback to now+7d
+                return null;
+            }
+        }
+        else {
+            return null;
+        }
+        // if utc was past and no valid next-year within window, treat as stale
+        if (utc.getTime() < now.getTime())
+            return null;
+    }
+    return formatInTimeZone(utc, BRISBANE_TZ, "yyyy-MM-dd'T'HH:mm:ssXXX");
+}
+export function parseClaudeUsage(result, now = new Date()) {
+    const sessionMatch = result.match(/Current session:\s+(\d+)% used[^·]*·\s*resets\s+([^\n(]+?)\s*\(/);
+    const weeklyMatch = result.match(/Current week \(all models\):\s+(\d+)% used[^·]*·\s*resets\s+([^\n(]+?)\s*\(/);
+    const usedPct = weeklyMatch ? parseInt(weeklyMatch[1], 10) : 0;
+    const sessionPct = sessionMatch ? parseInt(sessionMatch[1], 10) : undefined;
+    const resetsRaw = weeklyMatch?.[2].trim() ?? "";
+    let resetsAt = parseBrisbaneReset(resetsRaw, now);
+    if (!resetsAt)
+        resetsAt = new Date(now.getTime() + 7 * 86400000).toISOString();
+    return {
+        provider: "claude", plan: "max", usedPct, sessionPct,
+        resetsAt, periodStart: new Date(now.getTime() - 7 * 86400000).toISOString(),
+        raw: result, source: "cli", fetchedAt: now.toISOString()
+    };
+}
+export const claudeAdapter = {
+    id: "claude",
+    requiresAuth: "keychain:Claude Code-credentials",
+    async poll() {
+        const { stdout } = await exec("claude", ["-p", "/usage", "--output-format", "json"], { timeout: 8000 });
+        const parsed = JSON.parse(stdout);
+        const result = parsed.result ?? stdout;
+        return parseClaudeUsage(result);
+    }
+};

package/dist/src/adapters/index.d.ts

@@ -0,0 +1,18 @@
+import type { Adapter } from "./types.js";
+export declare const adapters: Record<string, Adapter>;
+export declare function pollAll(enabled: string[]): Promise<({
+    provider: string;
+    status: "fulfilled";
+    value: import("./types.js").Quota;
+    reason?: undefined;
+} | {
+    provider: string;
+    status: "skipped";
+    reason: any;
+    value?: undefined;
+} | {
+    provider: string;
+    status: "rejected";
+    reason: any;
+    value?: undefined;
+})[]>;

package/dist/src/adapters/index.js

@@ -0,0 +1,33 @@
+import { claudeAdapter } from "./claude.js";
+import { manualAdapter } from "./manual.js";
+export const adapters = {
+    claude: claudeAdapter,
+    manual: manualAdapter,
+};
+function withTimeout(p, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`timeout after ${ms}ms`)), ms);
+        Promise.resolve(p).then((v) => { clearTimeout(timer); resolve(v); }, (e) => { clearTimeout(timer); reject(e); });
+    });
+}
+export async function pollAll(enabled) {
+    const rawJobs = enabled.map(id => {
+        const a = adapters[id];
+        if (!a)
+            return Promise.reject(new Error(`unknown adapter ${id}`));
+        // manual adapter has no poll capability — skip without degraded
+        if (id === "manual")
+            return Promise.reject(new Error("manual skipped — use ingest"));
+        return withTimeout(a.poll(), 8000);
+    });
+    const settled = await Promise.allSettled(rawJobs);
+    return settled.map((s, i) => {
+        const id = enabled[i];
+        if (s.status === "fulfilled")
+            return { provider: id, status: "fulfilled", value: s.value };
+        const msg = String(s.reason?.message ?? s.reason);
+        if (msg.includes("manual skipped"))
+            return { provider: id, status: "skipped", reason: s.reason };
+        return { provider: id, status: "rejected", reason: s.reason };
+    });
+}

package/dist/src/adapters/manual.d.ts

@@ -0,0 +1,8 @@
+import type { Quota } from "./types.js";
+export declare function parseManualUsage(provider: string, text: string, now?: Date): Quota;
+export declare const manualAdapter: {
+    id: string;
+    requiresAuth: string;
+    ingest(provider: string, text: string): Promise<Quota>;
+    poll(): Promise<Quota>;
+};

package/dist/src/adapters/manual.js

@@ -0,0 +1,25 @@
+export function parseManualUsage(provider, text, now = new Date()) {
+    const m = text.match(/(\d+)% used/);
+    const usedPct = m ? parseInt(m[1], 10) : 0;
+    const resetsAt = new Date(now.getTime() + 3 * 86400000).toISOString();
+    return {
+        provider,
+        plan: "unknown",
+        usedPct,
+        resetsAt,
+        periodStart: new Date(now.getTime() - 7 * 86400000).toISOString(),
+        raw: text,
+        source: "manual",
+        fetchedAt: now.toISOString(),
+    };
+}
+export const manualAdapter = {
+    id: "manual",
+    requiresAuth: "none",
+    async ingest(provider, text) {
+        return parseManualUsage(provider, text);
+    },
+    async poll() {
+        throw new Error("manual has no poll — use ingest");
+    },
+};

package/dist/src/adapters/types.d.ts

@@ -0,0 +1,17 @@
+export interface Quota {
+    provider: string;
+    plan: string;
+    usedPct: number;
+    sessionPct?: number;
+    resetsAt: string;
+    periodStart: string;
+    raw: string;
+    source: "cli" | "api" | "scrape" | "manual";
+    fetchedAt: string;
+}
+export interface Adapter {
+    id: string;
+    requiresAuth: string;
+    poll(): Promise<Quota>;
+}
+export declare const UNIMPLEMENTED: (id: string) => Error;

package/dist/src/adapters/types.js

@@ -0,0 +1 @@
+export const UNIMPLEMENTED = (id) => new Error(`${id} adapter not implemented — use manual-paste`);

package/dist/src/advisory/engine.d.ts

@@ -0,0 +1,11 @@
+import type { Quota } from "../adapters/types.js";
+import type { Advisory } from "./types.js";
+export declare function computeAdvisory(q: Quota, burnRate: number, now?: Date): Advisory;
+export declare function recommend(quotas: Quota[], _task: string, burnByProvider?: Map<string, number>, now?: Date): {
+    use: string;
+    reason: string;
+    wastePct: number;
+    idealRate: number;
+    alternatives: Quota[];
+    advisories: Advisory[];
+};

package/dist/src/advisory/engine.js

@@ -0,0 +1,26 @@
+export function computeAdvisory(q, burnRate, now = new Date()) {
+    const resets = new Date(q.resetsAt);
+    const daysLeft = Math.max(0.1, (resets.getTime() - now.getTime()) / 86400000);
+    const remaining = 100 - q.usedPct;
+    const idealRate = remaining / daysLeft;
+    const wastePct = Math.max(0, remaining - burnRate * daysLeft);
+    let urgency = "on track";
+    if (wastePct > 30 && daysLeft < 3)
+        urgency = "burn now";
+    else if (wastePct > 20 && daysLeft < 7)
+        urgency = "use soon";
+    else if (burnRate > idealRate * 1.4)
+        urgency = "slow down";
+    else if (wastePct > 10)
+        urgency = "save";
+    return { provider: q.provider, daysLeft, remaining, idealRate, burnRate, wastePct, urgency };
+}
+export function recommend(quotas, _task, burnByProvider = new Map(), now = new Date()) {
+    if (!quotas.length)
+        return { use: "none", reason: "no quotas yet", wastePct: 0, idealRate: 0, alternatives: [], advisories: [] };
+    const advisories = quotas.map(q => computeAdvisory(q, burnByProvider.get(q.provider) ?? 2, now));
+    const burnNow = advisories.filter(a => a.urgency === "burn now");
+    const pool = burnNow.length ? burnNow : advisories;
+    const use = pool.sort((a, b) => b.wastePct - a.wastePct)[0];
+    return { use: use.provider, reason: `${Math.round(use.wastePct)}% waste in ${use.daysLeft.toFixed(1)}d`, wastePct: use.wastePct, idealRate: use.idealRate, alternatives: quotas, advisories };
+}

package/dist/src/advisory/types.d.ts

@@ -0,0 +1,10 @@
+export type Urgency = "burn now" | "use soon" | "slow down" | "save" | "on track";
+export interface Advisory {
+    provider: string;
+    daysLeft: number;
+    remaining: number;
+    idealRate: number;
+    burnRate: number;
+    wastePct: number;
+    urgency: Urgency;
+}

package/dist/src/advisory/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli/index.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import fs from "node:fs";
+import path from "node:path";
+import { buildApp } from "../http/server.js";
+import { openDb, migrate } from "../store/db.js";
+import { getDbPath, readConfig } from "../config.js";
+function ensureDbDir() { try {
+    fs.mkdirSync(path.dirname(getDbPath()), { recursive: true });
+}
+catch { } }
+const program = new Command();
+program.name("quotacap").version("0.0.1");
+program.command("status").option("--json", "json").action(async (opts) => {
+    ensureDbDir();
+    const db = openDb(getDbPath());
+    migrate(db);
+    const { getAllLatest } = await import("../store/quotas.js");
+    const quotas = getAllLatest(db);
+    if (opts.json)
+        console.log(JSON.stringify(quotas, null, 2));
+    else
+        console.table(quotas);
+});
+program.command("advise").option("--json", "json").option("--task <t>", "task", "any").action(async (opts) => {
+    ensureDbDir();
+    const db = openDb(getDbPath());
+    migrate(db);
+    try {
+        const r = await fetch(`http://localhost:${(await readConfig()).port}/api/recommendation?task=${opts.task}`, { signal: AbortSignal.timeout(2000) });
+        const j = await r.json();
+        console.log(opts.json ? JSON.stringify(j, null, 2) : `${j.use}: ${j.reason}`);
+    }
+    catch {
+        const { recommend } = await import("../advisory/engine.js");
+        const { getAllLatest } = await import("../store/quotas.js");
+        const quotas = getAllLatest(db);
+        if (!quotas.length) {
+            console.log(opts.json ? JSON.stringify({ use: "none", reason: "no quotas yet" }, null, 2) : "none: no quotas yet");
+            return;
+        }
+        const rec = recommend(quotas, opts.task);
+        console.log(opts.json ? JSON.stringify(rec, null, 2) : `${rec.use}: ${rec.reason}`);
+    }
+});
+program.command("ingest").requiredOption("--provider <p>").requiredOption("--text <t>").action(async (o) => {
+    ensureDbDir();
+    const db = openDb(getDbPath());
+    migrate(db);
+    const { parseManualUsage } = await import("../adapters/manual.js");
+    const { upsertQuota } = await import("../store/quotas.js");
+    upsertQuota(db, parseManualUsage(o.provider, o.text));
+    console.log("ingested");
+});
+program.command("web").option("--port <n>").action(async (o) => {
+    ensureDbDir();
+    const db = openDb(getDbPath());
+    migrate(db);
+    const app = buildApp(db);
+    const port = o.port ? parseInt(o.port) : (await readConfig()).port;
+    await app.listen({ port, host: "127.0.0.1" });
+    console.log(`QuotaCap at http://localhost:${port}`);
+});
+program.command("init").action(async () => {
+    const { readConfig, writeConfig } = await import("../config.js");
+    const c = await readConfig();
+    await writeConfig(c);
+    console.log(JSON.stringify(c, null, 2));
+});
+program.command("daemon").option("--foreground", "keep foreground (default: true)").action(async (o) => {
+    const { startDaemon } = await import("../daemon.js");
+    const { timer } = await startDaemon();
+    console.log("QuotaCap daemon started" + (o.foreground !== false ? " (foreground)" : ""));
+    // keep alive until SIGINT/SIGTERM — timer is ref'd so event loop stays alive
+    process.on("SIGINT", () => { clearInterval(timer); process.exit(0); });
+    process.on("SIGTERM", () => { clearInterval(timer); process.exit(0); });
+    // explicitly keep process alive if interval was somehow unref'd elsewhere
+    if (timer.ref)
+        timer.ref();
+});
+program.command("mcp").description("start MCP server (stdio over HTTP)").action(async () => {
+    const mod = await import("../mcp/server.js");
+    // if run with --help, commander handles it before action; this is the real server
+    await mod.runMcpServer();
+});
+program.parseAsync();

package/dist/src/config.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+export declare function getConfigPath(p?: string): string;
+export declare function getDbPath(p?: string): string;
+declare const ConfigSchema: z.ZodObject<{
+    port: z.ZodDefault<z.ZodNumber>;
+    pollMinutes: z.ZodDefault<z.ZodNumber>;
+    enabledProviders: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    port: number;
+    pollMinutes: number;
+    enabledProviders: string[];
+}, {
+    port?: number | undefined;
+    pollMinutes?: number | undefined;
+    enabledProviders?: string[] | undefined;
+}>;
+export type Config = z.infer<typeof ConfigSchema>;
+export declare function readConfig(p?: string): Promise<Config>;
+export declare function writeConfig(c: Config, p?: string): Promise<void>;
+export {};