token-quota 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jipengfei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# token-quota
+
+One compact table of the remaining token-plan / purchased-package quota for three
+platforms: **Doubao (Volcengine Ark)**, **Alibaba Bailian** and **Cursor**.
+
+```
+$ token-quota
+PLATFORM  PLAN/PACKAGE                            TOTAL  USED    REMAINING  RESET
+--------  --------------------------------------  -----  ------  ---------  ----------------
+doubao    agent-plan personal (medium) — 5h       100%   2.08%   97.92%     2026-09-19 16:29
+doubao    agent-plan personal (medium) — weekly   100%   57.53%  42.47%     2026-09-21 00:00
+doubao    agent-plan personal (medium) — monthly  100%   55.99%  44.01%     2026-09-28 23:59
+bailian   Alibaba Coding Plan — week              100%   64.4%   35.6%      2026-09-24 06:00
+cursor    Pro — included usage                    100%   17%     83%        2026-09-30 19:39
+cursor    Pro — auto usage                        100%   15%     85%        2026-09-30 19:39
+cursor    Pro — API usage                         100%   42%     58%        2026-09-30 19:39
+cursor    Pro — spend limit                       $1.00  $0.00   $1.00      2026-09-30 19:39
+```
+
+Read-only by design: **it queries, prints, exits**. No daemon, no background
+refresh, no cache, no purchase or top-up action. It never prints, writes or
+commits a credential value — credentials are only ever read by the vendor CLIs'
+own credential stores. One platform failing never affects the others, and a
+missing sign-in is a reported state, not a crash.
+
+## Install
+
+Requires **Node.js >= 20**.
+
+```
+npm install -g token-quota     # then: token-quota
+npx token-quota                # one-off, no install
+```
+
+The three data-source CLIs (`quota-axi`, `bailian-cli`, `@volcengine/ark-cli`)
+are declared dependencies of this package, so they arrive with it — there is
+nothing to install by hand.
+
+## Quick start
+
+```
+token-quota                    # the table
+token-quota --json             # machine-readable { rows, notes }
+token-quota --only cursor,doubao
+token-quota setup              # sign in to the platforms that are not configured
+token-quota doctor             # read-only check of what is missing
+token-quota --help
+token-quota --version
+```
+
+First run on a fresh machine: `token-quota setup` walks platform by platform and
+runs each platform's own login command. If everything is already signed in, just
+run `token-quota`.
+
+## Commands
+
+| Command | What it does |
+| ------- | ------------ |
+| *(none)* | Prints the quota table (or `--json`) and exits. |
+| `setup` | Interactive sign-in wizard. Checks each selected platform, explains what is missing, runs that platform's own login command (`arkcli auth login volc-sso`, `bl auth login --console`) or asks you to sign in inside the Cursor editor, then re-checks and prints the final panel. Writes no file and stores no credential — every session stays owned by the tool that created it. Non-interactive runs (`token-quota setup | cat`) only print the manual steps and exit 0. |
+| `doctor` | Read-only health check: Node version, the three data-source CLIs (`--version`), the sqlite3 the Cursor row needs, then one real read-only query per platform, each classified as working / not logged in / CLI missing / query failed, with the exact fix command for anything red. It never starts a login. Exits 0 only when everything is green. |
+
+Both subcommands accept `--only <list>`, like the panel.
+
+```
+$ token-quota doctor
+token-quota doctor — read-only checks; nothing is signed in, written or refreshed
+
+Environment
+  [ok] node v24.20.0 (requires >= 20)
+  [ok] sqlite3 (vendored for Windows) — .../vendor/sqlite3-shim/sqlite3.exe
+
+Data-source CLIs
+  [ok] quota-axi 0.1.47 — package dependency: node .../quota-axi/dist/bin/quota-axi.js
+  [ok] bailian CLI (bl) 1.24.0 — package dependency: node .../bailian-cli/dist/bailian.mjs
+  [ok] arkcli (Volcengine Ark) 1.0.33 — package dependency: .../ark-cli/bin/arkcli-windows-amd64.exe
+
+Platforms (real read-only queries)
+  [ok] doubao — 3 row(s) read
+  [ok] bailian — 1 row(s) read
+  [ok] cursor — 5 row(s) read
+
+3 of 3 platform(s) usable — everything checks out; `token-quota` is ready.
+```
+
+## Output
+
+| Column      | Meaning                                                                   |
+| ----------- | ------------------------------------------------------------------------- |
+| `PLATFORM`  | `doubao`, `bailian` or `cursor`                                           |
+| `PLAN`      | The purchased plan/package, plus the usage window the row describes        |
+| `TOTAL`     | The window's size (`100%` for percentage meters, USD for credit meters)    |
+| `USED`      | How much of that window has been consumed                                  |
+| `REMAINING` | What is left (`TOTAL - USED`)                                              |
+| `RESET`     | When the window resets/expires, in local time (`n/a` when not reported)    |
+
+A platform that cannot be queried still gets its row, with an explicit
+`credential missing` or `query failed` state and a note naming the exact
+credential or cause.
+
+## Data sources and credentials
+
+| Platform | Source | Credentials |
+| -------- | ------ | ----------- |
+| Doubao (Volcengine Ark) | **ark-cli** (`arkcli usage plan`) | an Ark CLI SSO session from `arkcli auth login volc-sso` (one browser SSO sign-in). AK/SK pairs and `DOUBAO_*` model keys are not used and never printed. |
+| Alibaba Bailian | **quota-axi** (`--provider alibaba`), which reads the local official Bailian CLI (`bl`) | a Bailian **console session** from `bl auth login --console` (one browser sign-in). `BAILIAN_PLAN_API_KEY` is a model inference key and is rejected by the usage API. |
+| Cursor | **quota-axi** (`--provider cursor`) | the Cursor editor's own local sign-in store (sign in to the app once). On Windows quota-axi needs the `sqlite3` CLI to read it — see below. |
+
+Credentials are only ever read from the config stores `quota-axi` and the
+platform CLIs already own. `token-quota` never prints, logs or writes secret
+values, and `quota-axi` is always run with `--no-credential-refresh`, so no read
+can trigger an interactive re-login flow.
+
+`QUOTA_AXI_BIN` and `ARKCLI_BIN` override how the two data-source CLIs are
+launched (absolute path to the entry script or binary); they are meant for
+development against a checkout, not for normal use.
+
+## Doubao quota granularity
+
+Doubao quota is whatever `arkcli usage plan` reports: one row per usage period
+(`5h`, `weekly`, `monthly`) of each subscribed plan item (`product edition
+(tier)`). Items marked `subscribed:false` are hidden by default (the row count
+is noted). If the SSO session is absent or expired, the doubao row reports
+`credential missing` and names `arkcli auth login volc-sso`.
+
+## Why vendor/sqlite3-shim exists
+
+quota-axi's Cursor provider reads the signed-in editor's `state.vscdb` by
+spawning the `sqlite3` CLI. On Windows, a spawned process can only execute a
+real `sqlite3.exe` (`.cmd` wrappers are invisible to it), and many machines do
+not have sqlite3 installed. This package therefore vendors the official
+public-domain `sqlite3.exe` (from sqlite.org, sqlite-tools-win-x64) in
+`vendor/sqlite3-shim/` and prepends that directory to `PATH` **only for the
+quota-axi subprocess**. Nothing is installed globally and the user's own
+environment is untouched. `token-quota doctor` reports whether it is present;
+if the vendored binary is missing or unusable, the cursor row says so explicitly.
+On macOS/Linux quota-axi uses the system `sqlite3` (doctor checks that too).
+
+## Exit codes
+
+- `0` — at least one platform returned usable data (missing credentials are a
+  reported state, not a crash); for `doctor`, every check is green
+- `1` — every selected platform failed (for `doctor`, at least one check failed)
+- `2` — bad usage (unknown argument or command, empty/unmatched `--only` list)
+
+## Development
+
+No build step, no bundler: plain ESM, `node:test`, and the three runtime
+dependencies the panel actually shells out to.
+
+```
+npm run quota -- --json     # run from a checkout (== node bin/token-quota.js)
+npm run doctor
+npm test                    # node --test
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/token-quota.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * token-quota — one compact table of remaining token-plan / package quota.
+ *
+ * Usage:
+ *   token-quota                      # or: npx token-quota
+ *   token-quota --json               # machine-readable
+ *   token-quota --only cursor,doubao
+ *   token-quota setup                # sign-in wizard (interactive)
+ *   token-quota doctor               # read-only health check
+ *
+ * Read-only: it queries the platforms and prints values. It never writes
+ * credentials, never prints them, and never buys, tops up or changes anything.
+ * The only command that touches a vendor login is `setup`, which runs the
+ * platform's own login command and stores nothing itself.
+ */
+import { parseArgs, UsageError, VERSION } from '../src/cli.js';
+import { runDoctor } from '../src/doctor.js';
+import { runPanel } from '../src/panel.js';
+import { platforms } from '../src/platforms/index.js';
+import { runSetup } from '../src/setup.js';
+
+const USAGE = `token-quota — remaining token-plan / package quota for Cursor, Doubao (Volcengine Ark) and Alibaba Bailian
+
+Usage: token-quota [--json] [--only <platform,...>] [--help] [--version]
+       token-quota setup  [--only <platform,...>]
+       token-quota doctor [--only <platform,...>]
+
+Commands:
+  (no command)         print the quota table and exit
+  setup                interactive sign-in wizard: checks each platform and, for
+                       the ones that are not signed in, explains what is needed
+                       and runs that platform's own login command; finishes by
+                       printing the panel. Writes no file, stores no credential.
+  doctor               read-only health check: Node version, the three
+                       data-source CLIs, sqlite3, and one real read-only query
+                       per platform, each classified and paired with its fix.
+                       Never starts a login. Exits 0 only when everything is green.
+
+Options:
+  --json               print { rows, notes } as JSON instead of a table
+  --only <list>        restrict to some platforms: ${platforms.map((p) => p.id).join(', ')}
+  --help               show this help
+  --version            print the installed version
+
+Data sources:
+  cursor   quota-axi — signed-in Cursor usage; the credential is the local
+           store the Cursor editor keeps
+  bailian  quota-axi — reads Token Plan usage through the local official
+           Bailian CLI (bl)
+  doubao   ark-cli (arkcli) — official Volcengine Ark usage-plan read
+
+All three CLIs come with this package, so there is nothing to install by hand;
+quota-axi is always run with --no-credential-refresh, so no read can trigger a
+re-login.
+
+Credentials (never printed, never written, never refreshed):
+  cursor   sign in to the Cursor editor; quota-axi reads the local credential
+           store Cursor itself keeps (on Windows this package ships
+           vendor/sqlite3-shim/sqlite3.exe for that read)
+  bailian  run \`bl auth login --console\` once; BAILIAN_PLAN_API_KEY is a model
+           inference key and cannot read Token Plan usage
+  doubao   run \`arkcli auth login volc-sso\` once (one browser SSO sign-in);
+           AK/SK pairs and DOUBAO_* model keys are not used
+
+New here? \`token-quota setup\` signs you in platform by platform, and
+\`token-quota doctor\` reports what is missing without changing anything.
+
+Exit codes:
+  0  at least one platform returned usable data (doctor: every check green)
+  1  every selected platform failed (doctor: at least one check failed)
+  2  bad usage
+`;
+
+async function main(argv = process.argv.slice(2)) {
+  let options;
+  try {
+    options = parseArgs(argv);
+  } catch (error) {
+    if (!(error instanceof UsageError)) throw error;
+    process.stderr.write(`token-quota: ${error.message}\n\nrun \`token-quota --help\` for usage\n`);
+    return 2;
+  }
+
+  if (options.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (options.version) {
+    process.stdout.write(`${VERSION}\n`);
+    return 0;
+  }
+  if (options.command === 'doctor') return runDoctor(options);
+  if (options.command === 'setup') return runSetup(options);
+  return runPanel(options);
+}
+
+main()
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((error) => {
+    process.stderr.write(`token-quota: ${error.message}\n`);
+    process.exitCode = 1;
+  });

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "token-quota",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "One compact table of remaining token-plan / package quota for Cursor, Doubao (Volcengine Ark) and Alibaba Bailian — read-only, no daemon",
+  "bin": {
+    "token-quota": "bin/token-quota.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "vendor/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "quota": "node bin/token-quota.js",
+    "doctor": "node bin/token-quota.js doctor",
+    "setup": "node bin/token-quota.js setup",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@volcengine/ark-cli": "^1.0.33",
+    "bailian-cli": "^1.24.0",
+    "quota-axi": "^0.1.47"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jibuji/token-quota.git"
+  },
+  "homepage": "https://github.com/jibuji/token-quota#readme",
+  "bugs": {
+    "url": "https://github.com/jibuji/token-quota/issues"
+  },
+  "keywords": [
+    "quota",
+    "token-plan",
+    "cli",
+    "cursor",
+    "doubao",
+    "volcengine-ark",
+    "bailian",
+    "dashscope"
+  ],
+  "license": "MIT"
+}

package/src/cli.js

@@ -0,0 +1,92 @@
+/**
+ * Shared command-line plumbing: argument parsing, platform selection and the
+ * installed version. Every subcommand (panel, doctor, setup) parses its
+ * arguments through `parseArgs` so the flags behave identically.
+ *
+ * Deliberately knows nothing about the platform list (callers pass theirs in),
+ * so this module stays a leaf of the import graph.
+ */
+import { readFileSync } from 'node:fs';
+
+/** Installed package version (read from this package's own package.json). */
+export const VERSION = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).version;
+
+/** Subcommands that take over instead of printing the panel. */
+export const COMMANDS = ['setup', 'doctor'];
+
+/** Bad usage — the CLI maps this to exit code 2. */
+export class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UsageError';
+  }
+}
+
+/**
+ * Parses argv into `{ command, json, only, help, version }`.
+ * Throws UsageError on anything unknown or incomplete.
+ */
+export function parseArgs(argv = []) {
+  const options = { command: null, json: false, only: null, help: false, version: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--json') options.json = true;
+    else if (arg === '--help' || arg === '-h') options.help = true;
+    else if (arg === '--version' || arg === '-v') options.version = true;
+    else if (arg === '--only') {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith('-')) {
+        throw new UsageError('--only needs a comma-separated platform list');
+      }
+      options.only = parseOnly(value);
+      i += 1;
+    } else if (arg.startsWith('--only=')) {
+      options.only = parseOnly(arg.slice('--only='.length));
+    } else if (arg.startsWith('-')) {
+      throw new UsageError(`unknown argument: ${arg}`);
+    } else if (options.command === null) {
+      if (!COMMANDS.includes(arg)) {
+        throw new UsageError(`unknown command: ${arg} (expected ${COMMANDS.join(' or ')})`);
+      }
+      options.command = arg;
+    } else {
+      throw new UsageError(`unexpected argument: ${arg}`);
+    }
+  }
+  return options;
+}
+
+/** `cursor,doubao` → ['cursor', 'doubao']. */
+export function parseOnly(value) {
+  return String(value ?? '')
+    .split(',')
+    .map((name) => name.trim())
+    .filter(Boolean);
+}
+
+/** Selected platforms for an `--only` list; throws UsageError when nothing matches. */
+export function selectPlatforms(only, available = []) {
+  if (!only || only.length === 0) return available;
+  const selected = available.filter((platform) => only.includes(platform.id));
+  if (selected.length === 0) {
+    throw new UsageError(
+      `no matching platform in --only ${only.join(',')} (known: ${available
+        .map((platform) => platform.id)
+        .join(', ')})`,
+    );
+  }
+  return selected;
+}
+
+/**
+ * `cmd --flag "arg with spaces"` — a single line for the `shell: true` launch
+ * path Windows needs for `.cmd` npm shims (passing args together with `shell`
+ * is deprecated). Only fixed flags are ever built here, never user input.
+ */
+export function commandLine(command, args = []) {
+  return [command, ...args]
+    .map((part) => (/\s/.test(String(part)) ? `"${part}"` : String(part)))
+    .join(' ');
+}