quotacap 0.0.22 → 0.0.23

package/README.md

@@ -39,21 +39,19 @@ npm install -g quotacap
 ```
 
 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.
+One command takes you from zero to a running tracker: the installer verifies checksums, provisions config, registers the background login service, and opens the dashboard. Re-running it upgrades in place with no flags. Pass `--no-service` (foreground only) or `--no-open` (SSH sessions) to skip steps.
 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
 
 ```bash
-# Terminal 1: leave this running
-quotacap init                 # writes ~/.quotacap/config.json
-quotacap web                  # dashboard at http://localhost:8787
-
-# Terminal 2: after the dashboard table fills
+quotacap            # opens the dashboard, starting the service if needed
 quotacap status
 quotacap advise
+quotacap update     # upgrade to the latest release
 ```
 
-`web` stays in the foreground and starts the daemon.
+No setup ceremony: config is provisioned on first use, and bare `quotacap` is the dashboard launcher. `quotacap web --foreground` and `quotacap daemon` keep the old hold-the-terminal mode for SSH, containers, and supervisors.
 
 ## MCP
 

package/dist/adapters/grok.js

@@ -10,7 +10,7 @@ const ABBR_MONTHS = {
     jul: 6, aug: 7, sep: 8, oct: 9, nov: 10, dec: 11,
 };
 function parseGrokReset(raw, now) {
-    const m = raw.trim().match(/^([A-Za-z]+)\s+(\d{1,2}),\s+(\d{1,2}):(\d{2})$/);
+    const m = raw.trim().match(/^([A-Za-z]+)\s+(\d{1,2}),\s*(\d{1,2}):(\d{2})$/);
     if (!m)
         return null;
     const monStr = m[1].toLowerCase();
@@ -73,7 +73,7 @@ export function parseGrokTui(text, now = new Date()) {
         if (Number.isFinite(v) && v >= 0)
             creditsUsd = v;
     }
-    const mReset = cleaned.match(/Resets:\s*([A-Za-z]+\s+\d+,\s+\d+:\d+)/i);
+    const mReset = cleaned.match(/Resets:\s*([A-Za-z]+\s+\d+,\s*\d+:\d+)/i);
     let resetsAt = null;
     let estimated = false;
     if (mReset) {

package/dist/adapters/pty.d.ts

@@ -20,4 +20,22 @@ export interface PtyRunOptions {
     /** Diagnostic label for the tracked child (adapter id). */
     label?: string;
 }
+export interface SpawnHelperRepair {
+    helper: string;
+    ok: boolean;
+    error?: string;
+}
+/**
+ * Lazy replacement for the removed postinstall: best-effort `chmod 0o755`
+ * over every prebuilds entry `spawn-helper` under the given node-pty roots.
+ * Missing roots, missing prebuild dirs, and missing helpers are skipped
+ * silently; only attempted repairs are recorded.
+ */
+export declare function repairSpawnHelpers(roots: string[], chmod?: (p: string, mode: number) => void): SpawnHelperRepair[];
+/**
+ * Human diagnostic for failed repairs, or null when nothing failed.
+ * Load-bearing for root-owned trees (e.g. `sudo` global installs) where the
+ * invoking user cannot repair: without it the failure would go opaque again.
+ */
+export declare function describeSpawnHelperRepairs(outcomes: SpawnHelperRepair[]): string | null;
 export declare function runPty(opts: PtyRunOptions): Promise<string>;

package/dist/adapters/pty.js

@@ -18,17 +18,71 @@ function regexTest(re, s) {
     const fresh = new RegExp(re.source, re.flags.replace("g", ""));
     return fresh.test(s);
 }
+/**
+ * Lazy replacement for the removed postinstall: best-effort `chmod 0o755`
+ * over every prebuilds entry `spawn-helper` under the given node-pty roots.
+ * Missing roots, missing prebuild dirs, and missing helpers are skipped
+ * silently; only attempted repairs are recorded.
+ */
+export function repairSpawnHelpers(roots, chmod = fs.chmodSync) {
+    const outcomes = [];
+    const seen = new Set();
+    for (const root of roots) {
+        let entries;
+        try {
+            entries = fs.readdirSync(path.join(root, "prebuilds"));
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const helper = path.join(root, "prebuilds", entry, "spawn-helper");
+            if (seen.has(helper))
+                continue;
+            seen.add(helper);
+            try {
+                if (!fs.existsSync(helper))
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            try {
+                chmod(helper, 0o755);
+                outcomes.push({ helper, ok: true });
+            }
+            catch (e) {
+                outcomes.push({ helper, ok: false, error: String(e?.message ?? e) });
+            }
+        }
+    }
+    return outcomes;
+}
+/**
+ * Human diagnostic for failed repairs, or null when nothing failed.
+ * Load-bearing for root-owned trees (e.g. `sudo` global installs) where the
+ * invoking user cannot repair: without it the failure would go opaque again.
+ */
+export function describeSpawnHelperRepairs(outcomes) {
+    const failed = outcomes.filter((o) => !o.ok);
+    if (failed.length === 0)
+        return null;
+    const lines = failed.map((o) => `could not make ${o.helper} executable (${o.error ?? "unknown error"})`);
+    return (`${lines.join("; ")} — the install tree is likely root-owned (e.g. installed with sudo); ` +
+        `reinstall without sudo or fix the install's ownership so the invoking user can write it`);
+}
+function nodePtyPackageRoot(resolvedEntry) {
+    const dir = path.dirname(resolvedEntry);
+    // node-pty's main entry is lib/index.js; the package root is two levels up.
+    if (path.basename(dir) === "lib" && /^index\.[cm]?js$/.test(path.basename(resolvedEntry))) {
+        return path.dirname(dir);
+    }
+    return dir;
+}
 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}`;
@@ -40,6 +94,29 @@ function getPty() {
         path.join(os.homedir(), ".local", "share", "quotacap", "pty", platformArch, "node-pty"),
         path.join(os.homedir(), ".quotacap", "pty", "node-pty"),
     ];
+    // Best-effort +x before requiring: the resolvable npm root (when present)
+    // plus every existing sidecar root. Successful repairs stay silent.
+    const repairRoots = [];
+    try {
+        const require0 = createRequire(import.meta.url);
+        repairRoots.push(nodePtyPackageRoot(require0.resolve("node-pty")));
+    }
+    catch { }
+    for (const c of candidates) {
+        try {
+            if (fs.existsSync(c))
+                repairRoots.push(c);
+        }
+        catch { }
+    }
+    const repairs = repairSpawnHelpers(repairRoots);
+    try {
+        const require = createRequire(import.meta.url);
+        ptyMod = require("node-pty");
+        if (ptyMod?.spawn)
+            return ptyMod;
+    }
+    catch { }
     for (const c of candidates) {
         try {
             if (!fs.existsSync(c))
@@ -65,7 +142,9 @@ function getPty() {
         }
         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)");
+    const repairNote = describeSpawnHelperRepairs(repairs);
+    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)" +
+        (repairNote ? `; ${repairNote}` : ""));
 }
 function isBunRuntime() {
     return typeof globalThis.Bun !== "undefined" && typeof globalThis.Bun.spawn === "function";
@@ -97,6 +176,11 @@ async function runPtyBun(opts) {
     let transcript = "";
     let exited = false;
     let exitCode;
+    // Genuine PTY via the Bun.spawn `terminal` option (verified on Bun 1.3.11):
+    // the child's stdin, stdout, and stderr are all the PTY slave, input goes
+    // through proc.terminal.write, and merged output arrives in `data`.
+    // proc.stdin/stdout/stderr are null in this mode.
+    const decoder = new TextDecoder();
     const proc = BunGlobal.spawn([opts.file, ...(opts.args ?? [])], {
         cwd: opts.cwd ?? process.cwd(),
         env: {
@@ -104,25 +188,26 @@ async function runPtyBun(opts) {
             ...(opts.env ?? {}),
             TERM: "xterm-256color",
         },
-        stdin: "pipe",
-        pty: { cols, rows },
+        terminal: {
+            cols,
+            rows,
+            data(_term, chunk) {
+                try {
+                    transcript += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+                }
+                catch { }
+            },
+        },
     });
-    // Capture stdout (pty merges stdout+stderr)
-    const decoder = new TextDecoder();
-    const reader = proc.stdout.getReader();
-    let reading = true;
-    const readLoop = (async () => {
+    if (!proc.terminal) {
+        // Old Bun runtimes silently ignore the unknown `terminal` option, so an
+        // absent proc.terminal is the fail-loud signal — never run half-attached.
         try {
-            while (reading) {
-                const { value, done } = await reader.read();
-                if (done)
-                    break;
-                if (value)
-                    transcript += decoder.decode(value);
-            }
+            proc.kill();
         }
         catch { }
-    })();
+        throw new Error("pty: Bun runtime lacks terminal (PTY) support (Bun.spawn terminal option unavailable) — rebuild the standalone binary with a newer Bun version");
+    }
     // Poll for exit
     const exitPoll = (async () => {
         try {
@@ -132,6 +217,7 @@ async function runPtyBun(opts) {
         }
         catch { }
     })();
+    void exitPoll;
     const checkCap = () => {
         if (Buffer.byteLength(transcript, "utf8") > maxBytes) {
             throw new Error(`pty transcript exceeds ${maxBytes} bytes`);
@@ -169,6 +255,10 @@ async function runPtyBun(opts) {
             proc.kill();
         }
         catch { }
+        try {
+            proc.terminal?.close();
+        }
+        catch { }
     }, opts.label ?? opts.file);
     try {
         if (opts.readyRegex) {
@@ -211,9 +301,7 @@ async function runPtyBun(opts) {
         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();
+            proc.terminal.write(opts.input);
         }
         catch (e) {
             throw new Error(`pty write failed: ${e.message}`);
@@ -257,12 +345,17 @@ async function runPtyBun(opts) {
             }
         }
         await kill();
-        reading = false;
+        // Drain late `data` callbacks, then close the terminal and flush the
+        // streamed decoder before the final checks.
+        await delay(200);
         try {
-            reader.cancel();
+            proc.terminal.close();
+        }
+        catch { }
+        try {
+            transcript += decoder.decode();
         }
         catch { }
-        await Promise.race([readLoop, delay(200)]);
         checkCap();
         checkAborted();
         const finalClean = stripAnsi(transcript);
@@ -272,12 +365,11 @@ async function runPtyBun(opts) {
         return transcript;
     }
     catch (e) {
-        reading = false;
+        await kill();
         try {
-            reader.cancel();
+            proc.terminal.close();
         }
         catch { }
-        await kill();
         unregisterChild();
         teardownAbort();
         throw e;

package/dist/advisory/snapshot.d.ts

@@ -9,6 +9,12 @@ export interface SnapshotOptions {
         polling: "idle" | "in-progress" | "cooldown";
         lastCompletedPollAt: string | null;
         version: string;
+        update?: {
+            current: string;
+            latest: string | null;
+            upToDate: boolean;
+            checkedAt: string | null;
+        };
     };
 }
 export declare function buildSnapshot(db: any, opts: SnapshotOptions): StateSnapshot;

package/dist/advisory/types.d.ts

@@ -42,6 +42,12 @@ export interface ProviderSnapshot {
     exclusionReason: ExclusionReason;
     advisory: Advisory | null;
 }
+export interface UpdateStatus {
+    current: string;
+    latest: string | null;
+    upToDate: boolean;
+    checkedAt: string | null;
+}
 export interface StateSnapshot {
     asOf: string;
     runtime: {
@@ -50,6 +56,7 @@ export interface StateSnapshot {
         polling: "idle" | "in-progress" | "cooldown";
         lastCompletedPollAt: string | null;
         version: string;
+        update?: UpdateStatus;
     };
     providers: ProviderSnapshot[];
     recommendation: Recommendation;

package/dist/cli/advise.js

@@ -1,13 +1,22 @@
 import { projectRecommendationResponse } from "../advisory/snapshot.js";
 import { validateTask } from "../advisory/validate.js";
-import { getDbPath, readConfig } from "../config.js";
+import { ensureConfig, getDbPath } from "../config.js";
 import { createServiceClient } from "../runtime/client.js";
-import { ClientError, OFFLINE_LABEL, emptySnapshot, resolveSnapshot } from "./snapshot-source.js";
+import { VERSION } from "../version.js";
+import { isServiceManaged, runServiceCommand } from "../service/index.js";
+import { detectChannel, printUpdateFooter, readUpdateCache, refreshUpdateCache, updateFooter, } from "../runtime/updates.js";
+import { ClientError, OFFLINE_LABEL, emptySnapshot, offlineOnlyClient, resolveSnapshot } from "./snapshot-source.js";
+import { checkSkew, execSkewWarning, olderCliWarning, takeoverManaged, unmanagedSkewWarning, } from "./takeover.js";
 export function registerAdviseCommand(program, deps) {
     const createClient = deps.createClient ?? ((o) => createServiceClient(o));
     const openDb = deps.openDb;
     const now = deps.now ?? (() => new Date());
     const exit = deps.exit ?? process.exit;
+    const execService = deps.execService ?? ((args, o) => runServiceCommand(args, o ?? {}, {}));
+    const isManaged = deps.isManaged ?? isServiceManaged;
+    const takeoverOpts = deps.takeoverOpts ?? {};
+    const checkUpdates = deps.checkUpdates ??
+        (() => refreshUpdateCache({ channel: detectChannel(), current: VERSION }));
     program
         .command("advise")
         .description("show which provider to use next (same advice for every task)")
@@ -26,8 +35,61 @@ export function registerAdviseCommand(program, deps) {
             return;
         }
         const t = now();
-        const cfg = await readConfig();
-        const client = createClient({ port: cfg.port, timeoutMs: 2000 });
+        const { config: cfg } = await ensureConfig();
+        let client = createClient({ port: cfg.port, timeoutMs: 2000 });
+        // Skew pre-check mirrors status: warn on exec-only and older-CLI skew,
+        // take the managed path when newer, and never spawn a foreground daemon
+        // here — unmanaged skew serves the stored snapshot instead of failing.
+        let health = null;
+        try {
+            health = await client.get("/health");
+        }
+        catch {
+            health = null;
+        }
+        if (health?.ok) {
+            const skew = checkSkew(health, VERSION, process.execPath);
+            if (skew === "exec-only") {
+                console.error(execSkewWarning(String(health.exec)));
+            }
+            else if (skew === "cli-older") {
+                console.error(olderCliWarning(String(health.version ?? "unknown")));
+            }
+            else if (skew === "cli-newer") {
+                const managed = await isManaged().catch(() => false);
+                if (managed) {
+                    try {
+                        const r = await takeoverManaged({
+                            port: cfg.port,
+                            health,
+                            createClient,
+                            execService,
+                            ...takeoverOpts,
+                        });
+                        console.error(r.message);
+                    }
+                    catch (e) {
+                        console.error(e instanceof Error ? e.message : String(e));
+                        exit(1);
+                        return;
+                    }
+                }
+                else {
+                    console.error(unmanagedSkewWarning(String(health.version ?? "unknown")));
+                    client = offlineOnlyClient();
+                }
+            }
+        }
+        // Passive daily update signal: opportunistically refresh the shared
+        // cache, then surface staleness as a stderr footer (never in --json).
+        let updateCache = null;
+        try {
+            updateCache = await checkUpdates();
+        }
+        catch {
+            updateCache = readUpdateCache();
+        }
+        const footer = updateFooter(VERSION, updateCache?.latest ?? null);
         let resolved;
         try {
             resolved = await resolveSnapshot({
@@ -43,8 +105,10 @@ export function registerAdviseCommand(program, deps) {
                 const rec = projectRecommendationResponse(emptySnapshot(t), task);
                 if (o.json)
                     console.log(JSON.stringify(rec, null, 2));
-                else
+                else {
                     console.log(`${rec.use}: ${rec.reason}`);
+                    printUpdateFooter(o, footer);
+                }
                 return;
             }
             console.error(e instanceof Error ? e.message : String(e));
@@ -56,7 +120,9 @@ export function registerAdviseCommand(program, deps) {
         const rec = projectRecommendationResponse(resolved.snapshot, task);
         if (o.json)
             console.log(JSON.stringify(rec, null, 2));
-        else
+        else {
             console.log(`${rec.use}: ${rec.reason}`);
+            printUpdateFooter(o, footer);
+        }
     });
 }

package/dist/cli/clients.d.ts

@@ -1,5 +1,7 @@
 import type { Command } from "commander";
 import type { ServiceClient } from "../runtime/client.js";
+import type { SleepFn } from "./takeover.js";
+import type { UpdateCache } from "../runtime/updates.js";
 export interface CreateClientOptions {
     port: number;
     token?: string;
@@ -14,5 +16,13 @@ export interface ClientCommandDeps {
     };
     now?: () => Date;
     exit?: (code: number) => void;
+    execService?: (args: string[], opts?: Record<string, any>) => Promise<number>;
+    isManaged?: () => Promise<boolean>;
+    takeoverOpts?: {
+        sleep?: SleepFn;
+        timeoutMs?: number;
+        readToken?: () => string | undefined;
+    };
+    checkUpdates?: () => Promise<UpdateCache | null>;
 }
 export declare function registerClientCommands(program: Command, deps?: ClientCommandDeps): void;

package/dist/cli/index.js

@@ -1,17 +1,14 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import { VERSION } from "../version.js";
-import { registerRuntimeCommands } from "./runtime.js";
+import { launchWeb, registerRuntimeCommands } from "./runtime.js";
 import { registerClientCommands } from "./clients.js";
+import { registerInitCommand } from "./init.js";
+import { registerUpdateCommand } from "./update.js";
 const program = new Command();
 program.name("quotacap").version(VERSION);
 program.command("version").action(() => console.log(VERSION));
-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));
-});
+registerInitCommand(program);
 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
@@ -19,4 +16,12 @@ program.command("mcp").description("start MCP server (stdio over HTTP)").action(
 });
 registerRuntimeCommands(program);
 registerClientCommands(program);
-program.parseAsync();
+registerUpdateCommand(program);
+// Bare `quotacap` with no arguments at all opens the dashboard through the
+// shared launcher; flags and subcommands keep Commander behavior.
+if (process.argv.length === 2) {
+    launchWeb({});
+}
+else {
+    program.parseAsync();
+}

package/dist/cli/init.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerInitCommand(program: Command): void;

package/dist/cli/init.js

@@ -0,0 +1,29 @@
+import fsSync from "node:fs";
+import { defaultConfig, ensureConfig, getConfigPath, readConfig, writeConfig, } from "../config.js";
+const NEXT_STEP = "next: run 'quotacap web' to open the dashboard, 'quotacap service status' to check the background service";
+export function registerInitCommand(program) {
+    program
+        .command("init")
+        .description("show or reset the config file")
+        .option("--quiet", "print nothing on success")
+        .option("--force", "rewrite defaults after moving the existing file to config.json.bak")
+        .action(async (o) => {
+        const p = getConfigPath();
+        if (o.force && fsSync.existsSync(p)) {
+            fsSync.renameSync(p, `${p}.bak`);
+            await writeConfig(defaultConfig());
+            if (o.quiet)
+                return;
+            console.log(JSON.stringify(await readConfig(), null, 2));
+            console.error(`rewrote default config at ${p} (previous saved to ${p}.bak)\n${NEXT_STEP}`);
+            return;
+        }
+        const r = await ensureConfig();
+        if (o.quiet)
+            return;
+        console.log(JSON.stringify(r.config, null, 2));
+        console.error(r.created
+            ? `wrote default config to ${p}\n${NEXT_STEP}`
+            : `config already exists at ${p} (use --force to rewrite defaults)\n${NEXT_STEP}`);
+    });
+}

package/dist/cli/runtime.d.ts

@@ -1,5 +1,7 @@
 import type { Command } from "commander";
 import { startService, type StartServiceOptions } from "../runtime/service.js";
+import { type ServiceClient } from "../runtime/client.js";
+import { type SleepFn } from "./takeover.js";
 export type StartServiceFn = (opts?: StartServiceOptions) => ReturnType<typeof startService>;
 export type OpenBrowserFn = (url: string) => Promise<void> | void;
 export type ExecServiceFn = (args: string[], opts?: Record<string, any>) => Promise<number>;
@@ -8,5 +10,24 @@ export interface RuntimeCommandDeps {
     openBrowser?: OpenBrowserFn;
     execService?: ExecServiceFn;
     exit?: (code: number) => void;
+    createClient?: (opts: {
+        port: number;
+        token?: string;
+        timeoutMs: number;
+    }) => ServiceClient;
+    isManaged?: () => Promise<boolean>;
+    takeoverOpts?: {
+        sleep?: SleepFn;
+        timeoutMs?: number;
+        readToken?: () => string | undefined;
+    };
+    checkUpdates?: () => Promise<unknown>;
+    isInstalled?: () => Promise<boolean>;
+    serviceSupported?: () => boolean;
 }
+export interface WebLaunchOptions {
+    port?: string;
+    foreground?: boolean;
+}
+export declare function launchWeb(o: WebLaunchOptions, deps?: RuntimeCommandDeps): Promise<void>;
 export declare function registerRuntimeCommands(program: Command, deps?: RuntimeCommandDeps): void;