token-quota 1.0.0

package/src/platforms/doubao.js

@@ -0,0 +1,259 @@
+/**
+ * Doubao / Volcengine Ark quota fetcher — ark-cli-backed.
+ *
+ * All Doubao quota data comes from the official `arkcli` CLI (v1.0.33+),
+ * subprocess-launched with the same pattern as the quota-axi wrapper
+ * (src/quota-axi.js): fixed argument list, bounded timeout, JSON stdout parsed
+ * even on non-zero exit, failures classified per platform. The credential is
+ * the CLI's own SSO session (`arkcli auth login volc-sso`, one browser
+ * sign-in); AK/SK pairs and DOUBAO_* model keys are never used or printed.
+ *
+ * `arkcli usage plan` emits:
+ *   { viewer: {...}, items: [ { product, edition, tier, subscribed,
+ *       periods: [ { label, used, total, percent, reset_at }, ... ] }, ... ] }
+ *
+ * Items with subscribed:false are skipped by default (one row per period of
+ * each subscribed item). A failure whose text looks like an auth problem
+ * becomes a missing-credential row naming `arkcli auth login volc-sso`.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { MissingCredential } from '../errors.js';
+import { NA, formatDateTime } from '../format.js';
+import { PACKAGES, resolveArkCliLaunch } from '../resolve-deps.js';
+
+export const id = 'doubao';
+export const label = 'doubao';
+
+const SPAWN_TIMEOUT_MS = 60_000;
+const LOGIN_COMMAND = 'arkcli auth login volc-sso';
+
+const HOW_TO_FIX = `run \`${LOGIN_COMMAND}\` (one browser SSO sign-in) to establish the Ark CLI session`;
+
+/**
+ * ark-cli's platform binary is fetched by that package's own postinstall script.
+ * When the binary is missing, the package's bin script exits with this message,
+ * and a plain reinstall of the CLI (or a rerun of its postinstall) is the fix.
+ */
+const INSTALL_FIX =
+  'install the Ark CLI with its platform binary: `npm i -g @volcengine/ark-cli` ' +
+  '(if only the bin script is present, rerun that package\'s postinstall: ' +
+  '`node node_modules/@volcengine/ark-cli/scripts/postinstall.js`)';
+
+/** Raised when the arkcli binary itself cannot be used at all. */
+class ArkCliUnavailable extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ArkCliUnavailable';
+  }
+}
+
+/**
+ * Resolves how to launch arkcli:
+ *  1. `ARKCLI_BIN` env var — path to a launchable binary
+ *  2. this package's own dependency tree (@volcengine/ark-cli): the platform
+ *     binary when its postinstall download succeeded, else its bin script
+ *     (`scripts/run.js`, which needs node in front of it)
+ *  3. the platform executable installed next to the running node binary
+ *     (`<node dir>/node_modules/@volcengine/ark-cli/bin/arkcli-windows-amd64.exe`)
+ *  4. plain `arkcli` from PATH (works via execvp on POSIX)
+ * `resolveDependency` is injectable so the ordering above can be tested.
+ */
+export function resolveLaunch({
+  env = process.env,
+  execPath = process.execPath,
+  platform = process.platform,
+  arch = process.arch,
+  resolveDependency = resolveArkCliLaunch,
+} = {}) {
+  const args = ['usage', 'plan'];
+
+  const bin = (env.ARKCLI_BIN ?? '').trim();
+  if (bin !== '') return { command: bin, args };
+
+  const dependency = resolveDependency({ platform, arch });
+  if (dependency) {
+    return dependency.nodeEntry
+      ? { command: execPath, args: [dependency.command, ...args] }
+      : { command: dependency.command, args };
+  }
+
+  if (platform === 'win32') {
+    const machine = arch === 'arm64' ? 'arm64' : 'amd64';
+    const exe = join(
+      dirname(execPath),
+      'node_modules',
+      '@volcengine',
+      'ark-cli',
+      'bin',
+      `arkcli-windows-${machine}.exe`,
+    );
+    if (existsSync(exe)) return { command: exe, args };
+    return null;
+  }
+  return { command: 'arkcli', args };
+}
+
+export async function query() {
+  const launch = resolveLaunch();
+  if (!launch) throw missingArkCliError();
+  const report = await runArkCli(launch);
+  return buildRows(report);
+}
+
+/** The error raised when no arkcli executable can be resolved. Exported for tests. */
+export function missingArkCliError() {
+  return new MissingCredential(
+    'Ark CLI (arkcli) executable',
+    `${INSTALL_FIX}, or point ARKCLI_BIN at its executable`,
+    'cli-missing',
+  );
+}
+
+function runArkCli(launch) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(launch.command, launch.args, {
+      timeout: SPAWN_TIMEOUT_MS,
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+    });
+    child.on('error', (error) => {
+      reject(new ArkCliUnavailable(`arkcli could not be launched: ${error.message}`));
+    });
+    child.on('close', () => {
+      // Prefer a parseable stdout over the exit code: arkcli may exit non-zero
+      // for per-command complaints while still emitting a JSON envelope.
+      try {
+        resolvePromise(parseReport(stdout, stderr));
+      } catch (error) {
+        reject(error);
+      }
+    });
+  });
+}
+
+/** Parses `arkcli usage plan` stdout; exported for tests. */
+export function parseReport(stdout, stderr = '') {
+  let report;
+  try {
+    report = JSON.parse(stdout);
+  } catch {
+    const detail = firstMeaningfulLine(stderr) || firstMeaningfulLine(stdout) || 'no output';
+    if (/binary not found/i.test(`${detail}\n${stderr}`)) {
+      throw new MissingCredential('Ark CLI (arkcli) platform binary', INSTALL_FIX, 'cli-missing');
+    }
+    if (/not logged in|login required|unauthorized|auth/i.test(detail)) {
+      throw new MissingCredential('Ark CLI SSO session (absent or expired)', HOW_TO_FIX);
+    }
+    throw new Error(`arkcli usage plan did not produce JSON (${detail})`);
+  }
+  if (!report || !Array.isArray(report.items)) {
+    throw new Error('arkcli usage plan report has no items array');
+  }
+  return report;
+}
+
+/**
+ * Turns the usage-plan payload into table rows.
+ * Exported for tests: no subprocess needed.
+ */
+export function buildRows(report) {
+  const rows = [];
+  const notes = [];
+  let skipped = 0;
+
+  for (const item of Array.isArray(report?.items) ? report.items : []) {
+    if (!item || typeof item !== 'object') continue;
+    if (item.subscribed === false) {
+      skipped += 1;
+      continue;
+    }
+    const planLabel = describeItem(item);
+    const periods = Array.isArray(item.periods) ? item.periods : [];
+    if (periods.length === 0) {
+      rows.push(row(`${planLabel} — no usage windows reported`));
+      continue;
+    }
+    for (const period of periods) {
+      if (!period || typeof period !== 'object') continue;
+      const windowName = text(period.label) || 'window';
+      const usedPct = usedPercentValue(period);
+      rows.push(
+        row(`${planLabel} — ${windowName}`, {
+          total: usedPct === null ? NA : pct(100),
+          used: usedPct === null ? NA : pct(usedPct),
+          remaining: usedPct === null ? NA : pct(Math.max(0, 100 - usedPct)),
+          reset: formatDateTime(period.reset_at),
+        }),
+      );
+    }
+  }
+
+  if (rows.length === 0) {
+    rows.push(row('no active Ark plan subscription'));
+    notes.push(
+      `${label}: arkcli reported no subscribed plan items — check \`arkcli usage plan\` and \`${LOGIN_COMMAND}\``,
+    );
+  }
+  if (skipped > 0) {
+    notes.push(`${label}: ${skipped} unsubscribed plan item(s) hidden (subscribed:false)`);
+  }
+
+  return { rows, notes };
+}
+
+function describeItem(item) {
+  const product = text(item.product) || 'unknown-plan';
+  const edition = text(item.edition);
+  const tier = text(item.tier);
+  const parts = [product, edition].filter(Boolean).join(' ');
+  return tier ? `${parts} (${tier})` : parts || 'Ark plan';
+}
+
+function row(plan, values = {}) {
+  return { platform: label, plan, total: NA, used: NA, remaining: NA, reset: NA, ...values };
+}
+
+/**
+ * All platforms display percentages, so doubao windows do too: arkcli reports
+ * `percent` directly, else it is derived from used/total. `remaining` is
+ * 100 minus the ROUNDED used value so used + remaining always reads as 100%.
+ */
+function pct(value) {
+  return `${Math.round(value * 100) / 100}%`;
+}
+
+function usedPercentValue(period) {
+  const percent = Number(period?.percent);
+  if (Number.isFinite(percent)) return Math.max(0, percent);
+  const total = Number(period?.total);
+  const used = Number(period?.used);
+  if (Number.isFinite(total) && Number.isFinite(used) && total > 0) {
+    return Math.max(0, (used / total) * 100);
+  }
+  return null;
+}
+
+function text(value) {
+  return typeof value === 'string' && value.trim() !== '' ? value.trim() : '';
+}
+
+function firstMeaningfulLine(raw) {
+  return (
+    String(raw ?? '')
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line !== '')
+      .find((line) => !line.startsWith('(node:')) ?? ''
+  ).slice(0, 220);
+}

package/src/platforms/index.js

@@ -0,0 +1,10 @@
+/** The three platforms this panel knows about, in display order (doubao, bailian, cursor). */
+import * as cursor from './cursor.js';
+import * as doubao from './doubao.js';
+import * as bailian from './bailian.js';
+
+export const platforms = [doubao, bailian, cursor];
+
+export function findPlatform(id) {
+  return platforms.find((platform) => platform.id === id);
+}

package/src/quota-axi.js

@@ -0,0 +1,255 @@
+/**
+ * quota-axi integration — the single data source for the Cursor and Alibaba
+ * (Bailian) platform rows.
+ *
+ * Per the project contract, quota-axi owns all credential reading, API calls
+ * and normalization for those two providers; this module only runs it as a
+ * subprocess and maps its JSON windows into table rows. Doubao/Volcengine is
+ * the only self-built fetcher and does not go through here.
+ *
+ * Invocation details that were verified against quota-axi 0.1.47:
+ *  - `quota-axi --provider cursor,alibaba --json` prints a JSON report
+ *    `{ generatedAt, schemaVersion, providers: [...] }`; a provider-level
+ *    failure is reported inside `providers[].state` while the process still
+ *    prints valid JSON (it may exit non-zero when any provider fails), so a
+ *    parseable stdout is always preferred over the exit code.
+ *  - `--no-credential-refresh` keeps the read strictly read-only: no expired
+ *    session is ever renewed by an interactive vendor CLI flow.
+ *  - The cursor provider reads the signed-in editor's `state.vscdb` through
+ *    the `sqlite3` CLI. On Windows only a real `sqlite3.exe` is executable
+ *    from a spawned process, so this repo vendors one under
+ *    `vendor/sqlite3-shim/` and prepends that directory to PATH for the
+ *    subprocess only. Nothing is installed globally and the user's own
+ *    environment is never modified.
+ *
+ * The subprocess PATH also gets the dependency tree's `.bin` shims: quota-axi
+ * resolves the Bailian CLI (`bl`) through PATH on its own, and npm does not put
+ * a nested dependency's shims on the user's PATH.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { commandLine } from './cli.js';
+import { formatDateTime, formatPercent, formatUsd, NA } from './format.js';
+import { dependencyBinDirs, PACKAGES, resolveDependencyCli } from './resolve-deps.js';
+
+/** The providers this panel consumes through quota-axi, in CLI flag form. */
+export const QUOTA_AXI_PROVIDERS = 'cursor,alibaba';
+
+const SPAWN_TIMEOUT_MS = 90_000;
+
+/** Raised when quota-axi itself cannot be used at all (missing/undecodable). */
+export class QuotaAxiUnavailable extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'QuotaAxiUnavailable';
+  }
+}
+
+/** Absolute path of the vendored sqlite3 directory (Windows: contains sqlite3.exe). */
+export function shimDir(importMetaUrl = import.meta.url) {
+  return resolve(dirname(fileURLToPath(importMetaUrl)), '..', 'vendor', 'sqlite3-shim');
+}
+
+/** PATH entries prepended for the quota-axi subprocess only. */
+function subprocessPathEntries() {
+  return [shimDir(), ...dependencyBinDirs()];
+}
+
+/**
+ * Resolves how to launch quota-axi:
+ *  1. `QUOTA_AXI_BIN` env var — absolute path to quota-axi.js or a launchable binary
+ *  2. this package's own dependency tree (`npm i -g token-quota`, `npx token-quota`),
+ *     using quota-axi's declared bin entry
+ *  3. the copy installed next to the running node binary (`<node dir>/node_modules/quota-axi`)
+ *  4. plain `quota-axi` from PATH (works via execvp on POSIX)
+ * Returns { command, args } or null when nothing usable is found.
+ * `resolveDependency` is injectable so the ordering above can be tested.
+ */
+export function resolveLaunch({
+  env = process.env,
+  execPath = process.execPath,
+  platform = process.platform,
+  arch = process.arch,
+  resolveDependency = resolveDependencyCli,
+} = {}) {
+  const entryArgs = ['--json', '--no-credential-refresh', '--provider', QUOTA_AXI_PROVIDERS];
+
+  const bin = (env.QUOTA_AXI_BIN ?? '').trim();
+  if (bin !== '') return { command: bin, args: entryArgs };
+
+  const dependency = resolveDependency(PACKAGES.quotaAxi, { execPath, platform, arch });
+  if (dependency) {
+    return { command: dependency.command, args: [...dependency.prefixArgs, ...entryArgs] };
+  }
+
+  const siblingEntry = join(
+    dirname(execPath),
+    'node_modules',
+    'quota-axi',
+    'dist',
+    'bin',
+    'quota-axi.js',
+  );
+  if (existsSync(siblingEntry)) return { command: execPath, args: [siblingEntry, ...entryArgs] };
+
+  if (platform === 'win32') {
+    // Spawn cannot resolve quota-axi.cmd without a shell; the npm shim next to
+    // node.exe launches it with the same node binary, so try that path shape.
+    const cmdShim = join(dirname(execPath), 'quota-axi.cmd');
+    if (existsSync(cmdShim)) return { command: cmdShim, args: entryArgs, shell: true };
+    return null;
+  }
+  return { command: 'quota-axi', args: entryArgs };
+}
+
+/** Parses quota-axi stdout; returns the report object or throws QuotaAxiUnavailable. */
+export function parseReport(stdout, stderr = '') {
+  let report;
+  try {
+    report = JSON.parse(stdout);
+  } catch {
+    const detail = firstLine(stderr) || firstLine(stdout) || 'no output';
+    throw new QuotaAxiUnavailable(`quota-axi did not produce a JSON report (${detail})`);
+  }
+  if (!report || !Array.isArray(report.providers)) {
+    throw new QuotaAxiUnavailable('quota-axi report has no providers array');
+  }
+  return report;
+}
+
+export function findProvider(report, id) {
+  return report.providers.find((provider) => provider?.provider === id) ?? null;
+}
+
+let reportPromise = null;
+
+/**
+ * Single-flight report fetch shared by both quota-axi-backed platforms, so one
+ * panel run spawns quota-axi exactly once. Memoized per process.
+ */
+export function fetchReport(launch = resolveLaunch()) {
+  if (reportPromise) return reportPromise;
+  reportPromise = spawnReport(launch).catch((error) => {
+    reportPromise = null; // allow a later call in the same process to retry
+    throw error;
+  });
+  return reportPromise;
+}
+
+function spawnReport(launch) {
+  if (!launch) {
+    return Promise.reject(
+      new QuotaAxiUnavailable(
+        'quota-axi was not found (install it globally, or point QUOTA_AXI_BIN at its entry script)',
+      ),
+    );
+  }
+  return new Promise((resolvePromise, reject) => {
+    const spawnOptions = {
+      timeout: SPAWN_TIMEOUT_MS,
+      env: {
+        ...process.env,
+        // Give the subprocess the vendored sqlite3.exe (cursor state-vscdb
+        // source) and the dependency tree's `.bin` shims (the `bl` CLI lookup),
+        // without touching the user's own environment.
+        PATH: [...subprocessPathEntries(), process.env.PATH ?? ''].join(
+          process.platform === 'win32' ? ';' : ':',
+        ),
+      },
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    };
+    // A `.cmd` npm shim can only be launched through a shell, so that path uses
+    // one composed line (passing args with `shell` is deprecated).
+    const child = launch.shell
+      ? spawn(commandLine(launch.command, launch.args), { ...spawnOptions, shell: true })
+      : spawn(launch.command, launch.args, spawnOptions);
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+    });
+    child.on('error', (error) => {
+      reject(new QuotaAxiUnavailable(`quota-axi could not be launched: ${error.message}`));
+    });
+    child.on('close', () => {
+      // Exit code is intentionally ignored: quota-axi exits non-zero when any
+      // provider fails while still printing the full per-provider JSON report.
+      try {
+        resolvePromise(parseReport(stdout, stderr));
+      } catch (error) {
+        reject(error);
+      }
+    });
+  });
+}
+
+/**
+ * Maps one quota-axi provider's windows into table rows.
+ * Two window shapes exist (schemaVersion 5):
+ *  - percent windows: percentRemaining (preferred), percentUsed, resetsAt
+ *  - credit/USD windows: spentUsd + limitUsd (kind "credits")
+ * `platformLabel` goes into the PLATFORM column; the plan name prefixes the PLAN column.
+ */
+export function providerWindowsToRows(platformLabel, provider) {
+  const plan = planName(provider);
+  return (provider?.windows ?? []).map((window) => {
+    if (window?.kind === 'credits' || window?.limitUsd !== undefined) {
+      const limit = finiteOrNull(window?.limitUsd);
+      const spent = finiteOrNull(window?.spentUsd);
+      const remaining = limit !== null && spent !== null ? Math.max(0, limit - spent) : null;
+      return {
+        platform: platformLabel,
+        plan: `${plan} — ${windowLabel(window)}`,
+        total: centsOrNa(limit),
+        used: centsOrNa(spent),
+        remaining: centsOrNa(remaining),
+        reset: formatDateTime(window?.resetsAt),
+      };
+    }
+    const used = finiteOrNull(window?.percentUsed);
+    const remaining = finiteOrNull(window?.percentRemaining);
+    return {
+      platform: platformLabel,
+      plan: `${plan} — ${windowLabel(window)}`,
+      total: '100%',
+      used: formatPercent(used ?? (remaining === null ? null : Math.round((100 - remaining) * 10) / 10)),
+      remaining: formatPercent(remaining ?? (used === null ? null : Math.max(0, Math.round((100 - used) * 10) / 10))),
+      reset: formatDateTime(window?.resetsAt),
+    };
+  });
+}
+
+export function planName(provider) {
+  return provider?.plan ?? provider?.label ?? 'unknown plan';
+}
+
+function windowLabel(window) {
+  return String(window?.label ?? window?.id ?? 'usage');
+}
+
+function finiteOrNull(value) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** formatUsd takes cents; quota-axi credit windows carry whole dollars. */
+function centsOrNa(usd) {
+  return usd === null ? NA : formatUsd(Math.round(usd * 100));
+}
+
+function firstLine(text) {
+  return (
+    String(text ?? '')
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line !== '')
+      .find((line) => !line.startsWith('(node:')) ?? ''
+  );
+}