token-quota 1.0.0

package/src/doctor.js

@@ -0,0 +1,292 @@
+/**
+ * `token-quota doctor` — read-only health check.
+ *
+ * It answers "why is my panel empty?" without changing anything: Node version,
+ * the three data-source CLIs, the sqlite3 the Cursor row needs, and one real
+ * read-only query per platform, each classified as working / not logged in /
+ * CLI missing / query failed. Every failure prints the exact command that fixes
+ * it. It never starts a login flow, never writes a file and never prints a
+ * credential value.
+ *
+ * Exit code: 0 when every check and every selected platform is green, else 1.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { commandLine, selectPlatforms } from './cli.js';
+import { MissingCredential } from './errors.js';
+import { platforms as allPlatforms } from './platforms/index.js';
+import { shimDir } from './quota-axi.js';
+import { PACKAGES, pathFallback, resolveDependencyCli } from './resolve-deps.js';
+
+/** Node major version this package supports (package.json "engines"). */
+export const MIN_NODE_MAJOR = 20;
+
+/**
+ * The CLIs the panel depends on, in check order. `fallback` is the plain
+ * command name to try on PATH when the dependency tree has no copy.
+ */
+export const CLI_CHECKS = [
+  {
+    id: 'quota-axi',
+    label: 'quota-axi',
+    package: PACKAGES.quotaAxi,
+    fallback: 'quota-axi',
+    // Also the data source of the cursor and bailian rows, hence the note.
+    fix: 'npm i -g quota-axi',
+  },
+  {
+    id: 'bailian',
+    label: 'bailian CLI (bl)',
+    package: PACKAGES.bailianCli,
+    fallback: 'bl',
+    fix: 'npm i -g bailian-cli',
+  },
+  {
+    id: 'arkcli',
+    label: 'arkcli (Volcengine Ark)',
+    package: PACKAGES.arkCli,
+    fallback: 'arkcli',
+    fix: 'npm i -g @volcengine/ark-cli',
+  },
+];
+
+const PROBE_TIMEOUT_MS = 20_000;
+
+/**
+ * Which data-source CLIs each platform's row needs. Used to report an install
+ * command before ever trying (and failing) to query the platform.
+ */
+export const REQUIRED_CLIS = {
+  doubao: ['arkcli'],
+  bailian: ['quota-axi', 'bailian'],
+  cursor: ['quota-axi'],
+};
+
+/**
+ * Runs `<command> --version` and reports success plus captured output.
+ * `shell: true` (Windows `.cmd` npm shims) uses a composed command line: passing
+ * args together with `shell` is deprecated, and every argument here is a fixed
+ * flag, never user input.
+ */
+export function defaultProbe(
+  command,
+  args,
+  { env = process.env, timeout = PROBE_TIMEOUT_MS, shell = false } = {},
+) {
+  const base = { encoding: 'utf8', timeout, windowsHide: true, env };
+  const result = shell
+    ? spawnSync(commandLine(command, args), { ...base, shell: true })
+    : spawnSync(command, args, base);
+  return {
+    ok: !result.error && result.status === 0,
+    status: result.status ?? null,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+    error: result.error ?? null,
+  };
+}
+
+/** First `x.y.z` token in the CLI's output, or null. */
+export function extractVersion(stdout = '', stderr = '') {
+  const match = `${stdout}\n${stderr}`.match(/\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?/);
+  return match ? match[0] : null;
+}
+
+/**
+ * Turns a platform query failure into a reportable classification.
+ * `not-logged-in` and `cli-missing` come from MissingCredential; everything else
+ * is an explicit query failure.
+ */
+export function classifyFailure(error) {
+  if (error instanceof MissingCredential) {
+    const missingCli = error.kind === 'cli-missing';
+    return {
+      kind: missingCli ? 'cli-missing' : 'not-logged-in',
+      label: missingCli ? 'CLI missing' : 'not logged in',
+      detail: missingCli ? error.credential : `${error.credential} (${error.howToFix})`,
+      fix: error.howToFix,
+    };
+  }
+  return {
+    kind: 'failed',
+    label: 'query failed',
+    detail: oneLine(error?.message ?? String(error)),
+    fix: null,
+  };
+}
+
+/**
+ * Resolves one data-source CLI and probes `--version`: dependency tree first,
+ * plain PATH command second.
+ * @returns {{ ok: boolean, version: string|null, source: string|null, detail: string|null }}
+ */
+export function checkCli(
+  check,
+  { execPath, platform, arch, env, probe, resolveDependency = resolveDependencyCli },
+) {
+  const resolved = resolveDependency(check.package, { execPath, platform, arch });
+  const candidates = [];
+  if (resolved) candidates.push({ ...resolved, source: 'package dependency' });
+  candidates.push({ ...pathFallback(check.fallback, { platform }), source: 'PATH' });
+
+  let detail = null;
+  for (const candidate of candidates) {
+    const result = probe(candidate.command, [...candidate.prefixArgs, '--version'], {
+      env,
+      shell: candidate.shell === true,
+    });
+    if (result.ok) {
+      return {
+        ok: true,
+        version: extractVersion(result.stdout, result.stderr),
+        source: candidate.source,
+        launch: candidate,
+        detail: null,
+      };
+    }
+    detail = result.error
+      ? `${candidate.source}: ${result.error.code === 'ENOENT' ? 'not found' : oneLine(result.error.message)}`
+      : `${candidate.source}: ${oneLine(result.stderr) || `exit ${result.status}`}`;
+  }
+  return { ok: false, version: null, source: null, launch: null, detail };
+}
+
+/** `node <script>` for JS entries, the bare path for native executables. */
+export function describeLaunch(launch, execPath = process.execPath) {
+  if (!launch) return 'not resolved';
+  return launch.prefixArgs.length > 0
+    ? `${baseName(execPath)} ${launch.prefixArgs.join(' ')}`
+    : launch.command;
+}
+
+/**
+ * Runs the whole check suite and prints the report.
+ * @param {{ only?: string[]|null }} options parsed CLI options
+ * @param {object} [io] injectable environment (streams, probes, platform list)
+ * @returns {Promise<number>} exit code
+ */
+export async function runDoctor(options = {}, io = {}) {
+  const {
+    stdout = process.stdout,
+    stderr = process.stderr,
+    platforms = allPlatforms,
+    execPath = process.execPath,
+    env = process.env,
+    platform = process.platform,
+    arch = process.arch,
+    nodeVersion = process.version,
+    probe = defaultProbe,
+    vendorSqlite3 = join(shimDir(), 'sqlite3.exe'),
+  } = io;
+
+  let selected;
+  try {
+    selected = selectPlatforms(options.only, platforms);
+  } catch (error) {
+    stderr.write(`token-quota: ${error.message}\n`);
+    return 2;
+  }
+
+  const lines = [
+    'token-quota doctor — read-only checks; nothing is signed in, written or refreshed',
+    '',
+    'Environment',
+  ];
+  let failures = 0;
+  const check = (ok, text, fix = null) => {
+    lines.push(`  [${ok ? 'ok' : 'fail'}] ${text}`);
+    if (!ok) {
+      failures += 1;
+      if (fix) lines.push(`         fix: ${fix}`);
+    }
+  };
+
+  const major = Number(String(nodeVersion).replace(/^v/, '').split('.')[0]);
+  check(
+    Number.isFinite(major) && major >= MIN_NODE_MAJOR,
+    `node ${nodeVersion} (requires >= ${MIN_NODE_MAJOR})`,
+    `upgrade Node.js to >= ${MIN_NODE_MAJOR} (https://nodejs.org) and re-run`,
+  );
+
+  if (platform === 'win32') {
+    check(
+      existsSync(vendorSqlite3),
+      `sqlite3 (vendored for Windows) — ${vendorSqlite3}`,
+      'reinstall this package so vendor/sqlite3-shim/sqlite3.exe is present (the cursor row needs it)',
+    );
+  } else {
+    const sqlite = probe('sqlite3', ['--version'], { env });
+    check(
+      sqlite.ok,
+      `sqlite3 (system) — ${extractVersion(sqlite.stdout, sqlite.stderr) ?? 'not found'}`,
+      'install the sqlite3 CLI (e.g. `apt install sqlite3` / `brew install sqlite`); the cursor row needs it',
+    );
+  }
+
+  lines.push('', 'Data-source CLIs');
+  const cliState = {};
+  for (const cliCheck of CLI_CHECKS) {
+    const state = checkCli(cliCheck, { execPath, platform, arch, env, probe });
+    cliState[cliCheck.id] = state;
+    check(
+      state.ok,
+      state.ok
+        ? `${cliCheck.label} ${state.version ?? '(version not reported)'} — ${state.source}: ${describeLaunch(state.launch, execPath)}`
+        : `${cliCheck.label} — ${state.detail}`,
+      cliCheck.fix,
+    );
+  }
+
+  lines.push('', 'Platforms (real read-only queries)');
+  let usable = 0;
+  for (const platformCheck of selected) {
+    // A platform whose data-source CLI is missing never gets queried: report the
+    // install command instead of a confusing spawn error.
+    const required = REQUIRED_CLIS[platformCheck.id] ?? ['quota-axi'];
+    const missing = required
+      .map((id) => CLI_CHECKS.find((entry) => entry.id === id))
+      .filter((entry) => entry && !cliState[entry.id].ok);
+    if (missing.length > 0) {
+      check(
+        false,
+        `${platformCheck.id} — CLI missing (${missing.map((entry) => entry.label).join(', ')})`,
+        missing.map((entry) => entry.fix).join(' then '),
+      );
+      continue;
+    }
+    try {
+      const { rows } = await platformCheck.query();
+      usable += 1;
+      check(true, `${platformCheck.id} — ${Array.isArray(rows) ? rows.length : 0} row(s) read`);
+    } catch (error) {
+      const classified = classifyFailure(error);
+      check(false, `${platformCheck.id} — ${classified.label}: ${classified.detail}`, classified.fix);
+    }
+  }
+
+  lines.push(
+    '',
+    `${usable} of ${selected.length} platform(s) usable` +
+      (failures === 0
+        ? ' — everything checks out; `token-quota` is ready.'
+        : ' — fix the [fail] items above, then run `token-quota doctor` again.'),
+    '',
+  );
+  stdout.write(`${lines.join('\n')}`);
+  return failures === 0 ? 0 : 1;
+}
+
+function oneLine(text) {
+  return String(text ?? '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line !== '' && !line.startsWith('(node:'))
+    .join(' ')
+    .slice(0, 200);
+}
+
+function baseName(path) {
+  return String(path ?? '').split(/[\\/]/).pop() ?? String(path ?? '');
+}

package/src/errors.js

@@ -0,0 +1,23 @@
+/**
+ * Raised when a platform's quota cannot be queried because a credential is missing
+ * (or present but rejected). The CLI turns this into an explicit "credential missing"
+ * table row plus a `needs credential` note, and never prints the credential value.
+ * `kind` distinguishes a missing sign-in from a missing CLI, which doctor and
+ * setup report differently (login command vs install command).
+ */
+export class MissingCredential extends Error {
+  /**
+   * @param {string} credential short name of what is missing, e.g. "Cursor access token"
+   * @param {string} howToFix one-line instruction for obtaining it
+   * @param {'credential'|'cli-missing'} [kind] `cli-missing` when the underlying
+   *   tool itself is not installed (doctor/setup then print install guidance
+   *   instead of a login flow)
+   */
+  constructor(credential, howToFix, kind = 'credential') {
+    super(`missing credential: ${credential}`);
+    this.name = 'MissingCredential';
+    this.credential = credential;
+    this.howToFix = howToFix;
+    this.kind = kind;
+  }
+}

package/src/format.js

@@ -0,0 +1,54 @@
+/** Value formatting shared by the platform fetchers. */
+
+/** Placeholder used when a value is genuinely absent from the source data. */
+export const NA = 'n/a';
+
+/** Volcengine/Ark and Bailian report quota as percentages; print one decimal at most. */
+export function formatPercent(value) {
+  if (value === null || value === undefined || !Number.isFinite(Number(value))) return NA;
+  const rounded = Math.round(Number(value) * 10) / 10;
+  return `${Number.isInteger(rounded) ? rounded : rounded.toFixed(1)}%`;
+}
+
+/** Cursor reports money in cents. */
+export function formatUsd(cents) {
+  if (cents === null || cents === undefined || !Number.isFinite(Number(cents))) return NA;
+  return `$${(Number(cents) / 100).toFixed(2)}`;
+}
+
+/** Local wall-clock timestamp, minute precision: `2026-09-19 11:30`. */
+export function formatDateTime(input) {
+  const ms = toMillis(input);
+  if (ms === null) return NA;
+  const d = new Date(ms);
+  if (Number.isNaN(d.getTime())) return NA;
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+
+/**
+ * Accepts epoch seconds, epoch milliseconds or an ISO 8601 string.
+ * Anything unparseable (including Volcengine's "no data" sentinel -1) becomes null.
+ */
+export function toMillis(input) {
+  if (input === null || input === undefined) return null;
+  if (typeof input === 'string') {
+    const parsed = Date.parse(input);
+    return Number.isNaN(parsed) ? null : parsed;
+  }
+  const value = Number(input);
+  if (!Number.isFinite(value) || value <= 0) return null;
+  // Anything below ~1e11 is seconds (1e11 ms ≈ 1973, 1e11 s ≈ year 5138).
+  return value < 1e11 ? Math.round(value * 1000) : Math.round(value);
+}
+
+/** Percentage of a whole, guarded against zero/absent totals. */
+export function percentUsed(used, total) {
+  if (!Number.isFinite(Number(used)) || !Number.isFinite(Number(total)) || Number(total) <= 0) return null;
+  return (Number(used) / Number(total)) * 100;
+}
+
+export function remainingPercent(usedPercent) {
+  if (!Number.isFinite(Number(usedPercent))) return null;
+  return Math.max(0, Math.round((100 - Number(usedPercent)) * 10) / 10);
+}

package/src/panel.js

@@ -0,0 +1,113 @@
+/**
+ * The panel itself: query every selected platform, print the table (or JSON),
+ * print the notes, and return the exit code.
+ *
+ * Contract kept from the original quota-panel: read-only queries, print and
+ * exit — no daemon, no cache, no credential writes. A platform that cannot be
+ * queried still gets its own row, and one platform's failure never affects the
+ * others. `quota-axi` is always run with `--no-credential-refresh` (see
+ * src/quota-axi.js), so nothing here can trigger an interactive re-login.
+ */
+import { MissingCredential } from './errors.js';
+import { NA } from './format.js';
+import { platforms as allPlatforms } from './platforms/index.js';
+import { renderTable } from './table.js';
+import { selectPlatforms } from './cli.js';
+
+/** Shown after the table on a first run where nothing is configured yet. */
+export const FIRST_RUN_HINT =
+  'Nothing is configured yet — run "token-quota setup" (interactive) or "token-quota doctor" (checks only).';
+
+/**
+ * Runs the selected platforms in parallel and classifies each outcome:
+ * usable data, `credentialMissing`, or `failed`.
+ * @param {Array<{id: string, label: string, query: () => Promise<{rows: Array<object>, notes?: string[]}>}>} selected
+ */
+export async function collect(selected) {
+  return Promise.all(
+    selected.map(async (platform) => {
+      try {
+        const { rows, notes } = await platform.query();
+        return { platform, rows, notes: notes ?? [], credentialMissing: false };
+      } catch (error) {
+        if (error instanceof MissingCredential) {
+          // A missing CLI is reported as its own state: the note carries the
+          // install command, which is a different fix from signing in.
+          const state = error.kind === 'cli-missing' ? 'CLI missing' : 'credential missing';
+          return {
+            platform,
+            rows: [stateRow(platform, state)],
+            notes: [`${platform.label}: ${error.credential} — ${error.howToFix}`],
+            credentialMissing: true,
+          };
+        }
+        return {
+          platform,
+          rows: [stateRow(platform, 'query failed')],
+          notes: [`${platform.label}: ${error.message}`],
+          credentialMissing: false,
+          failed: true,
+        };
+      }
+    }),
+  );
+}
+
+function stateRow(platform, state) {
+  return { platform: platform.label, plan: state, total: NA, used: NA, remaining: NA, reset: NA };
+}
+
+/**
+ * First-run guidance: only for a human watching a real terminal, and only when
+ * every selected platform is blocked on a missing credential. `--json` output
+ * and piped/redirected runs are never touched.
+ * @returns {string|null} the hint line, or null when it should not be shown
+ */
+export function firstRunHint(results, { isTTY = process.stdout.isTTY } = {}) {
+  if (!isTTY) return null;
+  if (!Array.isArray(results) || results.length === 0) return null;
+  return results.every((result) => result.credentialMissing) ? FIRST_RUN_HINT : null;
+}
+
+/**
+ * Prints the panel and returns the process exit code:
+ *  0 — at least one platform returned usable data
+ *  1 — every selected platform failed
+ *  2 — bad usage (no matching platform in `--only`)
+ */
+export async function runPanel(options = {}, io = {}) {
+  const {
+    stdout = process.stdout,
+    stderr = process.stderr,
+    isTTY = process.stdout.isTTY,
+    platforms = allPlatforms,
+  } = io;
+
+  let selected;
+  try {
+    selected = selectPlatforms(options.only, platforms);
+  } catch (error) {
+    stderr.write(`token-quota: ${error.message}\n`);
+    return 2;
+  }
+
+  const results = await collect(selected);
+  const rows = results.flatMap((result) => result.rows);
+  const notes = results.flatMap((result) => result.notes);
+
+  if (options.json) {
+    stdout.write(`${JSON.stringify({ rows, notes }, null, 2)}\n`);
+  } else {
+    stdout.write(`${renderTable(rows)}\n`);
+    if (notes.length > 0) {
+      stdout.write(`\n${notes.map((note) => `- ${note}`).join('\n')}\n`);
+    }
+    const hint = firstRunHint(results, { isTTY });
+    if (hint) stdout.write(`\n${hint}\n`);
+  }
+
+  // Missing credentials are a reported state, not a crash; only total query
+  // failure (or an empty selection) exits non-zero.
+  const anyUsable = results.some((result) => !result.failed);
+  return anyUsable ? 0 : 1;
+}

package/src/platforms/bailian.js

@@ -0,0 +1,96 @@
+/**
+ * Alibaba Cloud Bailian (阿里云百炼) Token Plan quota fetcher — quota-axi-backed.
+ *
+ * All Bailian quota data comes from the `quota-axi` CLI (see src/quota-axi.js),
+ * which in turn reads the local official Bailian CLI (`bl`) — the owner of the
+ * console session that `bl auth login --console` establishes. This module only
+ * maps the quota-axi provider result into table rows and classifies failures:
+ *
+ *  - `bl_cli_unavailable` → the Bailian CLI itself is not installed
+ *  - `bl_usage_failed`    → the `bl usage token-plan` read failed; the observed
+ *                           cause on this machine is an expired console session
+ *                           (`bl` exits 3 with "Console session is not logged in
+ *                           or has expired"). Model API keys such as
+ *                           BAILIAN_PLAN_API_KEY are inference keys and are
+ *                           rejected by the usage API, so a console session is
+ *                           the only working credential.
+ *  - anything else        → explicit error row, other platforms unaffected
+ *
+ * Bailian windows via quota-axi: `weekly` (per-week Token Plan percentage,
+ * computed by quota-axi from `per1WeekPercentage`), plus any per-model limits
+ * the payload carries.
+ */
+import { MissingCredential } from '../errors.js';
+import { NA } from '../format.js';
+import { fetchReport, findProvider, providerWindowsToRows } from '../quota-axi.js';
+
+export const id = 'bailian';
+export const label = 'bailian';
+
+/** quota-axi's provider id for Alibaba Bailian differs from this panel's platform id. */
+const QUOTA_AXI_PROVIDER_ID = 'alibaba';
+
+const HOW_TO_FIX =
+  'needs a Bailian console session: run `bl auth login --console` (one browser sign-in) ' +
+  'to refresh it. BAILIAN_PLAN_API_KEY is a model inference key and cannot read Token Plan usage';
+
+export async function query() {
+  const report = await fetchReport();
+  const provider = findProvider(report, QUOTA_AXI_PROVIDER_ID);
+  if (!provider) {
+    throw new Error(`quota-axi report contains no "${QUOTA_AXI_PROVIDER_ID}" provider`);
+  }
+  return buildRows(provider);
+}
+
+/** Maps one quota-axi alibaba provider entry into rows + notes. Exported for tests. */
+export function buildRows(provider) {
+  const state = provider?.state ?? {};
+  const windows = Array.isArray(provider?.windows) ? provider.windows : [];
+
+  if (state.status === 'fresh' || state.status === 'stale' || windows.length > 0) {
+    const rows = providerWindowsToRows(label, provider);
+    const notes = [];
+    if (state.status === 'stale') {
+      notes.push(
+        `${label}: showing stale cached data` +
+          (state.error ? ` (fresh fetch failed: ${cleanError(state.error)})` : ''),
+      );
+    }
+    notes.push(`${label}: Token Plan windows are percentages only; each window resets on its own schedule`);
+    if (rows.length === 0) {
+      rows.push(errorRow('quota-axi returned no usage windows'));
+    }
+    return { rows, notes };
+  }
+
+  const errorText = cleanError(state.error ?? 'unknown quota-axi state');
+  if (errorText.includes('bl_cli_unavailable')) {
+    throw new MissingCredential(
+      'Bailian CLI (bl)',
+      'install the official Bailian CLI (`bl`) and sign in with `bl auth login --console`',
+      'cli-missing',
+    );
+  }
+  if (errorText.includes('bl_usage_failed')) {
+    // quota-axi truncates the underlying bl error, but the dominant cause is the
+    // console session state; classify it as the credential problem it is.
+    throw new MissingCredential(
+      'Bailian console session (expired or absent — the `bl usage` read failed)',
+      HOW_TO_FIX,
+    );
+  }
+  throw new Error(`Bailian quota query failed: ${errorText}`);
+}
+
+function errorRow(message) {
+  return { platform: label, plan: message, total: NA, used: NA, remaining: NA, reset: NA };
+}
+
+/** Trims the Windows command-invocation noise quota-axi wraps failures in, keeping any prefix marker. */
+export function cleanError(text) {
+  const raw = String(text ?? '');
+  const at = raw.indexOf('Command failed:');
+  const kept = (at === -1 ? raw : raw.slice(0, at)).replace(/\s+/g, ' ').trim();
+  return (kept !== '' ? kept : 'command invocation failed').slice(0, 220);
+}

package/src/platforms/cursor.js

@@ -0,0 +1,86 @@
+/**
+ * Cursor quota fetcher — quota-axi-backed.
+ *
+ * All Cursor quota data comes from the `quota-axi` CLI (see src/quota-axi.js),
+ * which owns the credential reading (the signed-in Cursor editor's local
+ * `state.vscdb`, through the vendored `sqlite3.exe` on Windows) and the
+ * DashboardService API calls. This module only maps the quota-axi provider
+ * result into table rows and classifies its failure states:
+ *
+ *  - `auth_required`      → credential missing: open the Cursor app and sign in
+ *  - `sqlite3_unavailable`→ local sqlite3 CLI missing (the vendored one should
+ *                           prevent this; if it appears, the vendored binary
+ *                           is unusable on this machine)
+ *  - anything else        → explicit error row, other platforms unaffected
+ *
+ * Cursor windows (quota-axi ids): included_usage, auto_usage, api_usage
+ * (percent of the monthly plan pools) and spend_limit (USD credits).
+ */
+import { MissingCredential } from '../errors.js';
+import { NA } from '../format.js';
+import { fetchReport, findProvider, providerWindowsToRows } from '../quota-axi.js';
+
+export const id = 'cursor';
+export const label = 'cursor';
+
+const HOW_TO_FIX =
+  'no usable Cursor sign-in: open the Cursor editor and sign in ' +
+  '(quota-axi reads the local credential store Cursor itself keeps), then re-run';
+
+export async function query() {
+  const report = await fetchReport();
+  const provider = findProvider(report, id);
+  if (!provider) {
+    throw new Error(`quota-axi report contains no "${id}" provider`);
+  }
+  return buildRows(provider);
+}
+
+/** Maps one quota-axi cursor provider entry into rows + notes. Exported for tests. */
+export function buildRows(provider) {
+  const state = provider?.state ?? {};
+  const windows = Array.isArray(provider?.windows) ? provider.windows : [];
+
+  if (state.status === 'fresh' || state.status === 'stale' || windows.length > 0) {
+    const rows = providerWindowsToRows(label, provider);
+    const notes = [];
+    if (state.status === 'stale') {
+      notes.push(
+        `${label}: showing stale cached data` +
+          (state.error ? ` (fresh fetch failed: ${cleanError(state.error)})` : ''),
+      );
+    }
+    if (windows.some((window) => window?.id === 'spend_limit')) {
+      notes.push(`${label}: spend limit is the USD credit cap Cursor charges beyond the plan`);
+    }
+    if (rows.length === 0) {
+      rows.push(errorRow('quota-axi returned no usage windows'));
+      notes.push(`${label}: signed in, but Cursor reported no usage windows`);
+    }
+    return { rows, notes };
+  }
+
+  const errorText = cleanError(state.error ?? 'unknown quota-axi state');
+  if (state.status === 'auth_required' || /sign-in required|credentials/i.test(errorText)) {
+    throw new MissingCredential('Cursor sign-in (local credential store)', HOW_TO_FIX);
+  }
+  if (errorText.includes('sqlite3_unavailable')) {
+    throw new Error(
+      'quota-axi could not read Cursor\'s local credential store: no working sqlite3 CLI ' +
+        '(the repo-vendored vendor/sqlite3-shim/sqlite3.exe should have been used; check it exists)',
+    );
+  }
+  throw new Error(`Cursor quota query failed: ${errorText}`);
+}
+
+function errorRow(message) {
+  return { platform: label, plan: message, total: NA, used: NA, remaining: NA, reset: NA };
+}
+
+/** Trims the Windows command-invocation noise quota-axi wraps failures in, keeping any prefix marker. */
+export function cleanError(text) {
+  const raw = String(text ?? '');
+  const at = raw.indexOf('Command failed:');
+  const kept = (at === -1 ? raw : raw.slice(0, at)).replace(/\s+/g, ' ').trim();
+  return (kept !== '' ? kept : 'command invocation failed').slice(0, 220);
+}