claude-finops 0.2.0 → 0.4.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/analytics.py

@@ -30,22 +30,57 @@ def _merge(base, over):
     return base
 
 
+# claude_max -> "Max", claude_pro -> "Pro": the tier string carries a 5x/20x
+# suffix we keep, because which Max you are on changes every limit in the app.
+_PLANS = {"claude_max": "Max", "claude_pro": "Pro", "claude_team": "Team",
+          "claude_enterprise": "Enterprise"}
+
+
+def _plan(acct):
+    base = _PLANS.get(acct.get("organizationType") or "")
+    mult = ""
+    tier = str(acct.get("organizationRateLimitTier") or "")
+    if base == "Max":
+        for m in ("5x", "20x"):
+            if tier.endswith(m):
+                mult = " " + m
+    return (base + mult) if base else ""
+
+
 def detect_account():
-    """The signed-in Claude Code account, read from ~/.claude.json (actual, not guessed)."""
+    """Who Claude Code is signed in as, read from ~/.claude.json (actual, not guessed).
+
+    Everything here is already on this machine, written by Claude Code itself at
+    login. We only surface it, so a shared screenshot says whose numbers these
+    are — a dashboard with no name on it is the one people misread.
+    """
     try:
         with open(os.path.expanduser("~/.claude.json")) as fh:
             acct = json.load(fh).get("oauthAccount") or {}
     except (OSError, ValueError):
         return {}
-    return {"label": acct.get("emailAddress")} if acct.get("emailAddress") else {}
+    email = acct.get("emailAddress") or ""
+    name = acct.get("fullName") or acct.get("displayName") or ""
+    org = acct.get("organizationName") or ""
+    out = {"name": name, "email": email,
+           # A personal plan names the org after the person; repeating it is noise.
+           "org": "" if org == name else org,
+           "plan": _plan(acct)}
+    if email:
+        out["label"] = email
+    return {k: v for k, v in out.items() if v}
 
 
 def load_settings():
     """Shared defaults (settings.json) + this machine's overrides (settings.local.json)."""
     with open(SETTINGS_PATH) as fh:
         cur = json.load(fh)
-    if not cur.get("account", {}).get("label"):
-        cur.setdefault("account", {}).update(detect_account())
+    # Detected identity first, so a configured settings.json still wins below.
+    detected = detect_account()
+    acct = cur.setdefault("account", {})
+    for k, v in detected.items():
+        if not acct.get(k):
+            acct[k] = v
     if os.path.exists(LOCAL_SETTINGS_PATH):
         with open(LOCAL_SETTINGS_PATH) as fh:
             _merge(cur, json.load(fh))

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/report.py

@@ -3,6 +3,15 @@ import html
 from datetime import datetime, timezone
 
 
+def _who(acct):
+    """"Mohit Raj Purohit <mohit@example.com>" when we know both, else whichever
+    one we have. A report that leaves the house should name its account."""
+    name, email = acct.get("name") or "", acct.get("email") or acct.get("label") or ""
+    if name and email:
+        return f"{name} <{email}>"
+    return name or email or "unknown"
+
+
 def _f(v, kind="usd"):
     if v is None:
         return "&mdash;"
@@ -52,7 +61,7 @@ td:nth-child(n+2) {{ font-variant-numeric: tabular-nums; }}
 ul {{ margin:6px 0 12px 18px; padding:0; }} li {{ margin-bottom:4px; }}
 </style></head><body>
 <h1>Claude AI FinOps Report</h1>
