quotacap 0.0.19 → 0.0.22

package/dist/adapters/pty.js

@@ -0,0 +1,487 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { registerTrackedChild } from "../runtime/spawn.js";
+export function stripAnsi(s) {
+    return s
+        .replace(/\x1b\[[^A-Za-z]*[A-Za-z]/g, "")
+        .replace(/\x1b\][^\x07]*\x07/g, "")
+        .replace(/\x1b\][^\x1b]*\x1b\\/g, "")
+        .replace(/\x1b\([A-B0-2]/g, "")
+        .replace(/\x1b[=>]|\x1b7|\x1b8|\x1bD|\x1bM/g, "");
+}
+function delay(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+function regexTest(re, s) {
+    const fresh = new RegExp(re.source, re.flags.replace("g", ""));
+    return fresh.test(s);
+}
+let ptyMod = null;
+function getPty() {
+    if (ptyMod)
+        return ptyMod;
+    try {
+        const require = createRequire(import.meta.url);
+        ptyMod = require("node-pty");
+        if (ptyMod?.spawn)
+            return ptyMod;
+    }
+    catch { }
+    // Compiled binary (bun --compile) has no node_modules; try sidecar locations
+    const execDir = path.dirname(process.execPath);
+    const platformArch = `${process.platform}-${process.arch}`;
+    const candidates = [
+        path.join(execDir, "pty", "node-pty"),
+        path.join(execDir, "node-pty"),
+        path.join(execDir, "..", "share", "quotacap", "pty", "node-pty"),
+        path.join(os.homedir(), ".local", "share", "quotacap", "pty", "node-pty"),
+        path.join(os.homedir(), ".local", "share", "quotacap", "pty", platformArch, "node-pty"),
+        path.join(os.homedir(), ".quotacap", "pty", "node-pty"),
+    ];
+    for (const c of candidates) {
+        try {
+            if (!fs.existsSync(c))
+                continue;
+            const require2 = createRequire(import.meta.url);
+            const mod = require2(c);
+            if (mod?.spawn) {
+                ptyMod = mod;
+                return ptyMod;
+            }
+        }
+        catch { }
+        try {
+            const libIndex = path.join(c, "lib", "index.js");
+            if (!fs.existsSync(libIndex))
+                continue;
+            const require3 = createRequire(import.meta.url);
+            const mod = require3(libIndex);
+            if (mod?.spawn) {
+                ptyMod = mod;
+                return ptyMod;
+            }
+        }
+        catch { }
+    }
+    throw new Error("pty: node-pty not available — install with build tools (Xcode on macOS, build-essential + python3 on Linux) or use exec-based adapters only; for compiled binaries, ensure the pty sidecar is installed alongside the binary (see install.sh)");
+}
+function isBunRuntime() {
+    return typeof globalThis.Bun !== "undefined" && typeof globalThis.Bun.spawn === "function";
+}
+async function runPtyBun(opts) {
+    const maxBytes = opts.maxBytes ?? 256 * 1024;
+    const cols = opts.cols ?? 140;
+    const rows = opts.rows ?? 50;
+    const readyTimeoutMs = opts.readyTimeoutMs ?? 6000;
+    if (opts.timeoutMs <= 0)
+        throw new Error("pty: timeoutMs must be > 0");
+    if (opts.signal?.aborted)
+        throw new Error("pty aborted");
+    let aborted = false;
+    const onAbort = () => {
+        aborted = true;
+    };
+    if (opts.signal)
+        opts.signal.addEventListener("abort", onAbort, { once: true });
+    const checkAborted = () => {
+        if (aborted)
+            throw new Error("pty aborted");
+    };
+    const teardownAbort = () => {
+        if (opts.signal)
+            opts.signal.removeEventListener("abort", onAbort);
+    };
+    const BunGlobal = globalThis.Bun;
+    let transcript = "";
+    let exited = false;
+    let exitCode;
+    const proc = BunGlobal.spawn([opts.file, ...(opts.args ?? [])], {
+        cwd: opts.cwd ?? process.cwd(),
+        env: {
+            ...process.env,
+            ...(opts.env ?? {}),
+            TERM: "xterm-256color",
+        },
+        stdin: "pipe",
+        pty: { cols, rows },
+    });
+    // Capture stdout (pty merges stdout+stderr)
+    const decoder = new TextDecoder();
+    const reader = proc.stdout.getReader();
+    let reading = true;
+    const readLoop = (async () => {
+        try {
+            while (reading) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                if (value)
+                    transcript += decoder.decode(value);
+            }
+        }
+        catch { }
+    })();
+    // Poll for exit
+    const exitPoll = (async () => {
+        try {
+            const code = await proc.exited;
+            exited = true;
+            exitCode = code;
+        }
+        catch { }
+    })();
+    const checkCap = () => {
+        if (Buffer.byteLength(transcript, "utf8") > maxBytes) {
+            throw new Error(`pty transcript exceeds ${maxBytes} bytes`);
+        }
+    };
+    const checkAbort = (clean) => {
+        if (opts.abortOn && regexTest(opts.abortOn, clean)) {
+            throw new Error(`pty: untrusted workspace — trust prompt detected in ${opts.cwd ?? process.cwd()} — run \`${opts.file}\` there and select Trust this folder`);
+        }
+    };
+    const kill = async () => {
+        if (exited)
+            return;
+        try {
+            proc.kill();
+        }
+        catch { }
+        for (let i = 0; i < 6; i++) {
+            await delay(100);
+            if (exited)
+                return;
+        }
+        try {
+            proc.kill(9);
+        }
+        catch { }
+        for (let i = 0; i < 5; i++) {
+            await delay(100);
+            if (exited)
+                return;
+        }
+    };
+    const unregisterChild = registerTrackedChild(() => {
+        try {
+            proc.kill();
+        }
+        catch { }
+    }, opts.label ?? opts.file);
+    try {
+        if (opts.readyRegex) {
+            const deadline = Date.now() + readyTimeoutMs;
+            let matched = false;
+            while (Date.now() < deadline) {
+                checkCap();
+                checkAborted();
+                if (exited)
+                    throw new Error(`pty exited before ready (code ${exitCode})`);
+                const clean = stripAnsi(transcript);
+                checkAbort(clean);
+                if (regexTest(opts.readyRegex, clean)) {
+                    matched = true;
+                    break;
+                }
+                await delay(40);
+            }
+            if (!matched) {
+                await kill();
+                throw new Error(`pty ready timeout after ${readyTimeoutMs}ms`);
+            }
+            await delay(200);
+            checkCap();
+            checkAborted();
+            if (exited)
+                throw new Error(`pty exited before input (code ${exitCode})`);
+            const postReadyClean = stripAnsi(transcript);
+            checkAbort(postReadyClean);
+        }
+        else if (opts.settleDelayMs) {
+            await delay(opts.settleDelayMs);
+            checkCap();
+            checkAborted();
+            if (exited)
+                throw new Error(`pty exited during settle (code ${exitCode})`);
+            const c = stripAnsi(transcript);
+            checkAbort(c);
+        }
+        if (exited)
+            throw new Error(`pty exited before input (code ${exitCode})`);
+        try {
+            proc.stdin.write(opts.input);
+            if (typeof proc.stdin.flush === "function")
+                proc.stdin.flush();
+        }
+        catch (e) {
+            throw new Error(`pty write failed: ${e.message}`);
+        }
+        if (opts.completionRegex) {
+            const deadline = Date.now() + opts.timeoutMs;
+            let done = false;
+            while (Date.now() < deadline) {
+                checkCap();
+                checkAborted();
+                const clean = stripAnsi(transcript);
+                checkAbort(clean);
+                if (regexTest(opts.completionRegex, clean)) {
+                    done = true;
+                    break;
+                }
+                if (exited) {
+                    if (!regexTest(opts.completionRegex, clean)) {
+                        throw new Error(`pty exited before completion (code ${exitCode})`);
+                    }
+                    done = true;
+                    break;
+                }
+                await delay(40);
+            }
+            if (!done) {
+                await kill();
+                throw new Error(`pty completion timeout after ${opts.timeoutMs}ms`);
+            }
+        }
+        else {
+            const deadline = Date.now() + opts.timeoutMs;
+            while (Date.now() < deadline) {
+                checkCap();
+                checkAborted();
+                const c = stripAnsi(transcript);
+                checkAbort(c);
+                if (exited)
+                    break;
+                await delay(40);
+            }
+        }
+        await kill();
+        reading = false;
+        try {
+            reader.cancel();
+        }
+        catch { }
+        await Promise.race([readLoop, delay(200)]);
+        checkCap();
+        checkAborted();
+        const finalClean = stripAnsi(transcript);
+        checkAbort(finalClean);
+        unregisterChild();
+        teardownAbort();
+        return transcript;
+    }
+    catch (e) {
+        reading = false;
+        try {
+            reader.cancel();
+        }
+        catch { }
+        await kill();
+        unregisterChild();
+        teardownAbort();
+        throw e;
+    }
+}
+async function runPtyNode(opts) {
+    const maxBytes = opts.maxBytes ?? 256 * 1024;
+    const cols = opts.cols ?? 140;
+    const rows = opts.rows ?? 50;
+    const readyTimeoutMs = opts.readyTimeoutMs ?? 6000;
+    if (opts.timeoutMs <= 0)
+        throw new Error("pty: timeoutMs must be > 0");
+    if (opts.signal?.aborted)
+        throw new Error("pty aborted");
+    let aborted = false;
+    const onAbort = () => {
+        aborted = true;
+    };
+    if (opts.signal)
+        opts.signal.addEventListener("abort", onAbort, { once: true });
+    const checkAborted = () => {
+        if (aborted)
+            throw new Error("pty aborted");
+    };
+    const teardownAbort = () => {
+        if (opts.signal)
+            opts.signal.removeEventListener("abort", onAbort);
+    };
+    let transcript = "";
+    let exited = false;
+    let exitCode;
+    const pty = getPty();
+    let ptyProcess;
+    try {
+        ptyProcess = pty.spawn(opts.file, opts.args ?? [], {
+            name: "xterm-color",
+            cols,
+            rows,
+            cwd: opts.cwd ?? process.cwd(),
+            env: {
+                ...process.env,
+                ...(opts.env ?? {}),
+                TERM: "xterm-256color",
+            },
+        });
+    }
+    catch (e) {
+        throw new Error(`pty spawn failed for ${opts.file}: ${e.message}`);
+    }
+    const unregisterChild = registerTrackedChild(() => {
+        try {
+            ptyProcess.kill("SIGTERM");
+        }
+        catch { }
+    }, opts.label ?? opts.file);
+    const disposables = [];
+    disposables.push(ptyProcess.onData((data) => {
+        transcript += data;
+    }));
+    disposables.push(ptyProcess.onExit(({ exitCode: c }) => {
+        exited = true;
+        exitCode = c;
+    }));
+    const cleanup = () => {
+        for (const d of disposables) {
+            try {
+                d.dispose();
+            }
+            catch { }
+        }
+    };
+    const kill = async () => {
+        if (exited)
+            return;
+        try {
+            ptyProcess.kill("SIGINT");
+        }
+        catch { }
+        for (let i = 0; i < 6; i++) {
+            await delay(100);
+            if (exited)
+                return;
+        }
+        try {
+            ptyProcess.kill("SIGKILL");
+        }
+        catch { }
+        for (let i = 0; i < 5; i++) {
+            await delay(100);
+            if (exited)
+                return;
+        }
+    };
+    const checkCap = () => {
+        if (Buffer.byteLength(transcript, "utf8") > maxBytes) {
+            throw new Error(`pty transcript exceeds ${maxBytes} bytes`);
+        }
+    };
+    const checkAbort = (clean) => {
+        if (opts.abortOn && regexTest(opts.abortOn, clean)) {
+            throw new Error(`pty: untrusted workspace — trust prompt detected in ${opts.cwd ?? process.cwd()} — run \`${opts.file}\` there and select Trust this folder`);
+        }
+    };
+    try {
+        if (opts.readyRegex) {
+            const deadline = Date.now() + readyTimeoutMs;
+            let matched = false;
+            while (Date.now() < deadline) {
+                checkCap();
+                checkAborted();
+                if (exited)
+                    throw new Error(`pty exited before ready (code ${exitCode})`);
+                const clean = stripAnsi(transcript);
+                checkAbort(clean);
+                if (regexTest(opts.readyRegex, clean)) {
+                    matched = true;
+                    break;
+                }
+                await delay(40);
+            }
+            if (!matched) {
+                await kill();
+                throw new Error(`pty ready timeout after ${readyTimeoutMs}ms`);
+            }
+            await delay(200);
+            checkCap();
+            checkAborted();
+            if (exited)
+                throw new Error(`pty exited before input (code ${exitCode})`);
+            const postReadyClean = stripAnsi(transcript);
+            checkAbort(postReadyClean);
+        }
+        else if (opts.settleDelayMs) {
+            await delay(opts.settleDelayMs);
+            checkCap();
+            checkAborted();
+            if (exited)
+                throw new Error(`pty exited during settle (code ${exitCode})`);
+            const c = stripAnsi(transcript);
+            checkAbort(c);
+        }
+        if (exited)
+            throw new Error(`pty exited before input (code ${exitCode})`);
+        ptyProcess.write(opts.input);
+        if (opts.completionRegex) {
+            const deadline = Date.now() + opts.timeoutMs;
+            let done = false;
+            while (Date.now() < deadline) {
+                checkCap();
+                checkAborted();
+                const clean = stripAnsi(transcript);
+                checkAbort(clean);
+                if (regexTest(opts.completionRegex, clean)) {
+                    done = true;
+                    break;
+                }
+                if (exited) {
+                    if (!regexTest(opts.completionRegex, clean)) {
+                        throw new Error(`pty exited before completion (code ${exitCode})`);
+                    }
+                    done = true;
+                    break;
+                }
+                await delay(40);
+            }
+            if (!done) {
+                await kill();
+                throw new Error(`pty completion timeout after ${opts.timeoutMs}ms`);
+            }
+        }
+        else {
+            const deadline = Date.now() + opts.timeoutMs;
+            while (Date.now() < deadline) {
+                checkCap();
+                checkAborted();
+                const c = stripAnsi(transcript);
+                checkAbort(c);
+                if (exited)
+                    break;
+                await delay(40);
+            }
+        }
+        await kill();
+        checkCap();
+        checkAborted();
+        const finalClean = stripAnsi(transcript);
+        checkAbort(finalClean);
+        unregisterChild();
+        teardownAbort();
+        return transcript;
+    }
+    catch (e) {
+        await kill();
+        throw e;
+    }
+    finally {
+        cleanup();
+        unregisterChild();
+        teardownAbort();
+    }
+}
+export async function runPty(opts) {
+    if (isBunRuntime()) {
+        return runPtyBun(opts);
+    }
+    return runPtyNode(opts);
+}

