@cad0p/pi-usage 0.0.0-stage → 0.11.2

package/src/browser/history.js

@@ -0,0 +1,173 @@
+/**
+ * Read-only Firefox history lookup.
+ *
+ * Needed because opencode.ai serves the workspace app only at
+ * `/workspace/<id>/...`: there is no listing page at `/workspace` (it answers
+ * 404 even when authenticated), so the id has to be observed. Firefox records
+ * the URL the OAuth flow lands on, which makes its history the reliable source.
+ *
+ * Read-only: `places.sqlite` (with `-wal`/`-shm`) is copied to a private temp
+ * directory and opened there. Only URLs are read, and query strings are never
+ * returned to callers.
+ */
+
+import { DatabaseSync } from "node:sqlite";
+import { copyFileSync, existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { firefoxRoots, parseFirefoxProfiles } from "./cookies.js";
+
+/**
+ * @param {{ home?: string, usersRoot?: string, platform?: string }} [options]
+ * @returns {Array<{ profile: string, path: string }>}
+ */
+export function discoverHistoryStores(options = {}) {
+  /** @type {Array<{ profile: string, path: string }>} */
+  const stores = [];
+  for (const root of firefoxRoots(options)) {
+    for (const profile of parseFirefoxProfiles(root)) {
+      const path = join(profile.dir, "places.sqlite");
+      if (!existsSync(path)) continue;
+      const platformPrefix = root.includes("Application Support")
+        ? "mac"
+        : root.endsWith("Firefox")
+          ? "windows"
+          : "linux";
+      stores.push({ profile: `${platformPrefix}:${profile.label}`, path });
+    }
+  }
+  return stores;
+}
+
+/**
+ * Strip the query string so no token can leak through a URL.
+ *
+ * @param {string} url
+ * @returns {string}
+ */
+export function pathOnly(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.pathname;
+  } catch {
+    return String(url).split("?")[0];
+  }
+}
+
+/**
+ * Extract workspace ids from a list of URLs, most recent first.
+ *
+ * @param {string[]} urls
+ * @returns {string[]}
+ */
+export function extractWorkspaceIds(urls) {
+  /** @type {string[]} */
+  const ids = [];
+  const ignored = new Set(["settings", "usage", "go", "keys", "members", "billing", "new", "login", "auth"]);
+  for (const url of urls) {
+    const match = pathOnly(url).match(/\/(?:workspace|console)\/([A-Za-z0-9_-]{4,})/);
+    if (!match) continue;
+    if (ignored.has(match[1])) continue;
+    if (!ids.includes(match[1])) ids.push(match[1]);
+  }
+  return ids;
+}
+
+/**
+ * Query one history database.
+ *
+ * @param {string} dbPath
+ * @param {{ urlLike: string, limit?: number }} query
+ * @returns {string[]}
+ */
+const activeHistoryCleanups = new Set();
+if (typeof process !== "undefined" && typeof process.on === "function") {
+  const runCleanups = () => {
+    for (const fn of activeHistoryCleanups) {
+      try { fn(); } catch {}
+    }
+    activeHistoryCleanups.clear();
+  };
+  process.once("exit", runCleanups);
+  process.once("SIGINT", () => {
+    runCleanups();
+    process.exit(130);
+  });
+  process.once("SIGTERM", () => {
+    runCleanups();
+    process.exit(143);
+  });
+}
+
+export function readVisitedUrls(dbPath, query) {
+  const dir = mkdtempSync(join(tmpdir(), "pi-quota-history-"));
+  const target = join(dir, "places.sqlite");
+  const cleanupFn = () => {
+    activeHistoryCleanups.delete(cleanupFn);
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      // Best effort.
+    }
+  };
+  activeHistoryCleanups.add(cleanupFn);
+
+  try {
+    for (const suffix of ["", "-wal", "-shm"]) {
+      const source = `${dbPath}${suffix}`;
+      if (existsSync(source)) {
+        try {
+          copyFileSync(source, `${target}${suffix}`);
+        } catch {
+          // A locked sidecar is not fatal.
+        }
+      }
+    }
+    let database;
+    try {
+      database = new DatabaseSync(target, { readOnly: true });
+    } catch {
+      database = new DatabaseSync(target);
+    }
+    try {
+      const rows = database
+        .prepare("select url from moz_places where url like ? order by last_visit_date desc limit ?")
+        .all(query.urlLike, query.limit ?? 50);
+      return /** @type {Array<{ url: string }>} */ (rows).map((row) => row.url).filter(Boolean);
+    } finally {
+      try {
+        database.close();
+      } catch {
+        // Ignore.
+      }
+    }
+  } catch {
+    return [];
+  } finally {
+    cleanupFn();
+  }
+}
+
+/**
+ * Find recently visited workspace ids, newest first.
+ *
+ * @param {{
+ *   stores?: Array<{ profile: string, path: string }>,
+ *   home?: string,
+ *   usersRoot?: string,
+ *   platform?: string,
+ * }} [options]
+ * @returns {{ ids: string[], profile: string | null, scanned: number }}
+ */
+export function findRecentWorkspaceIds(options = {}) {
+  const stores = options.stores ?? discoverHistoryStores(options);
+  let scanned = 0;
+  for (const store of stores) {
+    scanned += 1;
+    const urls = readVisitedUrls(store.path, { urlLike: "%opencode.ai/%", limit: 100 });
+    const ids = extractWorkspaceIds(urls);
+    if (ids.length > 0) return { ids, profile: store.profile, scanned };
+  }
+  return { ids: [], profile: null, scanned };
+}

