@caius_kong/ccusage-dashboard 0.2.11 → 0.2.13

package/README.md

@@ -50,11 +50,18 @@ for you to open.
 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 background warm-up
+npx @caius_kong/ccusage-dashboard --foreground   # run attached to this terminal (Ctrl+C stops it)
+npx @caius_kong/ccusage-dashboard --stop          # stop the background instance
 ```
 
 Once started, the launcher prints the dashboard URL — open it in your browser
 (no browser is auto-launched).
 
+By default the dashboard runs **in the background**: after printing its URL the
+launcher exits and the server keeps running, so you can close the terminal. Use
+`--stop` to shut it down; running it again reuses the already-running instance.
+`--foreground` keeps it attached to the terminal instead (Ctrl+C to stop).
+
 ## What it shows
 
 | | |

package/bin/ccusage-ui.js

@@ -6,8 +6,14 @@
  * 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: once the server is up, a clear URL banner is printed so the
- * user can click/copy it to open the dashboard. No background magic.
+ * Modes:
+ *   default            — 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.
+ *   --foreground       — run the server attached to this terminal (Ctrl+C stops it).
+ *
+ * Stop a background instance with:  npx @caius_kong/ccusage-dashboard --stop
  */
 'use strict';
 
@@ -15,6 +21,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) {
@@ -45,7 +52,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);
@@ -54,23 +61,132 @@ 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('--foreground'); // background by default
+const wantStop = rawArgs.includes('--stop');
+const wantForeground = rawArgs.includes('--foreground');
 
-const args = rawArgs.slice();
+// Filter launcher-only flags before forwarding to server.py.
+const serverArgs = rawArgs.filter((a) => !['--daemon', '--stop', '--foreground'].includes(a));
 
-const child = spawn(py, [serverPy, ...args], { stdio: 'inherit', env: { ...process.env } });
+// --- 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`);
+}
+
+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 — 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;
@@ -78,7 +194,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));
@@ -89,4 +205,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caius_kong/ccusage-dashboard",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "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",