-<div class="sub">Account {html.escape(str(a.settings['account'].get('label')))} &middot;
+<div class="sub">Account {html.escape(_who(a.settings['account']))} &middot;
  Billing period {bp['start']} &rarr; {bp['end']} &middot;
  Data {ov['date_range']['first']} &ndash; {ov['date_range']['last']} &middot;
  Generated {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M UTC')}</div>

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.4.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

@@ -151,7 +151,8 @@ function shell() {
       <nav class="nav">${NAV.map(([g, items], gi) => `<div class="group g${gi}">${g}</div>` +
         items.map(([id, ic, label]) =>
           `<a data-view="${id}" class="g${gi}${id === 'diagnose' ? ' start' : ''}"><span class="ic">${ic}</span>${label}<span class="nb" data-nb="${id}"></span></a>`).join('')).join('')}
-      </nav></aside>
+      </nav>
+      <div class="who" id="who"></div></aside>
     <div class="main">
       <header class="topbar">
         <div class="r1">
@@ -160,6 +161,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 +184,7 @@ function shell() {
     render();
   };
   $('#refresh').onclick = () => { bust(); render(); };
+  updateChip();
   $('#sync').onclick = runSync;
   syncLabel();
   let t;
@@ -190,6 +193,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']];
@@ -2199,9 +2224,27 @@ const navAllowed = scope => !scope || (scope === 'claude' ? hasClaude()
   : scope === 'cloud' ? hasCloudKey() : hasPriced());
 // "Claude Code", "Codex", or "agent" for a mixed selection: used in data-availability text
 const agentWord = () => { const a = selAgents(); return a.length === 1 ? a[0].name : 'agent'; };
+// Whose usage this is. Read from ~/.claude.json by the server, so a screenshot
+// or a shared dashboard always says which account the numbers belong to.
+function whoBlock() {
+  const el = $('#who'), a = S.opts?.settings?.account || {};
+  if (!el) return;
+  if (!a.name && !a.email) { el.innerHTML = ''; return; }
+  const initials = (a.name || a.email || '?').split(/[\s@.]+/).filter(Boolean)
+    .slice(0, 2).map(w => w[0].toUpperCase()).join('');
+  el.innerHTML = `<div class="av">${esc(initials)}</div>
+    <div class="id">
+      <div class="nm">${esc(a.name || a.email)}</div>
+      <div class="em" title="${esc(a.email || '')}">${esc(a.email || '')}</div>
+      ${a.plan || a.org ? `<div class="pl">${esc([a.plan, a.org].filter(Boolean).join(' · '))}</div>` : ''}
+    </div>`;
+  el.title = `Claude Code is signed in as ${a.name || ''} <${a.email || ''}>`.trim();
+}
+
 function applyAgentChrome() {
   const a = selAgents();
   const label = a.length === 1 ? a[0].name.replace(/ (Code|CLI)$/, '') : a.length ? 'Multi-agent' : 'AI';
+  whoBlock();
   const mark = $('.brand .mark');
   if (mark) mark.innerHTML = `<span class="dot"></span>${esc(label)} FinOps`;
   const sub = $('.brand .sub');

package/web/styles.css

@@ -77,7 +77,8 @@ button, input, select { font: inherit; color: inherit; }
 /* ---------- shell ---------- */
 .app { display: grid; grid-template-columns: 216px 1fr; min-height: 100vh; }
 .sidebar { background: var(--surface); border-right: 1px solid var(--border);
-           padding: 14px 0; position: sticky; top:0; height:100vh; overflow-y:auto; }
+           padding: 14px 0; position: sticky; top:0; height:100vh; overflow-y:auto;
+           display:flex; flex-direction:column; }
 .brand { padding: 0 16px 14px; border-bottom: 1px solid var(--border); margin-bottom: 10px; }
 .brand .mark { display:flex; align-items:center; gap:8px; font-weight:660; font-size:14px;
                letter-spacing:-0.01em; }
@@ -385,3 +386,31 @@ 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; }
+
+/* Whose account this dashboard is reading — pinned to the foot of the sidebar,
+   so every screenshot carries the name of the account it came from. */
+/* Sticky, because the nav is taller than the viewport and an identity you have
+   to scroll to find is one nobody checks. */
+.who { margin-top:auto; position:sticky; bottom:0; z-index:2;
+       display:flex; align-items:center; gap:9px;
+       padding:12px 16px; background:var(--surface);
+       border-top:1px solid var(--border); }
+.who:empty { display:none; }
+.who .av { flex:none; width:26px; height:26px; border-radius:50%; display:grid;
+           place-items:center; font-size:10.5px; font-weight:700; color:#fff;
+           background: var(--accent, #eb6834); }
+.who .id { min-width:0; }
+.who .nm { font-size:11.5px; font-weight:620; line-height:1.25;
+           overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+.who .em, .who .pl { font-size:10px; color:var(--muted); line-height:1.35;
+                     overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }