@caius_kong/ccusage-dashboard 0.2.10 → 0.2.12

package/README.md

@@ -38,7 +38,8 @@ npx @caius_kong/ccusage-dashboard
 ```
 
 That's it. npx downloads the package (including its own `ccusage` dependency),
-starts a local server on `http://127.0.0.1:8799`, and opens your browser.
+starts a local server on `http://127.0.0.1:8799`, and prints the dashboard URL
+for you to open.
 
 > Requirements: **Node.js** (for the launcher) and **Python 3.8+** (for the server).
 > On macOS: `brew install python3`. No other installs, no build step, no config.
@@ -48,10 +49,18 @@ starts a local server on `http://127.0.0.1:8799`, and opens your browser.
 ```bash
 npx @caius_kong/ccusage-dashboard --port 9000     # change port
 npx @caius_kong/ccusage-dashboard --budget 500    # monthly budget cap (default $300)
-npx @caius_kong/ccusage-dashboard --no-warm       # skip 3s startup warm-up
-CCUSAGE_UI_NO_OPEN=1 npx @caius_kong/ccusage-dashboard   # don't auto-open browser
+npx @caius_kong/ccusage-dashboard --no-warm       # skip background warm-up
+npx @caius_kong/ccusage-dashboard --daemon        # run in the background (terminal exits, server keeps running)
+npx @caius_kong/ccusage-dashboard --stop          # stop a background instance
 ```
 
+Once started, the launcher prints the dashboard URL — open it in your browser
+(no browser is auto-launched).
+
+**`--daemon`** starts the server detached so you can close the terminal and it keeps
+running; run `--stop` to shut it down. Running `--daemon` again reuses the running
+instance instead of starting a second one.
+
 ## What it shows
 
 | | |
@@ -80,7 +89,7 @@ ccusage   (bundled dependency — the real cost engine)
 - `lib/server.py` — Python stdlib HTTP server. Resolves a local ccusage
   (bundled dep → PATH → npx cache), warms caches on boot (~3s), then serves instant responses.
 - `lib/index.html` — single-file dashboard. No build step, no CDN.
-- `bin/ccusage-ui.js` — Node launcher (finds python3, starts server, opens browser).
+- `bin/ccusage-ui.js` — Node launcher (finds python3, starts server, prints URL).
 
 ## Local development
 

package/bin/ccusage-ui.js

@@ -6,10 +6,16 @@
  * the local python3, forwarding any CLI args. The server itself shells out to
  * ccusage for all numbers, so the dashboard always matches ccusage.
  *
- * Startup UX:
- *   - the server tries to auto-open the default browser (best effort)
- *   - regardless of that, this launcher prints a clear URL banner once the
- *     server is up, so the user can always click/copy it manually.
+ * Modes:
+ *   foreground (default) — the server runs attached to this terminal; Ctrl+C
+ *                          stops it. A URL banner is printed when it is up.
+ *   --daemon             — start the server detached in the background, print
+ *                          the URL, and exit immediately. The server keeps
+ *                          running after this terminal closes. If a server is
+ *                          already up on the port, it reuses it instead of
+ *                          starting a second one.
+ *
+ * Stop a daemon with:  npx @caius_kong/ccusage-dashboard --stop
  */
 'use strict';
 
@@ -17,6 +23,7 @@ const { spawn, spawnSync } = require('node:child_process');
 const path = require('node:path');
 const fs = require('node:fs');
 const http = require('node:http');
