claude-finops 0.2.0 → 0.3.0

package/README.md

@@ -290,8 +290,15 @@ place for you to delete once you are happy.
 ## Privacy
 
 `~/.claude-finops/data/finops.db` and the prompt/CSV exports contain **your full prompt text**. The
-server binds to `127.0.0.1` only and makes no outbound requests, but treat the
-database and any export you generate as sensitive.
+server binds to `127.0.0.1` only, but treat the database and any export you
+generate as sensitive.
+
+The app makes exactly one outbound request of its own: once a day it asks
+`registry.npmjs.org` what the latest `claude-finops` version is, so it can tell
+you when an upgrade is out (npm has no way to push one at you). It sends nothing
+about you or your usage. Turn it off with `NO_UPDATE_NOTIFIER=1` or
+`CLAUDE_FINOPS_NO_UPDATE_CHECK=1`. Provider cost APIs are called only if you
+configure a key with `--set-key`.
 
 ---
 

package/finops/api.py

@@ -226,6 +226,9 @@ class Handler(BaseHTTPRequestHandler):
             self.send_json({"error": traceback.format_exc()}, 500)
 
     def api(self, route, qs):
+        if route == "update":
+            from .update import check
+            return self.send_json(check(force=qs.get("refresh", [""])[0] == "1"))
         if route == "usage":
             from .limits import usage
             return self.send_json(usage(force=qs.get("refresh", [""])[0] == "1"))
@@ -406,6 +409,11 @@ def _sync_job(log):
     return {"built_at": A.q("SELECT value FROM meta WHERE key='built_at'")[0]["value"]}
 
 
+def _notify_update():
+    from .update import notify
+    notify()
+
+
 def serve(port=8787, db=DB_PATH, background=None):
     global A
     if not os.path.exists(db):
@@ -420,6 +428,8 @@ def serve(port=8787, db=DB_PATH, background=None):
     print(f"  warehouse: {db}")
     print(f"  data      : {A.first_day} .. {A.last_day}")
     print("  Ctrl-C to stop.")
+    # Off the main thread: a slow registry must never delay the dashboard.
+    threading.Thread(target=_notify_update, daemon=True).start()
     try:
         srv.serve_forever()
     except KeyboardInterrupt:

package/finops/update.py

@@ -0,0 +1,133 @@
+"""Is there a newer release on npm?
+
+npm has no way to push: a global install stays on whatever version it was
+installed at until someone runs `npm i -g claude-finops@latest`. So we ask the
+registry ourselves, once a day, and say so if there is something newer.
+
+This is the only outbound request the app makes on its own. It sends nothing
+about you — no identifiers, no usage, not even a User-Agent beyond the package
+name and the version you already published to npm by installing it. Turn it off
+with NO_UPDATE_NOTIFIER=1 (the ecosystem-wide convention) or
+CLAUDE_FINOPS_NO_UPDATE_CHECK=1.
+
+The answer is cached in ~/.claude-finops/data/update_cache.json for a day, so a
+dashboard that restarts twenty times makes one request. Every failure is
+silent: no network, a proxy, an offline laptop and a 500 from the registry all
+look the same to the caller, which is "we don't know", never an error.
+"""
+import json
+import os
+import re
+import time
+import urllib.request
+
+from .paths import DATA_DIR, ROOT, ensure_dirs
+
+CACHE = os.path.join(DATA_DIR, "update_cache.json")
+URL = "https://registry.npmjs.org/claude-finops/latest"
+TTL_S = 24 * 60 * 60
+TIMEOUT_S = 3
+
+_NUM = re.compile(r"\d+")
+
+
+def _installed():
+    """Our own version, from the package.json we ship next to the code."""
+    try:
+        with open(os.path.join(ROOT, "package.json")) as fh:
+            return str(json.load(fh).get("version") or "").strip()
+    except (OSError, ValueError):
+        return ""
+
+
+def _key(v):
+    """Compare 1.10.0 above 1.9.0, and treat 1.0.0-rc.1 as below 1.0.0.
+
+    Only the numeric core is ordered; a prerelease suffix just loses the tie.
+    That is enough for a notifier — we publish plain releases.
+    """
+    core, _, pre = str(v).partition("-")
+    nums = [int(n) for n in _NUM.findall(core)[:3]]
+    return (nums + [0, 0, 0])[:3], 0 if pre else 1
+
+
+def _newer(latest, current):
+    return bool(latest) and bool(current) and _key(latest) > _key(current)
+
+
+def _read_cache():
+    try:
+        with open(CACHE) as fh:
+            c = json.load(fh)
+        return c if isinstance(c, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def _write_cache(latest):
+    ensure_dirs()
+    tmp = CACHE + ".tmp"
+    try:
+        with open(tmp, "w") as fh:
+            json.dump({"latest": latest, "checked_at": int(time.time())}, fh)
+        os.replace(tmp, CACHE)
+    except OSError:
+        pass
+
+
+def _fetch():
+    req = urllib.request.Request(URL, headers={
+        "Accept": "application/json",
+        "User-Agent": f"claude-finops/{_installed() or '0'}",
+    })
+    with urllib.request.urlopen(req, timeout=TIMEOUT_S) as r:
+        return str(json.load(r).get("version") or "").strip()
+
+
+def disabled():
+    return bool(os.environ.get("NO_UPDATE_NOTIFIER")
+                or os.environ.get("CLAUDE_FINOPS_NO_UPDATE_CHECK"))
+
+
+def check(force=False):
+    """Return {current, latest, update_available, checked_at, ...}.
+
+    Reads the cache unless it is older than a day (or `force`). Never raises,
+    and never blocks longer than TIMEOUT_S.
+    """
+    current = _installed()
+    out = {"current": current, "latest": "", "update_available": False,
+           "command": "npm i -g claude-finops@latest", "checked_at": 0,
+           "disabled": disabled()}
+    if out["disabled"]:
+        return out
+
+    cache = _read_cache()
+    age = time.time() - float(cache.get("checked_at") or 0)
+    if cache.get("latest") and age < TTL_S and not force:
+        out.update(latest=cache["latest"], checked_at=int(cache["checked_at"]), cached=True)
+    else:
+        try:
+            latest = _fetch()
+        except Exception:
+            # Offline, blocked, rate-limited — fall back to the last good answer
+            # rather than telling anyone anything is wrong.
+            latest = str(cache.get("latest") or "")
+            out["checked_at"] = int(cache.get("checked_at") or 0)
+            out["stale"] = True
+        else:
+            _write_cache(latest)
+            out["checked_at"] = int(time.time())
+        out["latest"] = latest
+    out["update_available"] = _newer(out["latest"], current)
+    return out
+
+
+def notify(log=print):
+    """Print one line if a newer version is out. Safe to call from a thread."""
+    try:
+        u = check()
+    except Exception:
+        return
+    if u.get("update_available"):
+        log(f"  update    : {u['current']} -> {u['latest']}   {u['command']}")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-finops",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local FinOps dashboard for Claude Code: what you used, what it cost, why it cost that much, and what to change. Reads your own transcripts, no API key, no data leaves the machine.",
   "bin": {
     "claude-finops": "bin/claude-finops.js"

package/run.py

@@ -100,6 +100,7 @@ Environment:
   CLAUDE_FINOPS_HOME=/path      where your data lives (default ~/.claude-finops)
   CLAUDE_PROJECTS=/path         where to read transcripts from
   CLAUDE_FINOPS_PYTHON=/path    which Python the npm wrapper should use
+  NO_UPDATE_NOTIFIER=1          never check npm for a newer release
 """
 
 

package/web/app.js

@@ -160,6 +160,7 @@ function shell() {
           <span class="spacer"></span>
           <div class="search"><span class="mag">⌕</span>
             <input id="gsearch" placeholder="Search prompts, sessions, models, dates…"></div>
+          <button class="iconbtn upd" id="upd" hidden></button>
           <button class="iconbtn" id="tour-btn" title="Walk through this dashboard">? Tour</button>
           <button class="iconbtn" id="theme" title="Toggle theme">◐</button>
           <button class="iconbtn" id="refresh" title="Reload data">↻</button>
@@ -182,6 +183,7 @@ function shell() {
     render();
   };
   $('#refresh').onclick = () => { bust(); render(); };
+  updateChip();
   $('#sync').onclick = runSync;
   syncLabel();
   let t;
@@ -190,6 +192,28 @@ function shell() {
       else if (S.view === 'search') go('overview'); }, 260); };
 }
 
+/* ---------- update notice ----------
+   npm cannot push a new release at anyone, so the server asks the registry once
+   a day and we surface the answer here. Silent when you are current, when the
+   check is switched off, and when it simply could not reach the registry. */
+async function updateChip() {
+  const el = $('#upd');
+  if (!el) return;
+  let u;
+  try { u = await fetch('/api/update').then(r => r.json()); } catch { return; }
+  if (!u || !u.update_available) return;
+  el.hidden = false;
+  el.textContent = `↑ v${u.latest} available`;
+  el.title = `You are on ${u.current}. Click to copy:  ${u.command}`;
+  el.onclick = async () => {
+    try {
+      await navigator.clipboard.writeText(u.command);
+      el.textContent = '✓ command copied';
+      setTimeout(() => { el.textContent = `↑ v${u.latest} available`; }, 2200);
+    } catch { prompt('Run this to upgrade:', u.command); }
+  };
+}
+
 /* ---------- filter bar ---------- */
 const RANGES = [['today', 'Today'], ['7d', '7 days'], ['14d', '14 days'], ['30d', '30 days'],
   ['period', 'Billing period'], ['all', 'All time'], ['custom', 'Custom']];

package/web/styles.css

@@ -385,3 +385,13 @@ table.tbl .sub { font-size:10.5px; color:var(--muted); }
 #tour .tour-ft .spacer { flex: 1; }
 #tour .act.primary { background: var(--accent, #eb6834); border-color: var(--accent, #eb6834); color: #fff; }
 #tour .act[disabled] { opacity: .45; cursor: default; }
+
+/* Update notice in the topbar: present, never alarming — this is good news,
+   not a problem, so it borrows the accent colour rather than the warning one. */
+.iconbtn.upd {
+  border-color: var(--accent, #eb6834);
+  color: var(--accent, #eb6834);
+  font-weight: 600;
+  white-space: nowrap;
+}
+.iconbtn.upd:hover { background: var(--accent, #eb6834); color: #fff; }