package/dist/adapters/types.d.ts

@@ -5,13 +5,17 @@ export interface Quota {
     sessionPct?: number;
     resetsAt: string;
     periodStart: string;
-    raw: string;
-    source: "cli" | "api" | "scrape" | "manual";
+    source: "cli" | "api" | "scrape" | "manual" | "tui";
     fetchedAt: string;
+    creditsUsd?: number;
+    resetsAtEstimated?: boolean;
+}
+export interface ParsedQuota extends Quota {
+    raw?: string;
 }
 export interface Adapter {
     id: string;
     requiresAuth: string;
-    poll(): Promise<Quota>;
+    poll(): Promise<ParsedQuota | ParsedQuota[]>;
 }
 export declare const UNIMPLEMENTED: (id: string) => Error;

package/dist/advisory/engine.d.ts

@@ -1,11 +1,28 @@
 import type { Quota } from "../adapters/types.js";
-import type { Advisory } from "./types.js";
-export declare function computeAdvisory(q: Quota, burnRate: number, now?: Date, burnMeasured?: boolean): Advisory;
+import type { Advisory, PaceSource, RecommendationBasis } from "./types.js";
+/**
+ * Pace from a single reading.
+ *
+ * `usedPct` is a running total since the window opened, and `periodStart` is
+ * a required field every adapter sets, so a pace is always computable from
+ * one poll. Returns null only when `periodStart` is missing or unparseable.
+ */
+export declare function averagePace(q: Quota, now?: Date): number | null;
+export declare function computeAdvisory(q: Quota, burnRate: number | null, now?: Date, paceSourceOrMeasured?: PaceSource | boolean): Advisory;
 export declare function recommend(quotas: Quota[], _task: string, burnByProvider?: Map<string, number>, now?: Date): {
     use: string;
     reason: string;
     wastePct: number;
     idealRate: number;
+    recommendationBasis: RecommendationBasis;
+    alternatives: Quota[];
+    advisories: Advisory[];
+} | {
+    use: string;
+    reason: string;
+    wastePct: null;
+    idealRate: number;
+    recommendationBasis: RecommendationBasis;
     alternatives: Quota[];
     advisories: Advisory[];
 };

