@emesoft/tokenhub 0.3.0 → 0.4.0

package/README.md

@@ -4,12 +4,13 @@ Pair Claude Code on this machine with a [TokenHub](https://tokenhub.aimpact.io.v
 
 ```
 npx @emesoft/tokenhub connect https://tokenhub.aimpact.io.vn
+npx @emesoft/tokenhub connect https://tokenhub.aimpact.io.vn --no-statusline
 npx @emesoft/tokenhub usage
 npx @emesoft/tokenhub dashboard
 npx @emesoft/tokenhub disconnect
 ```
 
-`connect` prints a short code and opens your browser. Confirm the code on the pool's member site and the CLI writes `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` into `~/.claude/settings.json` (or `$CLAUDE_CONFIG_DIR/settings.json`). Other settings are kept, and the previous file is saved as `settings.json.bak`. Each paired machine gets its own key, which you can revoke on the Keys page.
+`connect` prints a short code and opens your browser. Confirm the code on the pool's member site and the CLI writes `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` into `~/.claude/settings.json` (or `$CLAUDE_CONFIG_DIR/settings.json`). It also adds a `statusLine` that shows today's spend and credit under the Claude Code prompt (pass `--no-statusline` to skip it; a `statusLine` you already had is left alone). Other settings are kept, and the previous file is saved as `settings.json.bak`. Each paired machine gets its own key, which you can revoke on the Keys page.
 
 `usage` shows today's and this week's spend against your limits, your credit and the pool's health (`--json` for the raw report). It exits 2 when the pool would currently refuse your requests (out of credit or budget reached).
 
@@ -17,7 +18,7 @@ npx @emesoft/tokenhub disconnect
 
 Requests to the pool carry your key and one extra header, `x-tokenhub-cli: <version>` (this CLI's version), and nothing else.
 
-`disconnect` removes only those two entries.
+`disconnect` removes only those two entries and the TokenHub `statusLine`.
 
 If `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY` is set in your shell, it overrides `settings.json`.
 

package/bin/tokenhub.js

@@ -8,11 +8,13 @@ import { fetchUsage, formatUsage, resolveCredentials } from "../lib/usage.js";
 const HELP = `tokenhub - pair Claude Code with a TokenHub pool
 
 Usage:
-  tokenhub connect <poolUrl>   Pair this machine and write ~/.claude/settings.json
+  tokenhub connect <poolUrl> [--no-statusline]
+                               Pair this machine and write ~/.claude/settings.json, including the status line
+                               (today's spend under the prompt) unless --no-statusline
   tokenhub usage [--json]      Show today's and this week's spend, credit and pool health
   tokenhub dashboard [--interval <sec>] [--once]
                                Live full-screen view of spend, pool health and recent requests (q quits)
-  tokenhub disconnect          Remove the pool entries from settings.json
+  tokenhub disconnect          Remove the pool entries and the status line from settings.json
   tokenhub --help | --version
 `;
 
@@ -22,7 +24,9 @@ Usage:
  * @returns {Promise<number>} Process exit code.
  */
 async function main(argv) {
-  const [command, arg] = argv;
+  const [command, ...rest] = argv;
+  const flags = rest.filter((item) => item.startsWith("--"));
+  const arg = rest.find((item) => !item.startsWith("--"));
   if (!command || command === "--help" || command === "-h" || command === "help") {
     console.log(HELP);
     return command ? 0 : 1;
@@ -40,7 +44,7 @@ async function main(argv) {
     }
     const controller = new AbortController();
     process.once("SIGINT", () => controller.abort());
-    return runConnect({ poolUrl: arg, settingsFile: file, signal: controller.signal });
+    return runConnect({ poolUrl: arg, settingsFile: file, signal: controller.signal, statusLine: !flags.includes("--no-statusline") });
   }
   if (command === "usage") {
     try {
@@ -50,7 +54,7 @@ async function main(argv) {
         return 1;
       }
       const report = await fetchUsage(credentials.baseUrl, credentials.key);
-      console.log(arg === "--json" ? JSON.stringify(report, null, 2) : formatUsage(report));
+      console.log(flags.includes("--json") ? JSON.stringify(report, null, 2) : formatUsage(report));
       return report.blocked ? 2 : 0;
     } catch (error) {
       console.error(`Error: ${error.message}`);

package/lib/dashboard.js

@@ -151,13 +151,16 @@ function blockedText(report, timeZone) {
   return `BLOCKED: ${period} budget reached${lifts}.`;
 }
 
+const MAX_MODEL_WIDTH = 24;
+const MIN_MODEL_WIDTH = 5;
+
 /**
- * Pick the optional table columns that fit the terminal width.
- * @param {number} columns Terminal width.
- * @returns {{ latency: boolean, tokens: boolean }} Which optional columns to show.
+ * Format a request cost at the precision the pool logs it, so small amounts are never rounded away.
+ * @param {number} amount USD.
+ * @returns {string} For example `$0.0435`.
  */
-function tableLayout(columns) {
-  return { latency: columns >= 50, tokens: columns >= 70 };
+function exactMoney(amount) {
+  return `$${(Number(amount) || 0).toFixed(4)}`;
 }
 
 /**
@@ -170,37 +173,116 @@ function statusTone(status) {
 }
 
 /**
- * Render one request as a table row.
+ * Choose the table columns: sized to the content, then thinned to fit the terminal.
+ * Drops In/Out first, then Latency, then shrinks the model column.
+ * @param {number} columns Terminal width.
+ * @param {Record<string, any>[]} recent Requests to show (the model column fits the longest name, capped).
+ * @returns {{ id: string, title: string, width: number, right: boolean }[]} Visible columns in order.
+ */
+function tableColumns(columns, recent) {
+  const model = Math.min(MAX_MODEL_WIDTH, Math.max(MIN_MODEL_WIDTH, ...recent.map((request) => String(request.model ?? "-").length)));
+  let cols = [
+    { id: "time", title: "Time", width: 8, right: false },
+    { id: "model", title: "Model", width: model, right: false },
+    { id: "status", title: "Status", width: 6, right: false },
+    { id: "latency", title: "Latency", width: 7, right: true },
+    { id: "in", title: "In", width: 6, right: true },
+    { id: "out", title: "Out", width: 6, right: true },
+    { id: "cost", title: "Cost", width: 9, right: true },
+  ];
+  for (const drop of [["in", "out"], ["latency"]]) {
+    if (tableWidth(cols) <= columns - 1) break;
+    cols = cols.filter((col) => !drop.includes(col.id));
+  }
+  const excess = tableWidth(cols) - (columns - 1);
+  if (excess > 0) {
+    const modelCol = cols.find((col) => col.id === "model");
+    modelCol.width = Math.max(MIN_MODEL_WIDTH, modelCol.width - excess);
+  }
+  return cols;
+}
+
+/**
+ * Total width of a bordered table.
+ * @param {{ width: number }[]} cols Columns.
+ * @returns {number} Characters per line, borders and padding included.
+ */
+function tableWidth(cols) {
+  return cols.reduce((sum, col) => sum + col.width + 3, 1);
+}
+
+/**
+ * Draw a horizontal table border.
+ * @param {{ width: number }[]} cols Columns.
+ * @param {[string, string, string]} corners Left, junction and right characters.
+ * @param {boolean} color Whether to emit colour.
+ * @returns {string} One grey line.
+ */
+function border(cols, [left, mid, right], color) {
+  return paint(color, "grey", `${left}${cols.map((col) => "─".repeat(col.width + 2)).join(mid)}${right}`);
+}
+
+/**
+ * Draw one table line from already padded cells.
+ * @param {string[]} cells Cell text, each exactly its column width (colour codes allowed).
+ * @param {boolean} color Whether to emit colour.
+ * @returns {string} One line with grey vertical borders.
+ */
+function tableLine(cells, color) {
+  const bar = paint(color, "grey", "│");
+  return `${bar}${cells.map((cell) => ` ${cell} `).join(bar)}${bar}`;
+}
+
+/**
+ * Pad text to a column width on its alignment side.
+ * @param {string} text Plain text, already no longer than the column.
+ * @param {{ width: number, right: boolean }} col Column.
+ * @returns {string} Text of exactly `col.width` characters.
+ */
+function fit(text, col) {
+  return col.right ? text.padStart(col.width) : text.padEnd(col.width);
+}
+
+/**
+ * Render one request as table cells.
  * @param {Record<string, any>} request Entry from `/member/api/recent`.
- * @param {{ latency: boolean, tokens: boolean }} layout Visible columns.
- * @param {number} modelWidth Width reserved for the model name.
+ * @param {{ id: string, width: number, right: boolean }[]} cols Visible columns.
  * @param {boolean} color Whether to emit colour.
  * @param {string | undefined} timeZone IANA zone.
- * @returns {string} One line.
+ * @returns {string[]} One padded cell per column.
  */
-function requestRow(request, layout, modelWidth, color, timeZone) {
-  const cells = [clock(request.started_at, timeZone), truncate(String(request.model ?? "-"), modelWidth).padEnd(modelWidth)];
-  cells.push(paint(color, statusTone(request.status), String(request.status).padEnd(6)));
-  if (layout.latency) cells.push(latency(request.latency_ms).padStart(7));
-  if (layout.tokens) cells.push(tokens(request.input_tokens).padStart(7), tokens(request.output_tokens).padStart(7));
-  cells.push(money(request.usd).padStart(8));
-  return cells.join(" ");
+function requestCells(request, cols, color, timeZone) {
+  const text = {
+    time: clock(request.started_at, timeZone),
+    model: String(request.model ?? "-"),
+    status: String(request.status),
+    latency: latency(request.latency_ms),
+    in: tokens(request.input_tokens),
+    out: tokens(request.output_tokens),
+    cost: exactMoney(request.usd),
+  };
+  return cols.map((col) => {
+    const cell = fit(truncate(text[col.id], col.width), col);
+    return col.id === "status" ? paint(color, statusTone(request.status), cell) : cell;
+  });
 }
 
 /**
  * Render the whole dashboard as text. Pure: no I/O, so it can be tested without a terminal.
  * @param {{ report: Record<string, any> | null, recent: Record<string, any>[], refreshedAt: number | null, error: string | null, intervalSec: number, poolHost?: string, timeZone?: string }} state Latest poll result.
  * @param {{ columns: number, rows: number, color: boolean, now: number, fill?: boolean }} view Terminal size, colour switch, current epoch ms and whether to pad to `rows` so the footer sits on the last row (default true).
- * @returns {string} Lines joined with `\n`, each at most `columns` wide, at most `rows` lines, no trailing newline.
+ * @returns {string} Lines joined with `\n`, each at most `columns - 1` wide (the last column is left free: some terminals clip it), at most `rows` lines, no trailing newline.
  */
 export function renderFrame(state, { columns, rows, color, now, fill = true }) {
   const { report, recent, refreshedAt, error, intervalSec, timeZone } = state;
+  const cols = tableColumns(columns, recent);
+  const width = tableWidth(cols);
   const lines = [];
   const stale = refreshedAt !== null && now - refreshedAt > intervalSec * 2000 + 1000;
   const refreshed = refreshedAt === null ? "waiting for first refresh" : `refreshed ${clock(refreshedAt, timeZone)}${stale ? " (stale)" : ""}`;
   const title = `${report ? report.member : "TokenHub"}${state.poolHost ? ` @ ${state.poolHost}` : ""}`;
   const right = `${refreshed} · every ${intervalSec}s`;
-  lines.push(`${paint(color, "bold", title)}${" ".repeat(Math.max(2, columns - title.length - right.length))}${paint(color, "grey", right)}`);
+  lines.push(`${paint(color, "bold", title)}${" ".repeat(Math.max(2, width - title.length - right.length))}${paint(color, "grey", right)}`);
   lines.push("");
 
   if (report) {
@@ -216,23 +298,19 @@ export function renderFrame(state, { columns, rows, color, now, fill = true }) {
   lines.push("");
 
   const footer = error ? paint(color, "red", `reconnecting… ${error}`) : paint(color, "grey", "q quit · r refresh now");
-  const layout = tableLayout(columns);
-  const fixed = 8 + 1 + 6 + 1 + 8 + (layout.latency ? 8 : 0) + (layout.tokens ? 16 : 0) + 1;
-  const modelWidth = Math.max(8, columns - fixed);
-  const header = ["Time".padEnd(8), "Model".padEnd(modelWidth), "Status".padEnd(6)];
-  if (layout.latency) header.push("Latency".padStart(7));
-  if (layout.tokens) header.push("In".padStart(7), "Out".padStart(7));
-  header.push("$".padStart(8));
-  lines.push(paint(color, "grey", header.join(" ")));
-  const room = Math.max(0, rows - lines.length - 1);
+  lines.push(border(cols, ["┌", "┬", "┐"], color));
+  lines.push(tableLine(cols.map((col) => paint(color, "bold", fit(col.title, col))), color));
+  lines.push(border(cols, ["├", "┼", "┤"], color));
+  const room = Math.max(0, rows - lines.length - 2);
   if (recent.length === 0) {
-    if (room > 0) lines.push(paint(color, "grey", "No requests yet."));
+    if (room > 0) lines.push(tableLine([paint(color, "grey", "No requests yet.".padEnd(width - 4))], color));
   } else {
-    for (const request of recent.slice(0, room)) lines.push(requestRow(request, layout, modelWidth, color, timeZone));
+    for (const request of recent.slice(0, room)) lines.push(tableLine(requestCells(request, cols, color, timeZone), color));
   }
+  lines.push(border(cols, ["└", "┴", "┘"], color));
   while (fill && lines.length < rows - 1) lines.push("");
   lines.push(footer);
-  return lines.slice(-Math.max(rows, 1)).map((line) => clip(line, columns)).join("\n");
+  return lines.slice(-Math.max(rows, 1)).map((line) => clip(line, Math.max(columns - 1, 1))).join("\n");
 }
 
 /**

package/lib/pair.d.ts

@@ -8,4 +8,5 @@ export function runConnect(options: {
   deviceName?: string;
   intervalOverrideMs?: number;
   env?: Record<string, string | undefined>;
+  statusLine?: boolean;
 }): Promise<number>;

package/lib/pair.js

@@ -69,6 +69,7 @@ async function postJson(url, body, signal) {
  * @param {string} [options.deviceName] Name shown on the confirmation page.
  * @param {number} [options.intervalOverrideMs] Poll interval override (tests).
  * @param {Record<string, string | undefined>} [options.env] Environment inspected for overriding variables.
+ * @param {boolean} [options.statusLine] Also install the TokenHub status line (default true).
  * @returns {Promise<number>} Process exit code.
  */
 export async function runConnect({
@@ -80,6 +81,7 @@ export async function runConnect({
   deviceName = hostname(),
   intervalOverrideMs,
   env = process.env,
+  statusLine = true,
 }) {
   let pool;
   try {
@@ -119,8 +121,11 @@ export async function runConnect({
       if (poll.status === 429) continue;
       const status = poll.body?.status;
       if (status === "approved") {
-        connectSettings(settingsFile, poll.body.baseUrl, poll.body.key);
+        const statusResult = connectSettings(settingsFile, poll.body.baseUrl, poll.body.key, { statusLine });
         log(`Connected. Claude Code settings updated: ${settingsFile}`);
+        if (statusResult === "installed") log("Status line added: today's spend and credit show under the Claude Code prompt.");
+        if (statusResult === "updated") log("Status line refreshed with your new key.");
+        if (statusResult === "kept") log("Your existing statusLine was left as is. The setup guide on the pool site has the TokenHub one if you want it.");
         const overriding = overridingEnvVars(env);
         if (overriding.length > 0) {
           log(`Warning: ${overriding.join(", ")} set in your shell overrides settings.json. Unset it to use the pool.`);

package/lib/settings.d.ts

@@ -1,9 +1,22 @@
 export function settingsPath(env?: Record<string, string | undefined>, home?: string): string;
 export function normalizeUrl(input: string): string;
 export function mergeSettings(settings: Record<string, any>, baseUrl: string, key: string): Record<string, any>;
+export function statusLineCommand(baseUrl: string, key: string, platform?: string): string;
+export function isTokenhubStatusLine(value: unknown): boolean;
+export function installStatusLine(
+  settings: Record<string, any>,
+  baseUrl: string,
+  key: string,
+  platform?: string,
+): { settings: Record<string, any>; result: "installed" | "updated" | "kept" };
 export function removeSettings(settings: Record<string, any>): Record<string, any>;
 export function overridingEnvVars(env?: Record<string, string | undefined>): string[];
 export function readSettings(file: string): { exists: boolean; settings: Record<string, any> };
 export function writeSettings(file: string, settings: Record<string, any>): void;
-export function connectSettings(file: string, baseUrl: string, key: string): void;
+export function connectSettings(
+  file: string,
+  baseUrl: string,
+  key: string,
+  options?: { statusLine?: boolean; platform?: string },
+): "installed" | "updated" | "kept" | "skipped";
 export function disconnectSettings(file: string): boolean;

package/lib/settings.js

@@ -4,6 +4,7 @@ import { dirname, join } from "node:path";
 
 const BASE_URL_KEY = "ANTHROPIC_BASE_URL";
 const TOKEN_KEY = "ANTHROPIC_AUTH_TOKEN";
+const STATUS_PATH = "/member/api/status";
 
 /**
  * Locate Claude Code's user settings file.
@@ -48,15 +49,52 @@ export function mergeSettings(settings, baseUrl, key) {
 }
 
 /**
- * Return a copy of the settings without the pool connection entries.
+ * The shell command Claude Code runs to draw the TokenHub status line (today's spend and credit under the prompt).
+ * @param {string} baseUrl Pool address.
+ * @param {string} key The member's key.
+ * @param {string} [platform] Node platform name; Windows gets `curl.exe` with double quotes (works from cmd, PowerShell and Git Bash).
+ * @returns {string} The command line.
+ */
+export function statusLineCommand(baseUrl, key, platform = process.platform) {
+  const url = `${baseUrl}${STATUS_PATH}?format=line`;
+  return platform === "win32" ? `curl.exe -s -H "x-api-key: ${key}" "${url}"` : `curl -s -H 'x-api-key: ${key}' '${url}'`;
+}
+
+/**
+ * @param {unknown} value A `statusLine` setting.
+ * @returns {boolean} True when it is the TokenHub status line (a command calling the pool's status endpoint).
+ */
+export function isTokenhubStatusLine(value) {
+  return isPlainObject(value) && typeof value.command === "string" && value.command.includes(STATUS_PATH);
+}
+
+/**
+ * Add the TokenHub status line unless the user already has a different one.
  * @param {Record<string, any>} settings Existing settings object.
- * @returns {Record<string, any>} New settings; `env` is dropped when it ends up empty.
+ * @param {string} baseUrl Pool address.
+ * @param {string} key The member's key.
+ * @param {string} [platform] Node platform name.
+ * @returns {{ settings: Record<string, any>, result: "installed" | "updated" | "kept" }} `installed` when there was none,
+ *   `updated` when ours was refreshed with the new key, `kept` when another status line was left alone.
+ */
+export function installStatusLine(settings, baseUrl, key, platform = process.platform) {
+  const existing = settings.statusLine;
+  if (existing !== undefined && !isTokenhubStatusLine(existing)) return { settings, result: "kept" };
+  const statusLine = { ...(isPlainObject(existing) ? existing : {}), type: "command", command: statusLineCommand(baseUrl, key, platform) };
+  return { settings: { ...settings, statusLine }, result: existing === undefined ? "installed" : "updated" };
+}
+
+/**
+ * Return a copy of the settings without the pool connection entries (and without our status line).
+ * @param {Record<string, any>} settings Existing settings object.
+ * @returns {Record<string, any>} New settings; `env` is dropped when it ends up empty, another status line is kept.
  */
 export function removeSettings(settings) {
-  const { env, ...rest } = settings;
-  if (!isPlainObject(env)) return { ...settings };
+  const { env, statusLine, ...rest } = settings;
+  const keep = statusLine !== undefined && !isTokenhubStatusLine(statusLine) ? { statusLine } : {};
+  if (!isPlainObject(env)) return { ...rest, ...keep, ...(env === undefined ? {} : { env }) };
   const { [BASE_URL_KEY]: _url, [TOKEN_KEY]: _token, ...otherEnv } = env;
-  return Object.keys(otherEnv).length > 0 ? { ...rest, env: otherEnv } : rest;
+  return Object.keys(otherEnv).length > 0 ? { ...rest, ...keep, env: otherEnv } : { ...rest, ...keep };
 }
 
 /**
@@ -103,20 +141,28 @@ export function writeSettings(file, settings) {
 }
 
 /**
- * Persist a pool connection into the settings file.
+ * Persist a pool connection (and the TokenHub status line) into the settings file.
  * @param {string} file Path of settings.json.
  * @param {string} baseUrl Value for ANTHROPIC_BASE_URL.
  * @param {string} key Value for ANTHROPIC_AUTH_TOKEN.
- * @returns {void}
+ * @param {{ statusLine?: boolean, platform?: string }} [options] `statusLine: false` skips the status line; `platform` is for tests.
+ * @returns {"installed" | "updated" | "kept" | "skipped"} What happened to the status line.
  * @throws {Error} When the existing file is invalid JSON (left untouched).
  */
-export function connectSettings(file, baseUrl, key) {
+export function connectSettings(file, baseUrl, key, options = {}) {
   const { settings } = readSettings(file);
-  writeSettings(file, mergeSettings(settings, baseUrl, key));
+  const merged = mergeSettings(settings, baseUrl, key);
+  if (options.statusLine === false) {
+    writeSettings(file, merged);
+    return "skipped";
+  }
+  const { settings: next, result } = installStatusLine(merged, baseUrl, key, options.platform);
+  writeSettings(file, next);
+  return result;
 }
 
 /**
- * Remove the pool connection from the settings file.
+ * Remove the pool connection (and our status line) from the settings file.
  * @param {string} file Path of settings.json.
  * @returns {boolean} True when the file changed, false when there was nothing to remove.
  * @throws {Error} When the existing file is invalid JSON (left untouched).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emesoft/tokenhub",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Pair Claude Code on this machine with a TokenHub pool",
   "type": "module",
   "bin": {