package/src/cache.js

@@ -0,0 +1,224 @@
+/**
+ * Local response cache.
+ *
+ * Holds only the already-normalized report (percentages, windows, labels): no
+ * access token, refresh token, API key, cookie or account e-mail beyond the
+ * display identity the renderers already print.
+ */
+
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const DEFAULT_TTL_MS = 60_000;
+
+/**
+ * Merge a partial report into an existing cached report so partial family queries
+ * do not clobber other cached providers.
+ *
+ * @param {import("./engine.js").PiQuotaReport | null | undefined} existingReport
+ * @param {import("./engine.js").PiQuotaReport} newReport
+ * @returns {import("./engine.js").PiQuotaReport}
+ */
+export function mergeReportIntoCache(existingReport, newReport) {
+  if (!existingReport || !existingReport.byFamily) return newReport;
+  const mergedByFamily = { ...existingReport.byFamily, ...newReport.byFamily };
+  const existingFamilies = Object.keys(existingReport.byFamily);
+  const newFamilies = Object.keys(newReport.byFamily || {});
+  const allFamilies = Array.from(new Set([...existingFamilies, ...newFamilies]));
+  const providers = allFamilies.flatMap((family) => mergedByFamily[family] || []);
+
+  const keptExistingWarnings = (existingReport.warnings || []).filter((w) => {
+    const family = String(w).split(":")[0];
+    return !newFamilies.includes(family);
+  });
+  const seenPatterns = new Set();
+  const warnings = [];
+  for (const w of [...(newReport.warnings || []), ...keptExistingWarnings]) {
+    const pattern = w.replace(/\d+m ago/, "Xm ago").replace(/\d+s old/, "Xs old").replace(/\d+s\b/, "Xs");
+    if (!seenPatterns.has(pattern)) {
+      seenPatterns.add(pattern);
+      warnings.push(w);
+    }
+  }
+
+  return {
+    ...existingReport,
+    ...newReport,
+    providers,
+    byFamily: mergedByFamily,
+    warnings,
+  };
+}
+
+/**
+ * @param {{ env?: Record<string, string | undefined>, home?: string, path?: string }} [options]
+ * @returns {string}
+ */
+export function resolveCachePath(options = {}) {
+  if (options.path) return options.path;
+  const env = options.env ?? process.env;
+  const cacheHome = options.home ? join(options.home, ".cache") : (env.XDG_CACHE_HOME || join(homedir(), ".cache"));
+  return join(cacheHome, "pi-quota", "usage.json");
+}
+
+/**
+ * @param {{
+ *   path?: string,
+ *   ttlMs?: number,
+ *   now?: number,
+ *   env?: Record<string, string | undefined>,
+ *   home?: string,
+ * }} [options]
+ * @returns {{ report: import("./engine.js").PiQuotaReport, ageMs: number, path: string } | null}
+ */
+export function readCache(options = {}) {
+  const path = options.path ?? resolveCachePath(options);
+  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+  const now = options.now ?? Date.now();
+
+  let raw;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const report = /** @type {{ report?: import("./engine.js").PiQuotaReport }} */ (parsed).report;
+  if (!report || !Array.isArray(report.providers)) return null;
+
+  const savedAt = typeof /** @type {{ savedAt?: unknown }} */ (parsed).savedAt === "number"
+    ? /** @type {number} */ (/** @type {{ savedAt?: number }} */ (parsed).savedAt)
+    : null;
+  if (savedAt === null) return null;
+  const ageMs = now - savedAt;
+  if (ageMs > ttlMs) return null;
+
+  for (const provider of report.providers) {
+    for (const win of provider.windows ?? []) {
+      if (win.resetsAt) {
+        const parsedMs = Date.parse(win.resetsAt);
+        if (!Number.isNaN(parsedMs)) {
+          win.resetsInSec = Math.max(0, Math.round((parsedMs - now) / 1000));
+        }
+      }
+    }
+  }
+
+  return { report, ageMs, path };
+}
+
+/**
+ * @param {import("./engine.js").PiQuotaReport} report
+ * @param {{
+ *   path?: string,
+ *   now?: number,
+ *   env?: Record<string, string | undefined>,
+ *   home?: string,
+ * }} [options]
+ * @returns {{ ok: boolean, path: string, error?: string }}
+ */
+export function writeCache(report, options = {}) {
+  const path = options.path ?? resolveCachePath(options);
+  const now = options.now ?? Date.now();
+  let finalReport = report;
+  if (options.merge) {
+    const existing = readCache({ ...options, path, ttlMs: Number.POSITIVE_INFINITY });
+    if (existing?.report) {
+      finalReport = mergeReportIntoCache(existing.report, report);
+    }
+  }
+  const payload = JSON.stringify({ savedAt: now, report: finalReport }, null, 2);
+
+  try {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, payload, { encoding: "utf-8", mode: 0o600 });
+    try {
+      chmodSync(temporary, 0o600);
+    } catch {
+      // Best-effort in environments where chmod is not supported.
+    }
+    renameSync(temporary, path);
+    return { ok: true, path };
+  } catch (error) {
+    return { ok: false, path, error: /** @type {{ message?: string }} */ (error)?.message ?? String(error) };
+  }
+}
+
+/**
+ * @param {{ path?: string, env?: Record<string, string | undefined>, home?: string }} [options]
+ * @returns {{ removed: boolean, path: string }}
+ */
+export function clearCache(options = {}) {
+  const path = options.path ?? resolveCachePath(options);
+  try {
+    rmSync(path, { force: true });
+    return { removed: true, path };
+  } catch {
+    return { removed: false, path };
+  }
+}
+
+/**
+ * @param {{ path?: string, env?: Record<string, string | undefined>, home?: string }} [options]
+ * @returns {{ exists: boolean, path: string, sizeBytes: number | null }}
+ */
+export function describeCache(options = {}) {
+  const path = options.path ?? resolveCachePath(options);
+  try {
+    const stats = statSync(path);
+    return { exists: true, path, sizeBytes: stats.size };
+  } catch {
+    return { exists: false, path, sizeBytes: null };
+  }
+}
+
+/**
+ * Read-through helper: return a fresh cached report or refresh it.
+ *
+ * @param {{
+ *   ttlMs?: number,
+ *   now?: number,
+ *   force?: boolean,
+ *   path?: string,
+ *   families?: string[],
+ *   merge?: boolean,
+ *   env?: Record<string, string | undefined>,
+ *   home?: string,
+ * }} options
+ * @param {() => Promise<import("./engine.js").PiQuotaReport>} loader
+ * @returns {Promise<{ report: import("./engine.js").PiQuotaReport, cached: boolean, ageMs: number }>}
+ */
+export async function withCache(options, loader) {
+  const requested = options.families;
+  if (!options.force) {
+    const hit = readCache(options);
+    if (hit) {
+      const allPresent = !requested || requested.every((fam) => fam in hit.report.byFamily);
+      if (allPresent) {
+        const filteredReport = requested
+          ? {
+              ...hit.report,
+              providers: hit.report.providers.filter((p) => requested.includes(p.family)),
+              byFamily: Object.fromEntries(
+                Object.entries(hit.report.byFamily).filter(([fam]) => requested.includes(fam)),
+              ),
+            }
+          : hit.report;
+        return { report: filteredReport, cached: true, ageMs: hit.ageMs };
+      }
+    }
+  }
+  const report = await loader();
+  const isPartial = Array.isArray(requested) && requested.length > 0;
+  writeCache(report, { ...options, merge: isPartial || options.merge });
+  return { report, cached: false, ageMs: 0 };
+}

