@caius_kong/ccusage-dashboard 0.2.9 → 0.2.10

package/bin/ccusage-ui.js

@@ -5,12 +5,18 @@
  * Locates the bundled server.py (and its index.html sibling) and runs it with
  * 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.
  */
 'use strict';
 
 const { spawn, spawnSync } = require('node:child_process');
 const path = require('node:path');
 const fs = require('node:fs');
+const http = require('node:http');
 
 // Data files live in package/lib (installed layout) or the repo root (dev layout).
 function resolveLibFile(name) {
@@ -41,13 +47,50 @@ if (!py) {
   process.exit(1);
 }
 
-const args = process.argv.slice(2);
+// Parse the user's --port / --host so the banner points at the real URL.
+const rawArgs = process.argv.slice(2);
+function argValue(name, fallback) {
+  const i = rawArgs.indexOf(name);
+  return i >= 0 && rawArgs[i + 1] ? rawArgs[i + 1] : fallback;
+}
+const host = argValue('--host', '127.0.0.1');
+const port = parseInt(argValue('--port', '8799'), 10);
+const url = `http://${host}:${port}`;
+
+const args = rawArgs.slice();
 if (!args.includes('--open') && !process.env.CCUSAGE_UI_NO_OPEN) {
-  args.push('--open'); // default: open browser after start
+  args.push('--open'); // default: try to auto-open the browser (best effort)
 }
 
 const child = spawn(py, [serverPy, ...args], { stdio: 'inherit', env: { ...process.env } });
 
+// 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('');
+}
+
+let checked = false;
+function pingAndBanner() {
+  if (checked) return;
+  checked = true;
+  const req = http.get(url + '/api/health', { timeout: 1500 }, (res) => {
+    if (res.statusCode === 200) printBanner();
+    else setTimeout(pingAndBanner, 500);
+  });
+  req.on('error', () => setTimeout(pingAndBanner, 500));
+}
+
+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); });
 }

package/lib/server.py

@@ -577,6 +577,8 @@ def main() -> None:
     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()
@@ -585,28 +587,43 @@ def main() -> None:
 
 
 def _open_browser(url: str) -> None:
-    """Open the dashboard in the default browser. Prefers the OS-native opener
-    (open / xdg-open / start) and logs success/failure so it is verifiable.
+    """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":
-        cmd = ["open", url]
+        if browser:
+            attempts.append(["open", "-a", browser, url])
+        attempts.append(["open", url])
     elif sys.platform.startswith("win"):
-        cmd = ["cmd", "/c", "start", "", url]
+        if browser:
+            attempts.append(["cmd", "/c", "start", "", "chrome", url])
+        attempts.append(["cmd", "/c", "start", "", url])
     else:
-        cmd = ["xdg-open", url]
-    try:
-        r = subprocess.run(cmd, timeout=5, capture_output=True, text=True)
-        if r.returncode == 0:
-            print(f"browser opened → {url}", flush=True)
-        else:
-            print(f"browser open failed (rc={r.returncode}): {r.stderr.strip()[:200]}", flush=True)
-    except FileNotFoundError:
-        print(f"no system opener found; open {url} manually", flush=True)
-    except Exception as e:  # noqa: BLE001
-        print(f"browser open error: {e}", flush=True)
+        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:

package/package.json

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