@caius_kong/ccusage-dashboard 0.2.14 → 0.2.16

package/README.md

@@ -52,6 +52,7 @@ npx @caius_kong/ccusage-dashboard --budget 500    # monthly budget cap (default
 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
+npx @caius_kong/ccusage-dashboard --no-update-check  # disable the npm update hint entirely
 ```
 
 Once started, the launcher prints the dashboard URL — open it in your browser
@@ -75,6 +76,16 @@ launcher exits and the server keeps running, so you can close the terminal. Use
 All costs in USD. **Cache hit rate** is the standard input-side metric:
 `cacheReadTokens / (cacheReadTokens + non-cached inputTokens)`. Auto-refresh every 15s.
 
+## Update check (opt-out, purely manual)
+
+This dashboard is otherwise fully offline. The only way it touches the network
+is when **you click the "⇪ check update" button** in the header: the server then
+makes one quick request to the npm registry and pops up the result — up to date,
+update available (with the exact `npx @caius_kong/ccusage-dashboard@latest`
+command to run yourself in a terminal), or unreachable. Nothing is checked
+automatically, ever. Disable even this with `--no-update-check` or
+`CCUSAGE_NO_UPDATE_CHECK=1`.
+
 ## How it works
 
 ```

package/lib/index.html

@@ -49,6 +49,19 @@
   .empty{color:var(--muted);padding:18px 0;text-align:center}
   .err{color:var(--red)}
   .pill{background:var(--panel-2);border:1px solid var(--border);border-radius:999px;padding:1px 8px;font-size:11px;color:var(--muted);margin-left:6px}
+  .upd-btn{background:transparent;border:1px solid var(--border);border-radius:999px;padding:2px 11px;font-size:11px;color:var(--muted);cursor:pointer;font-family:inherit;transition:border-color .15s,color .15s}
+  .upd-btn:hover{border-color:var(--accent);color:var(--text)}
+  .upd-btn:disabled{opacity:.55;cursor:default}
+  .btn{background:var(--panel-2);border:1px solid var(--border);color:var(--text);border-radius:8px;padding:5px 14px;cursor:pointer;font-family:inherit;font-size:13px}
+  .btn:hover{border-color:var(--accent)}
+  .btn.primary{background:var(--accent);border-color:var(--accent);color:#0d1117;font-weight:600}
+  .modal-mask{position:fixed;inset:0;background:rgba(1,4,9,.6);display:flex;align-items:center;justify-content:center;z-index:60}
+  .modal{background:var(--panel);border:1px solid var(--border);border-radius:12px;padding:18px 20px;max-width:430px;width:calc(100vw - 40px);box-shadow:0 14px 44px rgba(0,0,0,.5)}
+  .modal h3{font-size:15px;margin:0 0 10px}
+  .modal .body{color:var(--text);font-size:13px;line-height:1.55}
+  .cmd{display:flex;align-items:center;gap:8px;background:var(--bg);border:1px solid var(--border);border-radius:8px;padding:8px 10px;margin:12px 0}
+  .cmd code{flex:1;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:12px;color:var(--text);word-break:break-all}
+  .modal .foot{display:flex;justify-content:flex-end;margin-top:16px}
   .hint{color:var(--muted);font-size:12px;margin-top:14px;text-align:center}
   .range{display:flex;gap:8px;align-items:center;margin-left:6px;flex-wrap:wrap}
   .range input{background:var(--panel-2);border:1px solid var(--border);color:var(--text);border-radius:6px;padding:5px 8px;font-size:12px;font-family:inherit}
@@ -71,7 +84,7 @@
 <header>
   <h1>ccusage · Live Cost</h1>
   <span class="sub">by model, straight from ccusage</span>
-  <span class="status"><span class="dot" id="dot"></span><span id="status">connecting…</span></span>
+  <span class="status"><button class="upd-btn" id="updBtn" type="button" title="Check the npm registry for a newer version">⇪ check update</button><span class="dot" id="dot"></span><span id="status">connecting…</span></span>
 </header>
 
 <div class="tabs" role="tablist" aria-label="Time period">
@@ -120,11 +133,64 @@
 
 <div class="hint">auto-refresh 15s · costs in USD · <span id="lastUpd"></span></div>
 
+<div class="modal-mask" id="updModal" style="display:none">
+  <div class="modal" role="dialog" aria-modal="true" aria-labelledby="updTitle">
+    <h3 id="updTitle"></h3>
+    <div class="body" id="updBody"></div>
+    <div class="foot"><button class="btn primary" id="updOk" type="button">OK</button></div>
+  </div>
+</div>
+
 <script>
 const $=(id)=>document.getElementById(id);
 const tabs={today:{label:"Today",len:0},week:{label:"This Week",len:0},month:{label:"This Month",len:0},range:{label:"Custom Range",len:1}};
 let active="today", modelCtx=[];
 
+const PKG_NPM="@caius_kong/ccusage-dashboard";
+const CMD_UPDATE=`npx ${PKG_NPM}@latest`;
+function showUpdModal(title,body){
+  $("updTitle").textContent=title;
+  $("updBody").innerHTML=body;
+  $("updModal").style.display="flex";
+}
+function hideUpdModal(){$("updModal").style.display="none";}
+async function copyText(t,btn){
+  try{await navigator.clipboard.writeText(t);}
+  catch(e){
+    const ta=document.createElement("textarea");ta.value=t;ta.style.position="fixed";ta.style.opacity="0";
+    document.body.appendChild(ta);ta.select();
+    try{document.execCommand("copy");}catch(_){}
+    document.body.removeChild(ta);
+  }
+  const old=btn.textContent;btn.textContent="copied ✓";
+  setTimeout(()=>{btn.textContent=old;},1200);
+}
+async function checkUpdate(){
+  const b=$("updBtn"),orig=b.textContent;
+  b.disabled=true;b.textContent="checking…";
+  try{
+    const d=await(await fetch("/api/update")).json();
+    if(d.disabled){
+      showUpdModal("Update check is off","This instance was started with <code>--no-update-check</code>, so version checks are disabled.");
+    }else if(d.error){
+      showUpdModal("Couldn't reach npm","The npm registry is not reachable right now. Check your internet connection and try again.");
+    }else if(d.outdated){
+      const cur=esc(d.current||"?"),lat=esc(d.latest||"?");
+      showUpdModal("Update available",
+        `You're running <b>v${cur}</b> — the latest version is <b>v${lat}</b>.<br>`+
+        `Update by running this in your terminal:`+
+        `<div class="cmd"><code>${CMD_UPDATE}</code><button class="btn" id="updCopy" type="button">copy</button></div>`+
+        `<div style="color:var(--muted);font-size:12px">Then restart the dashboard (run <code>--stop</code> first if it's running in the background).</div>`);
+      const cp=$("updCopy");if(cp)cp.addEventListener("click",(ev)=>copyText(CMD_UPDATE,ev.currentTarget));
+    }else{
+      showUpdModal("Up to date",`You're on the latest version <b>v${esc(d.current||"?")}</b> ✓`);
+    }
+  }catch(e){
+    showUpdModal("Check failed","Couldn't reach the dashboard server for a version check.");
+  }finally{
+    b.disabled=false;b.textContent=orig;
+  }
+}
 function fmtUsd(n){return "$"+(n==null?"–":Number(n).toFixed(2));}
 function fmtTok(n){
   if(n==null)return "–";
@@ -134,6 +200,18 @@ function fmtTok(n){
   return String(n);
 }
 function fmtPct(n){return n==null?"–":n.toFixed(1)+"%";}
+// cache hit rate (input side): read / (read + non-cached input). Shared by the
+// c5 summary card and per-row hit spans.
+function cacheHitStats(o){
+  const readIn=(o&&o.cacheReadTokens)||0, missIn=(o&&o.inputTokens)||0;
+  const rate=(readIn+missIn)>0?(readIn/(readIn+missIn))*100:null;
+  return {readIn, missIn, rate};
+}
+function cacheHitSpan(o){
+  const {readIn, missIn, rate}=cacheHitStats(o);
+  const tip=rate!=null?`cache hit rate: ${fmtPct(rate)} (read ${fmtTok(readIn)} / in ${fmtTok(missIn)})`:"no cache read data";
+  return `<span title="${tip}">hit ${fmtPct(rate)}</span>`;
+}
 function esc(s){const d=document.createElement("div");d.textContent=s;return d.innerHTML;}
 async function copySessionId(id, ev){
   ev.stopPropagation();
@@ -165,7 +243,7 @@ function renderModels(data){
     const badge=m2?`<span class="pill">${esc(m2[1])}</span>`:"";
     const mn=m2?esc(m2[2]||m2[1]):esc(m.name);
     return `<div class="row"><div class="row-top"><span class="name">${mn}${badge ? " " + badge : ""}</span><span class="cost">${fmtUsd(m.cost)} · ${pct.toFixed(1)}%</span></div>
-      <div class="toks"><span title="input">in ${fmtTok(m.inputTokens)}</span><span title="output">out ${fmtTok(m.outputTokens)}</span><span title="cache read">read ${fmtTok(m.cacheReadTokens)}</span><span title="cache write">write ${fmtTok(m.cacheCreationTokens)}</span></div>
+      <div class="toks"><span title="input">in ${fmtTok(m.inputTokens)}</span><span title="output">out ${fmtTok(m.outputTokens)}</span><span title="cache read">read ${fmtTok(m.cacheReadTokens)}</span>${cacheHitSpan(m)}<span title="cache write">write ${fmtTok(m.cacheCreationTokens)}</span></div>
       <div class="bar"><div style="width:${Math.max(pct,1.2)}%"></div></div></div>`;
   }).join("");
 }
@@ -218,7 +296,7 @@ function renderSessions(data){
     const last=(s.lastActivity||"").slice(0,10);
     return `<div class="row">
       <div class="row-top"><span>${label} <span class="pill">${esc(s.agent)}</span></span><span class="cost">${fmtUsd(s.cost)}</span></div>
-      <div class="toks">${last?`<span>${esc(last)}</span>`:""}<span title="input">in ${fmtTok(s.inputTokens)}</span><span title="output">out ${fmtTok(s.outputTokens)}</span><span title="cache read">read ${fmtTok(s.cacheReadTokens)}</span><span title="cache write">write ${fmtTok(s.cacheCreationTokens)}</span></div>
+      <div class="toks">${last?`<span>${esc(last)}</span>`:""}<span title="input">in ${fmtTok(s.inputTokens)}</span><span title="output">out ${fmtTok(s.outputTokens)}</span><span title="cache read">read ${fmtTok(s.cacheReadTokens)}</span>${cacheHitSpan(s)}<span title="cache write">write ${fmtTok(s.cacheCreationTokens)}</span></div>
     </div>`;
   }).join("");
 }
@@ -232,10 +310,9 @@ function applyCards(data){
   $("c3").textContent=fmtTok(data.cacheReadTokens);
   $("c4").textContent=fmtTok(data.cacheCreationTokens);
   // cache hit rate = cache-read input / (cache-read input + non-cached input)
-  const hitIn=data.cacheReadTokens||0, plainIn=data.inputTokens||0;
-  const hitRate = (hitIn+plainIn)>0 ? (hitIn/(hitIn+plainIn))*100 : null;
+  const {readIn, missIn, rate: hitRate}=cacheHitStats(data);
   $("c5").innerHTML=fmtPct(hitRate)+(hitRate!=null?"<small> cache</small>":"");
-  $("c5p").textContent=hitRate!=null?`${fmtTok(plainIn)} miss · ${fmtTok(hitIn)} hit`:"";
+  $("c5p").textContent=hitRate!=null?`${fmtTok(missIn)} miss · ${fmtTok(readIn)} hit`:"";
   $("c1label").textContent=tabs[active].label;
   $("modelSum").textContent=fmtUsd(total);
 }
@@ -353,6 +430,9 @@ document.querySelectorAll(".tab").forEach(t=>{
   t.addEventListener("keydown",(e)=>{if(e.key==="Enter"||e.key===" "||e.key==="Spacebar"){e.preventDefault();activate();}});
 });
 $("rangeGo").addEventListener("click",rangeApply);
+$("updBtn").addEventListener("click",checkUpdate);
+$("updOk").addEventListener("click",hideUpdModal);
+$("updModal").addEventListener("click",(e)=>{if(e.target.id==="updModal")hideUpdModal();});
 
 tick();
 setInterval(tick,15000);

package/lib/server.py

@@ -8,8 +8,13 @@ It shells out to ccusage's JSON reports and renders:
   - a monthly budget alert (default cap: $300)
 
 Because all numbers come from ccusage itself, the figures always match what
-`ccusage` reports (the source you already trust). No network, no pricing table
-to maintain, no third-party packages — only the Python standard library.
+`ccusage` reports (the source you already trust). No pricing table to maintain,
+no third-party packages — only the Python standard library. The sole optional
+This dashboard is fully offline except one manual check: clicking the
+"⇪ check update" button in the header makes a single request to the npm
+registry and shows the result in a popup (up to date / update available
+with the `npx @caius_kong/ccusage-dashboard@latest` command to run yourself /
+unreachable). Nothing is ever checked automatically.
 
 Usage:
     python3 server.py [--port 8799] [--budget 300]
@@ -25,6 +30,7 @@ import subprocess
 import sys
 import threading
 import time
+import urllib.request
 from datetime import date, timedelta
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
@@ -97,6 +103,19 @@ def _node() -> str:
 BUDGET = 300.0  # monthly cap in USD (override via --budget or CCUSAGE_BUDGET)
 TTL = {"/api/today": 15, "/api/week": 60, "/api/month": 60, "/api/range": 120, "/api/trend": 120, "/api/sessions": 60}
 
+# --- optional self-update check (purely user-triggered) ----------------------
+# The dashboard is otherwise fully offline: it makes a network request ONLY when
+# the user clicks the "check update" button in the UI. A short debounce stops
+# rapid re-clicks from hammering the registry. Disable entirely with
+# --no-update-check / CCUSAGE_NO_UPDATE_CHECK=1.
+PACKAGE_NAME = "@caius_kong/ccusage-dashboard"
+UPDATE_CHECKS = os.environ.get("CCUSAGE_NO_UPDATE_CHECK", "").lower() not in ("1", "true", "yes")
+UPDATE_REGISTRY = os.environ.get("CCUSAGE_REGISTRY", "https://registry.npmjs.org")
+CHECK_DEBOUNCE = 10  # seconds; ignore bursts of clicks
+
+_update_lock = threading.Lock()
+_last_check = None  # (timestamp, result dict) — debounce + last outcome
+
 
 def run_ccusage(args: list[str], ttl: float) -> dict:
     key = " ".join(args)
@@ -120,6 +139,77 @@ def run_ccusage(args: list[str], ttl: float) -> dict:
     return data
 
 