package/dist/advisory/engine.js

@@ -1,8 +1,59 @@
-export function computeAdvisory(q, burnRate, now = new Date(), burnMeasured = false) {
+const DAY_MS = 86400000;
+/**
+ * Pace from a single reading.
+ *
+ * `usedPct` is a running total since the window opened, and `periodStart` is
+ * a required field every adapter sets, so a pace is always computable from
+ * one poll. Returns null only when `periodStart` is missing or unparseable.
+ */
+export function averagePace(q, now = new Date()) {
+    if (!q.periodStart)
+        return null;
+    const start = new Date(q.periodStart).getTime();
+    if (Number.isNaN(start))
+        return null;
+    const elapsedDays = (now.getTime() - start) / DAY_MS;
+    if (elapsedDays < 1 / 24)
+        return null; // under an hour in: not yet meaningful
+    const pace = q.usedPct / elapsedDays;
+    if (!Number.isFinite(pace))
+        return null;
+    return Math.max(0, pace);
+}
+export function computeAdvisory(q, burnRate, now = new Date(), paceSourceOrMeasured = "unknown") {
     const resets = new Date(q.resetsAt);
-    const daysLeft = Math.max(0.1, (resets.getTime() - now.getTime()) / 86400000);
+    const daysLeft = Math.max(0.1, (resets.getTime() - now.getTime()) / DAY_MS);
     const remaining = 100 - q.usedPct;
     const idealRate = remaining / daysLeft;
+    let paceSource;
+    let burnMeasured;
+    if (burnRate === null) {
+        paceSource = "unknown";
+        burnMeasured = false;
+    }
+    else if (typeof paceSourceOrMeasured === "string") {
+        paceSource = paceSourceOrMeasured;
+        burnMeasured = paceSource === "recent";
+    }
+    else {
+        burnMeasured = paceSourceOrMeasured;
+        paceSource = burnMeasured ? "recent" : "window-average";
+    }
+    if (burnRate === null) {
+        return {
+            provider: q.provider,
+            daysLeft,
+            remaining,
+            idealRate,
+            burnRate: null,
+            burnMeasured: false,
+            paceSource: "unknown",
+            daysToExhaust: null,
+            status: "unknown",
+            wastePct: null,
+            urgency: "on track",
+        };
+    }
     const wastePct = Math.max(0, remaining - burnRate * daysLeft);
     // burn > ideal is exactly "quota exhausts before reset": remaining/burn < daysLeft
     const daysToExhaust = burnRate > 0 ? remaining / burnRate : Infinity;
@@ -16,14 +67,83 @@ export function computeAdvisory(q, burnRate, now = new Date(), burnMeasured = fa
         urgency = "slow down";
     else if (wastePct > 10)
         urgency = "save";
-    return { provider: q.provider, daysLeft, remaining, idealRate, burnRate, burnMeasured, daysToExhaust, status, wastePct, urgency };
+    return { provider: q.provider, daysLeft, remaining, idealRate, burnRate, burnMeasured, paceSource, daysToExhaust, status, 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, burnByProvider.has(q.provider)));
-    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 };
+    if (!quotas.length) {
+        return {
+            use: "none",
+            reason: "no quotas yet",
+            wastePct: 0,
+            idealRate: 0,
+            recommendationBasis: "none",
+            alternatives: [],
+            advisories: [],
+        };
+    }
+    // Build advisories for every quota with honest pace sources.
+    const advisories = quotas.map(q => {
+        const recent = burnByProvider.get(q.provider);
+        if (recent !== undefined) {
+            return computeAdvisory(q, recent, now, "recent");
+        }
+        const avg = averagePace(q, now);
+        if (avg !== null) {
+            return computeAdvisory(q, avg, now, "window-average");
+        }
+        return computeAdvisory(q, null, now, "unknown");
+    });
+    // 1. Prefer measured providers with positive avoidable waste (actionable "Use more" candidates).
+    const positiveWaste = advisories.filter((a) => a.paceSource !== "unknown" && a.wastePct !== null && a.wastePct > 0);
+    if (positiveWaste.length > 0) {
+        const burnNow = positiveWaste.filter(a => a.urgency === "burn now");
+        const pool = burnNow.length ? burnNow : positiveWaste;
+        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,
+            recommendationBasis: "known-waste",
+            alternatives: quotas,
+            advisories,
+        };
+    }
+    // 2. Low-confidence fallback: rank unknown providers by remaining headroom (remaining / daysLeft).
+    const unknownProviders = advisories.filter(a => a.paceSource === "unknown" && a.remaining > 0);
+    if (unknownProviders.length > 0) {
+        const use = unknownProviders.sort((a, b) => (b.remaining / b.daysLeft) - (a.remaining / a.daysLeft))[0];
+        return {
+            use: use.provider,
+            reason: `Measuring pace; ${Math.round(use.remaining)}% remains with ${use.daysLeft.toFixed(1)}d until reset`,
+            wastePct: null,
+            idealRate: use.idealRate,
+            recommendationBasis: "unknown-headroom",
+            alternatives: quotas,
+            advisories,
+        };
+    }
+    // 3. Check if all measured providers are healthy and on pace (status "on track").
+    const onTrack = advisories.filter(a => a.paceSource !== "unknown" && a.status === "on track" && a.remaining > 0);
+    if (onTrack.length > 0) {
+        return {
+            use: "none",
+            reason: "No subscription needs priority",
+            wastePct: 0,
+            idealRate: 0,
+            recommendationBasis: "none",
+            alternatives: quotas,
+            advisories,
+        };
+    }
+    // 4. No meaningful candidate (e.g. all quotas at risk or exhausted).
+    return {
+        use: "none",
+        reason: "all quotas at risk or exhausted",
+        wastePct: 0,
+        idealRate: 0,
+        recommendationBasis: "none",
+        alternatives: quotas,
+        advisories,
+    };
 }