+const os = require('node:os');
 
 // Data files live in package/lib (installed layout) or the repo root (dev layout).
 function resolveLibFile(name) {
@@ -47,7 +54,7 @@ if (!py) {
   process.exit(1);
 }
 
-// Parse the user's --port / --host so the banner points at the real URL.
+// --- arg parsing -----------------------------------------------------------
 const rawArgs = process.argv.slice(2);
 function argValue(name, fallback) {
   const i = rawArgs.indexOf(name);
@@ -56,26 +63,131 @@ function argValue(name, fallback) {
 const host = argValue('--host', '127.0.0.1');
 const port = parseInt(argValue('--port', '8799'), 10);
 const url = `http://${host}:${port}`;
+const wantDaemon = rawArgs.includes('--daemon');
+const wantStop = rawArgs.includes('--stop');
+
+// Filter launcher-only flags before forwarding to server.py.
+const serverArgs = rawArgs.filter((a) => !['--daemon', '--stop'].includes(a));
 
-const args = rawArgs.slice();
-if (!args.includes('--open') && !process.env.CCUSAGE_UI_NO_OPEN) {
-  args.push('--open'); // default: try to auto-open the browser (best effort)
+// --- daemon pid file (per host:port) ----------------------------------------
+function pidFile() {
+  const safeHost = host.replace(/[^a-z0-9]/gi, '_');
+  return path.join(os.tmpdir(), `ccusage-dashboard-${safeHost}-${port}.pid`);
 }
 
-const child = spawn(py, [serverPy, ...args], { stdio: 'inherit', env: { ...process.env } });
+function readDaemonPid() {
+  try {
+    const pid = parseInt(fs.readFileSync(pidFile(), 'utf8').trim(), 10);
+    return Number.isFinite(pid) ? pid : null;
+  } catch { return null; }
+}
+
+function daemonAlive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function isServerUp() {
+  return new Promise((resolve) => {
+    const req = http.get(url + '/api/health', { timeout: 1200 }, (res) => {
+      resolve(res.statusCode === 200);
+    });
+    req.on('error', () => resolve(false));
+  });
+}
 
-// Once the server answers /, print a clear URL banner for manual opening.
-let bannerPrinted = false;
 function printBanner() {
-  if (bannerPrinted) return;
-  bannerPrinted = true;
   const line = '─'.repeat(Math.max(20, url.length + 6));
   console.log('');
   console.log(line);
   console.log(`  Dashboard is running →  ${url}`);
   console.log(`  Open it manually:      ${url}`);
   console.log(line);
-  console.log('');
+  if (wantDaemon) {
+    console.log(`  (background mode — stop with: npx @caius_kong/ccusage-dashboard --stop)`);
+    console.log('');
+  }
+}
+
+async function waitForUp(timeoutMs) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await isServerUp()) return true;
+    await new Promise((r) => setTimeout(r, 300));
+  }
+  return false;
+}
+
+// --- stop -------------------------------------------------------------------
+async function handleStop() {
+  const pid = readDaemonPid();
+  if (pid && daemonAlive(pid)) {
+    try { process.kill(pid, 'SIGTERM'); } catch {}
+    console.log(`Stopping dashboard (pid ${pid}) …`);
+    const t0 = Date.now();
+    while (Date.now() - t0 < 5000 && await isServerUp()) {
+      await new Promise((r) => setTimeout(r, 300));
+    }
+    try { fs.unlinkSync(pidFile()); } catch {}
+    console.log('Dashboard stopped.');
+    process.exit(0);
+  }
+  console.log('No running dashboard instance found.');
+  process.exit(0);
+}
+
+if (wantStop) {
+  handleStop();
+  return;
+}
+
+// --- daemon mode ------------------------------------------------------------
+async function handleDaemon() {
+  // Reuse an already-running instance on this port.
+  if (await isServerUp()) {
+    console.log(`A dashboard is already running at ${url} — reusing it.`);
+    printBanner();
+    process.exit(0);
+  }
+  // If the pid file points at a dead pid, clear it.
+  const oldPid = readDaemonPid();
+  if (oldPid && !daemonAlive(oldPid)) {
+    try { fs.unlinkSync(pidFile()); } catch {}
+  }
+  // Start detached; the server outlives this launcher.
+  const out = fs.openSync(path.join(os.tmpdir(), `ccusage-dashboard-${port}.log`), 'a');
+  const child = spawn(py, [serverPy, ...serverArgs], {
+    detached: true,
+    stdio: ['ignore', out, out],
+    env: { ...process.env },
+  });
+  child.unref();
+  fs.writeFileSync(pidFile(), String(child.pid));
+  const up = await waitForUp(15000);
+  if (!up) {
+    console.error(`[ccusage-dashboard] server did not come up within 15s — check ${path.join(os.tmpdir(), `ccusage-dashboard-${port}.log`)}`);
+    try { process.kill(child.pid, 'SIGTERM'); } catch {}
+    process.exit(1);
+  }
+  console.log(`ccusage-dashboard started in background (pid ${child.pid}).`);
+  printBanner();
+  process.exit(0);
+}
+
+if (wantDaemon) {
+  handleDaemon();
+  return;
+}
+
+// --- foreground mode (default) ----------------------------------------------
+const child = spawn(py, [serverPy, ...serverArgs], { stdio: 'inherit', env: { ...process.env } });
+
+// Once the server answers /, print a clear URL banner for manual opening.
+let bannerPrinted = false;
+function printBannerFg() {
+  if (bannerPrinted) return;
+  bannerPrinted = true;
+  printBanner();
 }
 
 let checked = false;
@@ -83,7 +195,7 @@ function pingAndBanner() {
   if (checked) return;
   checked = true;
   const req = http.get(url + '/api/health', { timeout: 1500 }, (res) => {
-    if (res.statusCode === 200) printBanner();
+    if (res.statusCode === 200) printBannerFg();
     else setTimeout(pingAndBanner, 500);
   });
   req.on('error', () => setTimeout(pingAndBanner, 500));
@@ -94,4 +206,4 @@ setTimeout(pingAndBanner, 800); // give the python server a beat to bind
 for (const sig of ['SIGINT', 'SIGTERM']) {
   process.on(sig, () => { if (!child.killed) child.kill(sig); });
 }
-child.on('exit', (code) => process.exit(code == null ? 0 : code));
+child.on('exit', (code) => process.exit(code == null ? 0 : code));

package/lib/server.py

@@ -12,7 +12,7 @@ Because all numbers come from ccusage itself, the figures always match what
 to maintain, no third-party packages — only the Python standard library.
 
 Usage:
-    python3 server.py [--port 8799] [--budget 300] [--open]
+    python3 server.py [--port 8799] [--budget 300]
 """
 from __future__ import annotations
 
@@ -543,7 +543,6 @@ def main() -> None:
     parser.add_argument("--budget", type=float, default=None, help="monthly budget cap in USD (default 300)")
     parser.add_argument("--ccusage-path", default=None, help="explicit path to a ccusage binary or src/cli.js")
     parser.add_argument("--no-warm", action="store_true", help="skip background warm-up (first requests may be slow)")
-    parser.add_argument("--open", action="store_true", help="open browser after start")
     args = parser.parse_args()
 
     BUDGET = args.budget if args.budget is not None else float(os_env_budget() or 300.0)
@@ -575,10 +574,6 @@ def main() -> None:
     httpd = ThreadingHTTPServer((args.host, args.port), Handler)
     url = f"http://{args.host}:{args.port}"
     print(f"ccusage-ui → {url}  (monthly budget ${BUDGET:g}, Ctrl+C to stop)", flush=True)
-    if args.open:
-        _open_browser(url)
-    else:
-        print(f"dashboard ready at {url} — open it in your browser", flush=True)
 
     try:
         httpd.serve_forever()
@@ -586,46 +581,6 @@ def main() -> None:
         print("\nbye", flush=True)
 
 
-def _open_browser(url: str) -> None:
-    """Open the dashboard in a browser. Tries, in order:
-      1. $BROWSER (e.g. 'Google Chrome', 'Safari', 'firefox')
-      2. the OS default opener (open / xdg-open / start)
-      3. prints the URL as a fallback so the user can open it manually.
-    Every attempt logs its outcome so auto-open is verifiable.
-    """
-    import os
-    import subprocess
-    import sys
-
-    browser = os.environ.get("BROWSER", "").strip()
-    attempts = []
-    if sys.platform == "darwin":
-        if browser:
-            attempts.append(["open", "-a", browser, url])
-        attempts.append(["open", url])
-    elif sys.platform.startswith("win"):
-        if browser:
-            attempts.append(["cmd", "/c", "start", "", "chrome", url])
-        attempts.append(["cmd", "/c", "start", "", url])
-    else:
-        if browser:
-            attempts.append([browser, url])
-        attempts.append(["xdg-open", url])
-
-    for cmd in attempts:
-        try:
-            r = subprocess.run(cmd, timeout=5, capture_output=True, text=True)
-            if r.returncode == 0:
-                print(f"browser opened → {url} ({' '.join(cmd[:2])})", flush=True)
-                return
-            print(f"browser attempt failed (rc={r.returncode}): {' '.join(cmd[:2])}", flush=True)
-        except FileNotFoundError:
-            print(f"opener not found: {' '.join(cmd[:2])}", flush=True)
-        except Exception as e:  # noqa: BLE001
-            print(f"browser open error: {e}", flush=True)
-    print(f"could not auto-open a browser — open it manually: {url}", flush=True)
-
-
 def os_env_budget() -> str:
     import os
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caius_kong/ccusage-dashboard",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "One-command local dashboard for ccusage: today/week/month/custom cost by model, 30-day trend, monthly budget alert. Numbers straight from ccusage.",
   "license": "MIT",
   "type": "commonjs",