+def _read_current_version() -> str | None:
+    """Version of the running package. Finds the nearest package.json whose name
+    is ours (installed layout: <pkg>/package.json next to lib/; dev: repo root)."""
+    try:
+        for parent in APP_DIR.parents:
+            pj = parent / "package.json"
+            if pj.is_file():
+                meta = json.loads(pj.read_text(encoding="utf-8"))
+                if meta.get("name") == PACKAGE_NAME and meta.get("version"):
+                    return str(meta["version"])
+    except Exception:
+        return None
+    return None
+
+
+def _num(s: str) -> int:
+    m = re.match(r"\d+", s)
+    return int(m.group()) if m else 0
+
+
+def compare_versions(a: str, b: str) -> int:
+    """Minimal numeric semver compare for simple x.y.z tags (no deps)."""
+    pa = [_num(x) for x in re.sub(r"^v", "", a).split("-")[0].split(".")]
+    pb = [_num(x) for x in re.sub(r"^v", "", b).split("-")[0].split(".")]
+    for i in range(max(len(pa), len(pb))):
+        x = pa[i] if i < len(pa) else 0
+        y = pb[i] if i < len(pb) else 0
+        if x != y:
+            return -1 if x < y else 1
+    return 0
+
+
+def _fetch_latest_version() -> str:
+    """One GET to the npm registry's <latest> dist-tag endpoint."""
+    pkg = PACKAGE_NAME.replace("/", "%2F")
+    url = f"{UPDATE_REGISTRY.rstrip('/')}/{pkg}/latest"
+    req = urllib.request.Request(
+        url,
+        headers={
+            "User-Agent": f"ccusage-dashboard/{_read_current_version() or 'unknown'}",
+        },
+    )
+    with urllib.request.urlopen(req, timeout=4) as resp:
+        return str(json.loads(resp.read().decode("utf-8"))["version"])
+
+
+def check_now() -> dict:
+    """One synchronous registry lookup, triggered by the user's click. Debounced
+    briefly so double-clicks don't hit the registry twice; never runs on its own."""
+    global _last_check
+    if not UPDATE_CHECKS:
+        return {"disabled": True, "outdated": False}
+    now = time.time()
+    with _update_lock:
+        if _last_check and now - _last_check[0] < CHECK_DEBOUNCE:
+            return _last_check[1]
+    current = _read_current_version()
+    try:
+        latest = _fetch_latest_version()
+        result = {
+            "current": current,
+            "latest": latest,
+            "outdated": bool(current) and bool(latest) and compare_versions(latest, current) > 0,
+        }
+    except Exception:
+        result = {"current": current, "latest": None, "outdated": False, "error": "unreachable"}
+    with _update_lock:
+        _last_check = (time.time(), result)
+    return result
+
+
 def pick_all_row(rows: list[dict]) -> dict:
     return next((r for r in rows if r.get("agent") == "all"), None) or (rows[0] if rows else {})
 
@@ -492,6 +582,9 @@ class Handler(BaseHTTPRequestHandler):
         if path == "/api/health":
             self._json({"ok": True, "budget": BUDGET})
             return
+        if path == "/api/update":
+            self._json(check_now())
+            return
 
         if path == "/api/today":
             data = run_ccusage(["daily", "--last", "1", "--json", "--offline"], TTL[path])
@@ -532,17 +625,20 @@ class Handler(BaseHTTPRequestHandler):
 
 
 def main() -> None:
-    global BUDGET, _CCUSAGE_PATH_OVERRIDE
+    global BUDGET, _CCUSAGE_PATH_OVERRIDE, UPDATE_CHECKS
     parser = argparse.ArgumentParser(description="ccusage dashboard")
     parser.add_argument("--port", type=int, default=8799)
     parser.add_argument("--host", default="127.0.0.1")
     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("--no-update-check", action="store_true", help="disable the npm version hint entirely")
     args = parser.parse_args()
 
     BUDGET = args.budget if args.budget is not None else float(os_env_budget() or 300.0)
     _CCUSAGE_PATH_OVERRIDE = args.ccusage_path
+    if args.no_update_check:
+        UPDATE_CHECKS = False
     print(f"using ccusage → {' '.join(resolve_ccusage())}", flush=True)
 
     def warm_one(fn):

package/package.json

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