package/src/cli/args.js

@@ -0,0 +1,154 @@
+/**
+ * Argument parsing shared by both CLIs.
+ *
+ * Deliberately small: this parser only owns the flags piquota itself
+ * implements, and reports anything else as unknown.
+ */
+
+/**
+ * @typedef {Object} ParsedArgs
+ * @property {string[]} positionals
+ * @property {boolean} json
+ * @property {boolean} compact
+ * @property {boolean} color
+ * @property {boolean} noCache
+ * @property {boolean} force
+ * @property {boolean} explain
+ * @property {boolean} help
+ * @property {boolean} version
+ * @property {boolean} status
+ * @property {boolean} clearCache
+ * @property {number} ttlMs
+ * @property {number} timeoutMs
+ * @property {string[]} unknown          Flags this parser does not own.
+ * @property {string[]} raw              Original argv.
+ */
+
+const VALUE_FLAGS = new Set(["--ttl", "--timeout"]);
+
+/**
+ * Flags a subcommand consumes from the raw argv, collected here only so the parser
+ * can tell a real typo apart from a flag that belongs to subcommands like `auth`.
+ */
+const SUBCOMMAND_VALUE_FLAGS = new Set(["--wait"]);
+
+/** Boolean flags owned by a subcommand. */
+const SUBCOMMAND_FLAGS = new Set(["--paste", "--no-browser", "--no-refresh"]);
+
+/**
+ * What to name in an "unknown flag" report.
+ *
+ * A bare flag is reported alone when nothing followed it or when what followed was
+ * another flag: `--interval --fetch-ttl` must not claim that `--fetch-ttl` was the
+ * value of `--interval`.
+ *
+ * @param {string} flag
+ * @param {string | undefined} value
+ * @returns {string[]}
+ */
+function flagWithValue(flag, value) {
+  return value !== undefined && value !== "" && !value.startsWith("-") ? [flag, value] : [flag];
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{ defaultTtlMs?: number, defaultTimeoutMs?: number }} [defaults]
+ * @returns {ParsedArgs}
+ */
+export function parseArgs(argv, defaults = {}) {
+  /** @type {ParsedArgs} */
+  const parsed = {
+    positionals: [],
+    json: false,
+    compact: false,
+    color: true,
+    noCache: false,
+    force: false,
+    explain: false,
+    help: false,
+    version: false,
+    status: false,
+    box: false,
+    clearCache: false,
+    ttlMs: defaults.defaultTtlMs ?? 60_000,
+    timeoutMs: defaults.defaultTimeoutMs ?? 15_000,
+    unknown: [],
+    raw: [...argv],
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (VALUE_FLAGS.has(arg)) {
+      const value = argv[index + 1];
+      index += 1;
+      const number = Number(value);
+      if (!Number.isFinite(number) || number <= 0) {
+        parsed.unknown.push(...flagWithValue(arg, value));
+        continue;
+      }
+      if (arg === "--ttl") parsed.ttlMs = number * 1000;
+      if (arg === "--timeout") parsed.timeoutMs = number;
+      continue;
+    }
+
+    if (SUBCOMMAND_VALUE_FLAGS.has(arg)) {
+      // The value is consumed here only so it cannot be mistaken for a
+      // positional; the subcommand reads it from `raw` itself.
+      const value = argv[index + 1];
+      if (value === undefined || value.startsWith("-") || Number.isNaN(Number(value))) {
+        parsed.unknown.push(...flagWithValue(arg, value));
+        continue;
+      }
+      index += 1;
+      continue;
+    }
+
+    switch (arg) {
+      case "--json":
+        parsed.json = true;
+        break;
+      case "--compact":
+      case "-c":
+        parsed.compact = true;
+        break;
+      case "--no-color":
+        parsed.color = false;
+        break;
+      case "--no-cache":
+        parsed.noCache = true;
+        break;
+      case "--force":
+      case "--refresh":
+        parsed.force = true;
+        break;
+      case "--explain":
+        parsed.explain = true;
+        break;
+      case "--help":
+      case "-h":
+        parsed.help = true;
+        break;
+      case "--version":
+      case "-v":
+        parsed.version = true;
+        break;
+      case "--status":
+        parsed.status = true;
+        break;
+      case "--box":
+        parsed.box = true;
+        break;
+      case "--clear-cache":
+        parsed.clearCache = true;
+        break;
+      default:
+        // Owned by a subcommand, which reads it from `raw` itself.
+        if (SUBCOMMAND_FLAGS.has(arg)) break;
+        if (arg.startsWith("-")) parsed.unknown.push(arg);
+        else parsed.positionals.push(arg);
+    }
+  }
+
+  return parsed;
+}