@emesoft/tokenhub 0.6.0 → 0.7.0

package/README.md

@@ -12,8 +12,13 @@ npx @emesoft/tokenhub dashboard
 npx @emesoft/tokenhub disconnect
 npx @emesoft/tokenhub connect --admin
 npx @emesoft/tokenhub disconnect --admin
+npx @emesoft/tokenhub overlay
 ```
 
+To type `tokenhub` without `npx`, install it **globally**: `npm install -g @emesoft/tokenhub`, then `tokenhub connect`. A plain `npm install @emesoft/tokenhub` puts it in the current folder's `node_modules`, which is not on your `PATH` (only `npx` finds it there). With nvm, global packages belong to one Node version: install again after `nvm use`.
+
+`overlay` (Windows) downloads the TokenHub desktop overlay installer from the pool (`/downloads/overlay.exe`) and starts it. The overlay then shows your own usage after `connect`, or the whole pool after `connect --admin`.
+
 `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).
@@ -24,7 +29,7 @@ Requests to the pool carry your key and one extra header, `x-tokenhub-cli: <vers
 
 `disconnect` removes only those two entries and the TokenHub `statusLine`.
 
-`connect --admin` is for pool admins. It pairs this machine as an *admin device* for the TokenHub desktop overlay: you confirm the code on the pool's **admin** console (so only the signed-in admin can approve it), and the CLI saves a read-only device token to `~/.tokenhub/admin.json` (or `$TOKENHUB_CONFIG_DIR/admin.json`). It never touches Claude Code's settings. The token can read account names and quota levels, nothing else. Revoke a device on the admin Devices page (`/admin/pair`); `disconnect --admin` just forgets the token locally.
+`connect --admin` is for pool admins. It pairs this machine as an *admin device* for the TokenHub desktop overlay: you confirm the code on the pool's **admin** console (so only the signed-in admin can approve it), and the CLI saves a device token to `~/.tokenhub/admin.json` (or `$TOKENHUB_CONFIG_DIR/admin.json`). It never touches Claude Code's settings. The token can read account names and quota levels and switch accounts on or off (the overlay's switch), nothing else: no emails, tokens, members or settings. Revoke a device on the admin Devices page (`/admin/pair`); `disconnect --admin` just forgets the token locally.
 
 If `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY` is set in your shell, it overrides `settings.json`.
 

package/bin/tokenhub.js

@@ -2,6 +2,7 @@
 import { readFileSync } from "node:fs";
 import { adminConfigPath, removeAdminConfig } from "../lib/admin.js";
 import { parseDashboardArgs, runDashboard } from "../lib/dashboard.js";
+import { runOverlayInstall } from "../lib/overlay.js";
 import { DEFAULT_POOL_URL, runConnect } from "../lib/pair.js";
 import { disconnectSettings, readSettings, settingsPath } from "../lib/settings.js";
 import { fetchUsage, formatUsage, resolveCredentials } from "../lib/usage.js";
@@ -16,6 +17,7 @@ Usage:
   tokenhub connect [poolUrl] --admin
                                Pair this machine as an admin device (for the desktop overlay's pool view): the admin
                                confirms in the console, the token is saved to ~/.tokenhub/admin.json
+  tokenhub overlay [poolUrl]   Download and install the TokenHub desktop overlay (Windows)
   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)
@@ -55,6 +57,9 @@ async function main(argv) {
       adminFile: adminConfigPath(),
     });
   }
+  if (command === "overlay") {
+    return runOverlayInstall(arg ? { poolUrl: arg } : {});
+  }
   if (command === "usage") {
     try {
       const credentials = resolveCredentials(readSettings(file).settings);

package/lib/overlay.d.ts

@@ -0,0 +1,9 @@
+export const OVERLAY_PATH: string;
+export function runOverlayInstall(options?: {
+  poolUrl?: string;
+  log?: (line: string) => void;
+  platform?: string;
+  run?: (file: string) => void;
+  dir?: string;
+  fetchImpl?: typeof fetch;
+}): Promise<number>;

package/lib/overlay.js

@@ -0,0 +1,81 @@
+import { spawn } from "node:child_process";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { normalizeUrl } from "./settings.js";
+import { DEFAULT_POOL_URL } from "./pair.js";
+
+/** Path of the overlay installer on the pool. */
+export const OVERLAY_PATH = "/downloads/overlay.exe";
+
+/**
+ * Start the installer and let it run on its own (it shows its own window; this process does not wait for it).
+ * @param {string} file Installer path.
+ * @returns {void}
+ */
+function launch(file) {
+  const child = spawn(file, [], { detached: true, stdio: "ignore", windowsHide: false });
+  child.on("error", () => {});
+  child.unref();
+}
+
+/**
+ * Download the TokenHub desktop overlay's Windows installer from the pool and start it.
+ * @param {object} options
+ * @param {string} [options.poolUrl] Pool address (default `DEFAULT_POOL_URL`).
+ * @param {(line: string) => void} [options.log] Output sink.
+ * @param {string} [options.platform] Node platform name; the overlay is Windows only.
+ * @param {(file: string) => void} [options.run] Starts the downloaded installer (tests replace it).
+ * @param {string} [options.dir] Folder to save the installer in (default a new temp folder).
+ * @param {typeof fetch} [options.fetchImpl] `fetch` override for tests.
+ * @returns {Promise<number>} Process exit code.
+ */
+export async function runOverlayInstall({
+  poolUrl = DEFAULT_POOL_URL,
+  log = console.log,
+  platform = process.platform,
+  run = launch,
+  dir,
+  fetchImpl = fetch,
+} = {}) {
+  if (platform !== "win32") {
+    log("The TokenHub overlay is a Windows app; there is no build for this system yet.");
+    return 1;
+  }
+  let url;
+  try {
+    url = `${normalizeUrl(poolUrl)}${OVERLAY_PATH}`;
+  } catch (error) {
+    log(`Error: ${error.message}`);
+    return 1;
+  }
+  log(`Downloading the overlay from ${url} ...`);
+  let res;
+  try {
+    res = await fetchImpl(url, { signal: AbortSignal.timeout(120_000) });
+  } catch (error) {
+    log(`Error: could not reach the pool (${error.message}).`);
+    return 1;
+  }
+  if (res.status === 404) {
+    log("This pool has not published the overlay installer yet. Ask your admin.");
+    return 1;
+  }
+  if (!res.ok) {
+    log(`Error: the pool answered HTTP ${res.status}.`);
+    return 1;
+  }
+  const bytes = Buffer.from(await res.arrayBuffer());
+  const expected = Number(res.headers.get("content-length"));
+  // A Windows executable starts with "MZ"; anything else (an HTML error page, a cut-off download) is not run.
+  if ((expected > 0 && bytes.length !== expected) || bytes.length < 2 || bytes[0] !== 0x4d || bytes[1] !== 0x5a) {
+    log("Error: the download is incomplete or not an installer. Try again.");
+    return 1;
+  }
+  const file = join(dir ?? mkdtempSync(join(tmpdir(), "tokenhub-overlay-")), "TokenHub-Overlay-setup.exe");
+  writeFileSync(file, bytes);
+  log(`Downloaded ${(bytes.length / 1024 / 1024).toFixed(1)} MB. Starting the installer...`);
+  run(file);
+  log("Follow the installer. The overlay picks up `tokenhub connect` (your usage) or `tokenhub connect --admin` (the pool).");
+  return 0;
+}

package/package.json

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