quotacap 0.0.20 → 0.0.22

package/README.md

@@ -1,6 +1,6 @@
 # QuotaCap
 
-QuotaCap helps you get more from the AI coding subscriptions you already pay for: Claude Code, Codex, Kimi Code, and Grok. It tracks one current usage window and reset time for each plan, then estimates which plan to use next from remaining usage and recent pace when available.
+QuotaCap helps you get more from the AI coding subscriptions you already pay for: Claude Code, Codex, Kimi Code, Grok, and Antigravity. It tracks one current usage window and reset time for each plan, then estimates which plan to use next from remaining usage and recent pace when available.
 
 [![npm](https://img.shields.io/npm/v/quotacap)](https://www.npmjs.com/package/quotacap)
 [![CI](https://github.com/carlosboeing/quotacap/actions/workflows/test.yml/badge.svg)](https://github.com/carlosboeing/quotacap/actions)
@@ -16,15 +16,17 @@ QuotaCap helps you get more from the AI coding subscriptions you already pay for
 
 ## Providers
 
-| Provider | Source |
-|---|---|
-| Claude Code | Live |
-| Codex | Live |
-| Kimi Code | Live |
-| Grok | Live |
-| Antigravity / Gemini | Manual (`quotacap ingest`) |
+| Provider | Mechanism | Source |
+|---|---|---|
+| Claude Code | `exec` — `claude -p /usage --output-format json` | Live |
+| Antigravity | `exec` — `agy -p /usage --output-format json` (two rows: `agy` Gemini, `agy:3p` 3p) | Live |
+| Codex | `pty` — `codex --no-alt-screen` then `/status`, parse `Weekly/5h limit: X% left` | Live |
+| Kimi Code | `pty` — `kimi` then `/usage`, parse `Weekly/5h limit: Y% used` | Live |
+| Grok | `pty` — `grok` then `/usage`, parse `Weekly limit (plan)` + `Credits: $X` | Live |
 
-Live adapters reuse the matching CLI login.
+Exec adapters run via `execFile` with an argv list. PTY adapters run via `node-pty` (`src/adapters/pty.ts`). They are TUI-fragile: a vendor text change breaks the parser and the row degrades fail-closed until the regex is fixed. Poll latency is 2–10 s per PTY provider (settle plus completion). It dominates `POST /api/refresh` and the first poll, not the steady-state 15 m timer.
+
+Live adapters invoke the CLIs you already logged into. No API keys. No token files are read.
 
 ## Install
 
@@ -36,7 +38,7 @@ curl -fsSL https://raw.githubusercontent.com/carlosboeing/quotacap/main/install.
 npm install -g quotacap
 ```
 
-The binary is a self-contained executable from GitHub Releases.
+The binary is a self-contained executable from GitHub Releases (shipped as `quotacap-<os>-<arch>.tar.gz` with a `pty` sidecar for Kimi/Codex/Grok); `install.sh` handles the tarball and sidecar transparently.
 The npm package runs the same CLI on Node. To run without a global install, replace `quotacap` with `npx quotacap` in any command, for example `npx quotacap web`.
 
 ## Quick start
@@ -53,12 +55,6 @@ quotacap advise
 
 `web` stays in the foreground and starts the daemon.
 
-For a provider without a live adapter:
-
-```bash
-quotacap ingest --provider agy --text "65% used · resets Sep 1"
-```
-
 ## MCP
 
 ```json
@@ -73,15 +69,51 @@ Use `"command": "npx", "args": ["quotacap", "mcp"]` when installed via npm only.
 
 Tools: `get_quotas`, `get_recommendation`, `forecast`.
 
-## Privacy
+## HTTP API
+
+The local web server listens on `127.0.0.1:8787` (configured via `QUOTACAP_URL` or `~/.quotacap/config.json`). All endpoints enforce loopback `Host` (`127.0.0.1`, `localhost`, `[::1]`) and reject foreign `Origin` headers (403) to prevent DNS rebinding and cross-origin requests.
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `GET` | `/health` | None | Health check and uptime |
+| `GET` | `/api/quotas` | None | Current quotas for all providers |
+| `GET` | `/api/recommendation` | None | Current advisory on which provider to use next |
+| `GET` | `/api/token` | Same-origin | Shared secret token for the dashboard |
+| `POST` | `/api/refresh` | `X-QuotaCap-Token` | Trigger an immediate adapter poll (debounced to 60s) |
+
+### Curl examples
+
+Read current quotas:
+
+```bash
+curl http://localhost:8787/api/quotas
+```
+
+Trigger an immediate refresh (requires the shared secret in `~/.quotacap/token` with mode `0600`):
+
+```bash
+curl -X POST http://localhost:8787/api/refresh \
+  -H "X-QuotaCap-Token: $(cat ~/.quotacap/token)"
+```
+
+## Security
+
+QuotaCap is a local daemon. It binds to `127.0.0.1` only (`src/cli/index.ts:56`). It does not listen on `0.0.0.0`. There is no LAN surface.
 
-Bound to `127.0.0.1`, with usage history stored under `~/.quotacap/`. Live adapters contact provider usage endpoints or invoke the provider CLI using your existing login. Codex, Kimi, and Grok adapters may refresh expired OAuth tokens and update the CLI-owned credential file. QuotaCap stores no API keys.
+It owns no tokens. It never reads `~/.codex/auth.json`, `~/.kimi-code/credentials/kimi-code.json`, `~/.kimi/credentials/kimi-code.json`, `~/.grok/auth.json`, or `~/.gemini/oauth_creds.json`. It never uses `refresh_token` or `grant_type=refresh_token`. It has no hardcoded client ids. Those OAuth paths and the `.qc-bak` and `.qc-lock` helpers were removed in #14. This is asserted by `tests/adapters/credential-free.test.ts`. Each CLI owns its own session. QuotaCap only spawns the CLI and reads its stdout via `exec` (`claude`, `agy`) or PTY (`codex`, `kimi`, `grok`).
+
+It stores no `raw` provider payload. The `raw` column was dropped and migrated in `src/store/db.ts:37-48`. `GET /api/quotas` and MCP `get_quotas` never return `raw` (`tests/http/api.test.ts`). History and the token live under `~/.quotacap/` with `0700` on the directory and `0600` on files.
+
+Every request checks `Host` and `Origin`. `Host` must be loopback (`127.0.0.1`, `localhost`, `[::1]`), otherwise `403`. `Origin` when present must be loopback, otherwise `403`. Absent `Origin` passes for `curl` and MCP. `POST /api/refresh` requires `X-QuotaCap-Token` matching `~/.quotacap/token` with `crypto.timingSafeEqual` (`src/http/server.ts:isValidToken`), otherwise `401`. `GET /assets/*` is rooted with `path.resolve` and a prefix check (`tests/http/api.test.ts`).
+
+Adapters fail closed. A timeout or unmatched TUI text becomes a stale row, never `0% used`. See `SECURITY.md` for the full "does and does not touch" list and how to report a vulnerability. See `docs/architecture.md` for the detailed security model.
 
 ## Docs
 
 - [Architecture](docs/architecture.md)
 - [Changelog](docs/CHANGELOG.md)
 - [Roadmap](docs/ROADMAP.md)
+- [Security](SECURITY.md)
 
 ## License
 
@@ -100,4 +132,13 @@ npm run build:bin
 The store uses `node:sqlite` on Node and `bun:sqlite` on Bun.
 The same code is an npm package and a compiled binary.
 
+`node-pty` is a native addon for the PTY-based adapters (Kimi, Codex, Grok) and is an `optionalDependency`. Prebuilt binaries are provided where available (macOS and Linux). If no prebuild matches your Node version or platform, `npm install` compiles it from source — this requires Xcode (macOS) or `build-essential` + `python3` (Linux). If the compile fails the install still succeeds and exec-based adapters (Claude, Agy) continue to work; PTY adapters will report `node-pty not available` until you install the toolchain and run `npm rebuild node-pty`.
+
+The Kimi adapter spawns `kimi` in your home directory so the quota modal does not depend on the project path. If Kimi shows `Trust this folder?`, QuotaCap fails closed with `untrusted workspace — run \`kimi\` there and select Trust this folder` and does not auto-trust; trust remains an explicit interactive decision.
+
+The compiled binaries are built with `bun build --compile`.
+Each `dist-bin/quotacap-<os>-<arch>.tar.gz` bundles a `pty` sidecar.
+The sidecar is `pty/node-pty` with the matching prebuild.
+`install.sh` verifies the tarball and installs the sidecar to `~/.local/bin/pty` and `~/.local/share/quotacap/pty`.
+
 </details>

package/dist/adapters/agy.d.ts

@@ -0,0 +1,3 @@
+import type { Adapter, ParsedQuota } from "./types.js";
+export declare function parseAgyUsage(parsedJson: any, now?: Date): ParsedQuota[];
+export declare const agyAdapter: Adapter;

package/dist/adapters/agy.js

@@ -0,0 +1,81 @@
+import { trackedExecFile } from "../runtime/spawn.js";
+function usedPctFromRemaining(remaining) {
+    if (typeof remaining !== "number" || !Number.isFinite(remaining))
+        return null;
+    const pct = Math.round((1 - remaining) * 100);
+    if (!Number.isFinite(pct) || pct < 0 || pct > 100)
+        return null;
+    return pct;
+}
+function parseGroup(g, provider, rawJsonString, now) {
+    if (!Array.isArray(g.buckets))
+        return null;
+    const weekly = g.buckets.find((b) => b.window === "weekly");
+    if (!weekly)
+        return null;
+    const usedPct = usedPctFromRemaining(weekly.remaining_fraction);
+    if (usedPct === null)
+        return null;
+    const rawReset = weekly.reset_time;
+    const resetDate = rawReset ? new Date(rawReset) : null;
+    if (!resetDate || Number.isNaN(resetDate.getTime()))
+        throw new Error("agy: bad weekly reset_time");
+    const resetsAt = resetDate.toISOString();
+    const periodStart = new Date(resetDate.getTime() - 7 * 86400000).toISOString();
+    const fiveHour = g.buckets.find((b) => b.window === "5h");
+    const sessionPct = fiveHour
+        ? usedPctFromRemaining(fiveHour.remaining_fraction) ?? undefined
+        : undefined;
+    return {
+        provider,
+        plan: "unknown",
+        usedPct,
+        sessionPct,
+        resetsAt,
+        periodStart,
+        source: "cli",
+        fetchedAt: now.toISOString(),
+        raw: rawJsonString,
+    };
+}
+export function parseAgyUsage(parsedJson, now = new Date()) {
+    if (parsedJson?.status !== "SUCCESS")
+        throw new Error("agy: status is not SUCCESS");
+    const groups = parsedJson?.command?.data?.groups;
+    if (!Array.isArray(groups))
+        throw new Error("agy: no usage groups");
+    const raw = JSON.stringify(parsedJson);
+    const rows = [];
+    const geminiGroup = groups.find((g) => /gemini/i.test(g.name ?? "") || g.buckets?.some((b) => b.id?.startsWith("gemini")));
+    if (geminiGroup) {
+        const q = parseGroup(geminiGroup, "agy", raw, now);
+        if (q)
+            rows.push(q);
+    }
+    const threePGroup = groups.find((g) => /claude|gpt|3p/i.test(g.name ?? "") || g.buckets?.some((b) => b.id?.startsWith("3p")));
+    if (threePGroup) {
+        const q = parseGroup(threePGroup, "agy:3p", raw, now);
+        if (q)
+            rows.push(q);
+    }
+    if (rows.length === 0) {
+        for (const g of groups) {
+            const q = parseGroup(g, "agy", raw, now);
+            if (q) {
+                rows.push(q);
+                break;
+            }
+        }
+    }
+    if (rows.length === 0)
+        throw new Error("agy: no weekly bucket");
+    return rows;
+}
+export const agyAdapter = {
+    id: "agy",
+    requiresAuth: "agy login (CLI owns credentials)",
+    async poll() {
+        const { stdout } = await trackedExecFile("agy", "agy", ["-p", "/usage", "--output-format", "json"], { timeout: 20000 });
+        return parseAgyUsage(JSON.parse(stdout));
+    },
+};

package/dist/adapters/claude.d.ts

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

package/dist/adapters/claude.js

@@ -1,7 +1,5 @@
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
+import { trackedExecFile } from "../runtime/spawn.js";
 import { parseResetText } from "./parse.js";
-const exec = promisify(execFile);
 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*\(/);
@@ -15,14 +13,16 @@ export function parseClaudeUsage(result, now = new Date()) {
     const periodStart = (parsedReset ? new Date(resets - 7 * 86400000) : new Date(now.getTime() - 7 * 86400000)).toISOString();
     return {
         provider: "claude", plan: "max", usedPct, sessionPct,
-        resetsAt, periodStart, raw: result, source: "cli", fetchedAt: now.toISOString()
+        resetsAt, periodStart, source: "cli", fetchedAt: now.toISOString(), raw: result,
     };
 }
 export const claudeAdapter = {
     id: "claude",
     requiresAuth: "keychain:Claude Code-credentials",
-    async poll() {
-        const { stdout } = await exec("claude", ["-p", "/usage", "--output-format", "json"], { timeout: 8000 });
+    execPath: "claude",
+    async poll(execPath) {
+        const bin = execPath ?? claudeAdapter.execPath ?? "claude";
+        const { stdout } = await trackedExecFile("claude", bin, ["-p", "/usage", "--output-format", "json"], { timeout: 8000 });
         const parsed = JSON.parse(stdout);
         const result = parsed.result ?? stdout;
         return parseClaudeUsage(result);

package/dist/adapters/codex.d.ts

@@ -1,7 +1,7 @@
-import type { Quota } from "./types.js";
-export declare function parseCodexUsage(body: any, now?: Date): Quota;
+import type { ParsedQuota } from "./types.js";
+export declare function parseCodexTui(text: string, now?: Date): ParsedQuota;
 export declare const codexAdapter: {
     id: string;
     requiresAuth: string;
-    poll(): Promise<Quota>;
+    poll(): Promise<ParsedQuota>;
 };

package/dist/adapters/codex.js

@@ -1,61 +1,140 @@
 import os from "node:os";
-import path from "node:path";
-import { readJsonFile, getJson, postForm, persistCreds } from "./core.js";
-export function parseCodexUsage(body, now = new Date()) {
-    const rl = body?.rate_limit ?? {};
-    const win = rl.secondary_window ?? rl.primary_window;
-    if (!win)
-        throw new Error("codex: no rate-limit window in response");
-    const resetsAt = new Date(win.reset_at * 1000).toISOString();
-    const periodStart = new Date((win.reset_at - win.limit_window_seconds) * 1000).toISOString();
+import { runPty, stripAnsi } from "./pty.js";
+import { adapterSignal } from "../runtime/spawn.js";
+const MONTHS = {
+    jan: 0, feb: 1, mar: 2, apr: 3, may: 4, jun: 5,
+    jul: 6, aug: 7, sep: 8, oct: 9, nov: 10, dec: 11,
+};
+function parseWeeklyReset(raw, now) {
+    const m = raw.trim().match(/^(\d{1,2}):(\d{2})\s+on\s+(\d{1,2})\s+([A-Za-z]{3,9})$/);
+    if (!m)
+        return null;
+    const hours = parseInt(m[1], 10);
+    const mins = parseInt(m[2], 10);
+    const day = parseInt(m[3], 10);
+    const monStr = m[4].slice(0, 3).toLowerCase();
+    const month = MONTHS[monStr];
+    if (month === undefined || !Number.isFinite(hours) || !Number.isFinite(mins) || !Number.isFinite(day))
+        return null;
+    if (hours < 0 || hours > 23 || mins < 0 || mins > 59 || day < 1 || day > 31)
+        return null;
+    let year = now.getFullYear();
+    let dt = new Date(year, month, day, hours, mins, 0, 0);
+    if (Number.isNaN(dt.getTime()))
+        return null;
+    if (dt.getTime() < now.getTime()) {
+        dt = new Date(year + 1, month, day, hours, mins, 0, 0);
+        if (Number.isNaN(dt.getTime()))
+            return null;
+    }
+    if (dt.getTime() < now.getTime())
+        return null;
+    return dt.toISOString();
+}
+function parseFiveReset(raw, now) {
+    const m = raw.trim().match(/^(\d{1,2}):(\d{2})$/);
+    if (!m)
+        return null;
+    const hours = parseInt(m[1], 10);
+    const mins = parseInt(m[2], 10);
+    if (hours < 0 || hours > 23 || mins < 0 || mins > 59)
+        return null;
+    let dt = new Date(now.getFullYear(), now.getMonth(), now.getDate(), hours, mins, 0, 0);
+    if (dt.getTime() < now.getTime()) {
+        dt = new Date(dt.getTime() + 86400000);
+    }
+    return dt.toISOString();
+}
+export function parseCodexTui(text, now = new Date()) {
+    const cleaned = stripAnsi(text);
+    let weeklyLeft = null;
+    let fiveLeft = null;
+    let weeklyRaw = null;
+    let fiveRaw = null;
+    const weeklyRe = /Weekly limit:\s*(\d+)%\s*left\s*\(resets\s+([^)]+)\)/i;
+    const fiveRe = /5h limit:\s*(\d+)%\s*left\s*\(resets\s+([^)]+)\)/i;
+    const w = cleaned.match(weeklyRe);
+    const f = cleaned.match(fiveRe);
+    if (w) {
+        weeklyLeft = parseInt(w[1], 10);
+        weeklyRaw = w[2].trim();
+    }
+    if (f) {
+        fiveLeft = parseInt(f[1], 10);
+        fiveRaw = f[2].trim();
+    }
+    if (weeklyLeft === null) {
+        const m = cleaned.match(/weekly[^\d%]*(\d+)%\s*left/i);
+        if (m)
+            weeklyLeft = parseInt(m[1], 10);
+    }
+    if (fiveLeft === null) {
+        const m = cleaned.match(/5h[^\d%]*(\d+)%\s*left/i);
+        if (m)
+            fiveLeft = parseInt(m[1], 10);
+    }
+    if (weeklyLeft === null)
+        throw new Error("codex: weekly limit not found in TUI output");
+    if (fiveLeft === null)
+        throw new Error("codex: 5h limit not found in TUI output");
+    if (!Number.isFinite(weeklyLeft) || weeklyLeft < 0 || weeklyLeft > 100)
+        throw new Error("codex: bad weekly pct");
+    if (!Number.isFinite(fiveLeft) || fiveLeft < 0 || fiveLeft > 100)
+        throw new Error("codex: bad 5h pct");
+    let weeklyIso = null;
+    let fiveIso = null;
+    let estimated = false;
+    if (weeklyRaw) {
+        weeklyIso = parseWeeklyReset(weeklyRaw, now);
+        if (!weeklyIso)
+            throw new Error(`codex: bad weekly reset "${weeklyRaw}"`);
+    }
+    if (fiveRaw) {
+        fiveIso = parseFiveReset(fiveRaw, now);
+        if (!fiveIso)
+            throw new Error(`codex: bad 5h reset "${fiveRaw}"`);
+    }
+    if (!weeklyIso) {
+        weeklyIso = new Date(now.getTime() + 7 * 86400000).toISOString();
+        estimated = true;
+    }
+    if (!fiveIso)
+        fiveIso = new Date(now.getTime() + 5 * 3600000).toISOString();
+    const usedPct = 100 - weeklyLeft;
+    const sessionPct = 100 - fiveLeft;
+    const periodStart = new Date(new Date(weeklyIso).getTime() - 7 * 86400000).toISOString();
     return {
         provider: "codex",
-        plan: body.plan_type ?? "unknown",
-        usedPct: win.used_percent ?? 0,
-        resetsAt,
+        plan: "unknown",
+        usedPct,
+        sessionPct,
+        resetsAt: weeklyIso,
         periodStart,
-        raw: JSON.stringify(body),
-        source: "api",
+        source: "tui",
         fetchedAt: now.toISOString(),
+        resetsAtEstimated: estimated || undefined,
+        raw: cleaned.slice(0, 4096),
     };
 }
-const USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
-const REFRESH_URL = "https://auth.openai.com/oauth/token";
-const CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
-function codexHome() {
-    return process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex");
-}
 export const codexAdapter = {
     id: "codex",
-    requiresAuth: "~/.codex/auth.json (codex login)",
+    requiresAuth: "codex login (CLI owns credentials)",
     async poll() {
-        const authFile = path.join(codexHome(), "auth.json");
-        const auth = await readJsonFile(authFile);
-        const at = auth.tokens?.access_token;
-        if (!at)
-            throw new Error("codex: no access_token in auth.json — run codex login");
-        const headers = { Authorization: `Bearer ${at}`, "User-Agent": "quotacap" };
-        if (auth.tokens?.account_id)
-            headers["ChatGPT-Account-Id"] = auth.tokens.account_id;
-        try {
-            return parseCodexUsage(await getJson(USAGE_URL, headers));
-        }
-        catch (e) {
-            if (e.status !== 401)
-                throw e;
-            const rf = auth.tokens?.refresh_token;
-            if (!rf)
-                throw e;
-            const tok = await postForm(REFRESH_URL, { grant_type: "refresh_token", client_id: CLIENT_ID, refresh_token: rf });
-            await persistCreds(authFile, (cur) => {
-                const tokens = { ...(cur.tokens ?? {}), };
-                if (tok.access_token)
-                    tokens.access_token = tok.access_token;
-                if (tok.refresh_token)
-                    tokens.refresh_token = tok.refresh_token;
-                return { ...cur, tokens, last_refresh: new Date().toISOString() };
-            });
-            return parseCodexUsage(await getJson(USAGE_URL, { ...headers, Authorization: `Bearer ${tok.access_token}` }));
-        }
+        const transcript = await runPty({
+            file: "codex",
+            args: ["--no-alt-screen"],
+            cwd: os.homedir(),
+            cols: 140,
+            rows: 50,
+            settleDelayMs: 2000,
+            input: "/status\r",
+            completionRegex: /\d+%\s*left/i,
+            abortOn: /Do you trust|Trust.*folder|trust the files in this folder/i,
+            timeoutMs: 12000,
+            maxBytes: 256 * 1024,
+            signal: adapterSignal("codex"),
+            label: "codex",
+        });
+        return parseCodexTui(transcript);
     },
 };

package/dist/adapters/grok.d.ts

@@ -1,7 +1,7 @@
-import type { Quota } from "./types.js";
-export declare function parseGrokUsage(body: any, now?: Date): Quota;
+import type { ParsedQuota } from "./types.js";
+export declare function parseGrokTui(text: string, now?: Date): ParsedQuota;
 export declare const grokAdapter: {
     id: string;
     requiresAuth: string;
-    poll(): Promise<Quota>;
+    poll(): Promise<ParsedQuota>;
 };