feat(dashboard): v1.3.0 — footer version, extension promo, update check

Add a single source-of-truth version and surface-aware footer to both the
standalone web dashboard and the embedded VS Code panel.

- scanner.VERSION ("1.3.0") is the runtime version (CHANGELOG isn't bundled
  into the .vsix), surfaced via `python cli.py --version`.
- The dashboard footer now shows the running version linked to its GitHub
  release tag on both surfaces (closes #135).
- The web build additionally promotes the VS Code extension and, when a newer
  release exists, shows an "Update to vX.Y.Z" link. It learns its surface from
  a new `--surface` flag; the extension passes `--surface vscode`, which
  suppresses the promo and the update check (VS Code updates the extension
  itself, and a GitHub-release check would misfire because the Marketplace
  publish lags the GitHub release).
- The update check is one unauthenticated GET to GitHub's public releases API,
  cached in localStorage for 24h and fully fail-silent. No usage data is sent;
  the embedded panel makes no such request. Disclosed in the CHANGELOG.
- Version injected server-side via a window.APP_CONFIG placeholder.
- Tests: three-way version parity (scanner / CHANGELOG / package.json),
  `--version` CLI flag, APP_CONFIG placeholder substitution, surface gating.
- Bumped vscode-extension/package.json to 1.3.0; documented the VERSION bump
  in AGENTS.md's release checklist.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: phuryn

AGENTS.md

@@ -107,7 +107,7 @@ This applies to all agents working on this repo, not just Claude Code.
 
 The release flow:
 1. While work accumulates on `DEV`, the `## vX.Y.Z — TBD` heading at the top of `CHANGELOG.md` collects bullets. (For automated triage runs, see the routine note below.)
-2. When the maintainer is ready to release, they finalize the heading (`TBD` → today's date), **bump `vscode-extension/package.json`'s `version` to match the CHANGELOG version** (the two ship in lockstep — the extension bundles the Python sources), merge `DEV → main` with `merge --no-ff` (so the release boundary is visible in `git log main`), and push `main`.
+2. When the maintainer is ready to release, they finalize the heading (`TBD` → today's date), **bump both `scanner.VERSION` and `vscode-extension/package.json`'s `version` to match the CHANGELOG version** (all three ship in lockstep — the extension bundles the Python sources, and `scanner.VERSION` is the runtime version reported by `cli.py --version` and the dashboard footer since the CHANGELOG isn't bundled into the `.vsix`), merge `DEV → main` with `merge --no-ff` (so the release boundary is visible in `git log main`), and push `main`. A parity test (`tests/test_version.py`) fails the suite if the three drift, so in practice they're bumped together on `DEV` when the version heading is written.
 3. [`.github/workflows/tag-on-merge.yml`](.github/workflows/tag-on-merge.yml) fires on the push, sees the new `## vX.Y.Z` heading in the CHANGELOG diff, and:
    - creates a lightweight tag at the merge commit (**no `git tag` step for the maintainer**), then
    - builds the VS Code extension `.vsix` and publishes a **GitHub Release** for that tag — the matching CHANGELOG section as the release notes, the built `.vsix` attached as a release asset.

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v1.3.0 — TBD
+
+### Dashboard
+
+- The footer now shows the running version, linked to its GitHub release tag, on both the standalone web dashboard and the embedded VS Code panel (#135).
+- The standalone web dashboard now promotes the VS Code extension in the footer and, when a newer release is available, shows an **Update to vX.Y.Z** link to the latest GitHub release. The embedded panel shows neither — VS Code updates the extension itself, so it only displays the version. The dashboard learns its surface from a new `--surface` flag the extension passes (`--surface vscode`).
+- **Version check / privacy:** to power the update link, the standalone web dashboard now makes one unauthenticated request to GitHub's public releases API (`api.github.com/repos/phuryn/claude-usage/releases/latest`), cached in the browser for 24 hours and fully fail-silent (offline, blocked, or rate-limited simply hides the link). It sends **none** of your usage data — only a plain GET for the latest release number. The embedded VS Code panel makes no such request. Your transcripts and usage data never leave your machine.
+
+### Scanner / CLI
+
+- Added a single source-of-truth `VERSION` constant (`scanner.VERSION`) surfaced via `python cli.py --version`. It stays in lockstep with the top CHANGELOG heading and the extension's `package.json` (a parity test enforces all three match).
+
 ## v1.2.6 — 2026-06-15
 
 ### Dashboard

cli.py

@@ -14,6 +14,8 @@
 from pathlib import Path
 from datetime import datetime, date, timedelta
 
+from scanner import VERSION
+
 DB_PATH = Path.home() / ".claude" / "usage.db"
 
 PRICING = {
@@ -364,7 +366,7 @@ def cmd_stats():
     conn.close()
 
 
-def cmd_dashboard(projects_dir=None, host=None, port=None, no_browser=False):
+def cmd_dashboard(projects_dir=None, host=None, port=None, no_browser=False, surface=None):
     import threading
     import time
 
@@ -403,7 +405,7 @@ def open_browser():
 
         threading.Thread(target=open_browser, daemon=True).start()
 
-    serve(host=host, port=port)
+    serve(host=host, port=port, surface=surface)
 
 
 # ── Entry point ───────────────────────────────────────────────────────────────
@@ -416,8 +418,9 @@ def open_browser():
   python cli.py today                        Show today's usage summary
   python cli.py week                         Show last 7 days (per-day + by-model)
   python cli.py stats                        Show all-time statistics
-  python cli.py dashboard [--projects-dir PATH] [--host HOST] [--port PORT] [--no-browser]
+  python cli.py dashboard [--projects-dir PATH] [--host HOST] [--port PORT] [--no-browser] [--surface SURFACE]
                                                  Scan + start dashboard (opens a browser unless --no-browser)
+  python cli.py --version                    Print the version and exit
 """
 
 COMMANDS = {
@@ -436,6 +439,10 @@ def parse_named_arg(args, flag):
     return None
 
 if __name__ == "__main__":
+    if len(sys.argv) >= 2 and sys.argv[1] in ("--version", "-V", "version"):
+        print(VERSION)
+        sys.exit(0)
+
     if len(sys.argv) < 2 or sys.argv[1] not in COMMANDS:
         print(USAGE)
         sys.exit(0)
@@ -450,6 +457,7 @@ def parse_named_arg(args, flag):
             host=parse_named_arg(rest, "--host"),
             port=parse_named_arg(rest, "--port"),
             no_browser="--no-browser" in rest,
+            surface=parse_named_arg(rest, "--surface"),
         )
     elif command == "scan" and projects_dir:
         cmd_scan(projects_dir=projects_dir)

dashboard.py

@@ -10,8 +10,19 @@
 from pathlib import Path
 from datetime import datetime
 
+from scanner import VERSION
+
 DB_PATH = Path.home() / ".claude" / "usage.db"
 
+# Which surface is rendering the dashboard: "web" (standalone `cli.py dashboard`)
+# or "vscode" (embedded in the extension's sidebar webview). serve() sets this
+# from the --surface flag the extension passes. The footer reads it to decide
+# what to show — the web build promotes the VS Code extension and offers a
+# "check GitHub for a newer release" update link; the embedded build shows just
+# the version (VS Code updates the extension itself, and a GitHub-release check
+# would misfire there because the Marketplace publish lags the GitHub release).
+SURFACE = "web"
+
 
 def get_dashboard_data(db_path=DB_PATH):
     if not db_path.exists():
@@ -135,6 +146,7 @@ def get_dashboard_data(db_path=DB_PATH):
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Claude Code Usage Dashboard</title>
 <script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js"></script>
+<script>window.APP_CONFIG = __APP_CONFIG_JSON__;</script>
 <style>
   :root {
     --bg: #161617;      /* page base */
@@ -258,6 +270,7 @@ def get_dashboard_data(db_path=DB_PATH):
   .footer-content p:last-child { margin-bottom: 0; }
   .footer-content a { color: var(--blue); text-decoration: none; }
   .footer-content a:hover { text-decoration: underline; }
+  .footer-content a.update-link { color: var(--accent); font-weight: 600; }
 
   @media (max-width: 768px) { .charts-grid { grid-template-columns: 1fr; } .chart-card.wide { grid-column: 1; } }
 </style>
@@ -398,6 +411,7 @@ def get_dashboard_data(db_path=DB_PATH):
       &nbsp;&middot;&nbsp;
       License: MIT
     </p>
+    <p id="footer-meta"></p>
   </div>
 </footer>
 
@@ -1471,6 +1485,82 @@ def get_dashboard_data(db_path=DB_PATH):
   }
 }
 
+// ── Footer meta: version, extension promo, update check ──────────────────────
+// APP_CONFIG is injected server-side (see do_GET). { version, surface }.
+const APP_CONFIG = window.APP_CONFIG || { version: '', surface: 'web' };
+const REPO_URL = 'https://github.com/phuryn/claude-usage';
+const MARKETPLACE_URL = 'https://marketplace.visualstudio.com/items?itemName=PawelHuryn.claude-usage-phuryn';
+const UPDATE_CACHE_KEY = 'cu_update_check';
+const UPDATE_CACHE_TTL = 24 * 60 * 60 * 1000;  // re-check GitHub at most once a day
+
+// Compare dotted numeric versions ("1.3.0"); leading "v" tolerated. Returns
+// true only when `latest` is strictly ahead of `current`.
+function isNewer(latest, current) {
+  const a = String(latest).replace(/^v/, '').split('.').map(n => parseInt(n, 10) || 0);
+  const b = String(current).replace(/^v/, '').split('.').map(n => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const x = a[i] || 0, y = b[i] || 0;
+    if (x > y) return true;
+    if (x < y) return false;
+  }
+  return false;
+}
+
+function appendUpdateLink(latest) {
+  const el = document.getElementById('footer-meta');
+  if (!el || !el.innerHTML) return;
+  const a = document.createElement('a');
+  a.className = 'update-link';
+  a.href = REPO_URL + '/releases/latest';
+  a.target = '_blank';
+  a.rel = 'noopener';
+  a.textContent = 'Update to v' + latest;
+  el.insertAdjacentHTML('beforeend', '&nbsp;&middot;&nbsp;');
+  el.appendChild(a);
+}
+
+// Web only. Asks GitHub's public releases API whether a newer release exists and,
+// if so, appends an "Update to vX.Y.Z" link. Cached in localStorage for 24h and
+// fully fail-silent (offline / rate-limited / blocked -> no link, no error). No
+// usage data is sent; this is a plain unauthenticated GET of release metadata.
+function checkForUpdate(current) {
+  let cached = null;
+  try { cached = JSON.parse(localStorage.getItem(UPDATE_CACHE_KEY) || 'null'); } catch (e) {}
+  if (cached && cached.latest && cached.ts && (Date.now() - cached.ts) < UPDATE_CACHE_TTL) {
+    if (isNewer(cached.latest, current)) appendUpdateLink(cached.latest);
+    return;
+  }
+  fetch('https://api.github.com/repos/phuryn/claude-usage/releases/latest', {
+    headers: { 'Accept': 'application/vnd.github+json' }
+  })
+    .then(r => r.ok ? r.json() : null)
+    .then(data => {
+      if (!data || !data.tag_name) return;
+      const latest = String(data.tag_name).replace(/^v/, '');
+      try { localStorage.setItem(UPDATE_CACHE_KEY, JSON.stringify({ ts: Date.now(), latest: latest })); } catch (e) {}
+      if (isNewer(latest, current)) appendUpdateLink(latest);
+    })
+    .catch(() => {});  // fail-silent: never let a version check disrupt the dashboard
+}
+
+function initFooterMeta() {
+  const el = document.getElementById('footer-meta');
+  if (!el) return;
+  const v = APP_CONFIG.version || '';
+  const parts = [];
+  if (v) {
+    parts.push('Version <a href="' + REPO_URL + '/releases/tag/v' + esc(v) + '" target="_blank" rel="noopener">v' + esc(v) + '</a>');
+  }
+  // The web build promotes the extension; the embedded build is already in it.
+  if (APP_CONFIG.surface !== 'vscode') {
+    parts.push('<a href="' + MARKETPLACE_URL + '" target="_blank" rel="noopener">Get the VS Code extension</a>');
+  }
+  el.innerHTML = parts.join('&nbsp;&middot;&nbsp;');
+  // VS Code auto-updates the extension, so only the web build checks for updates.
+  if (v && APP_CONFIG.surface !== 'vscode') checkForUpdate(v);
+}
+
+initFooterMeta();
 loadData();
 scheduleAutoRefresh();
 </script>
@@ -1510,10 +1600,17 @@ def do_GET(self):
         # URLs don't fall through to 404.
         path = urlparse(self.path).path
         if path in ("/", "/index.html"):
+            # Inject runtime config (version + surface) the page can't know at
+            # author time. json.dumps produces a valid JS object literal for the
+            # `window.APP_CONFIG = __APP_CONFIG_JSON__;` placeholder in the head.
+            config = json.dumps({"version": VERSION, "surface": SURFACE})
+            html = HTML_TEMPLATE.replace("__APP_CONFIG_JSON__", config)
+            body = html.encode("utf-8")
             self.send_response(200)
             self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
             self.end_headers()
-            self.wfile.write(HTML_TEMPLATE.encode("utf-8"))
+            self.wfile.write(body)
 
         elif path == "/api/data":
             data = get_dashboard_data()
@@ -1570,7 +1667,10 @@ def do_POST(self):
             self.end_headers()
 
 
-def serve(host=None, port=None):
+def serve(host=None, port=None, surface=None):
+    global SURFACE
+    if surface:
+        SURFACE = surface
     host = host or os.environ.get("HOST", "localhost")
     port = port or int(os.environ.get("PORT", "8080"))
     server = ThreadingHTTPServer((host, port), DashboardHandler)

scanner.py

@@ -9,6 +9,14 @@
 from pathlib import Path
 from datetime import datetime, timezone
 
+# Single source of truth for the app version reported by the CLI (`--version`)
+# and the dashboard footer. CHANGELOG.md is the canonical version reference, but
+# it isn't bundled into the .vsix — only the three Python files are — so the
+# runtime version has to live here as a constant. Keep this in lockstep with the
+# top CHANGELOG heading and vscode-extension/package.json (a parity test guards
+# all three; see tests/test_version.py).
+VERSION = "1.3.0"
+
 PROJECTS_DIR = Path.home() / ".claude" / "projects"
 XCODE_PROJECTS_DIR = Path.home() / "Library" / "Developer" / "Xcode" / "CodingAssistant" / "ClaudeAgentConfig" / "projects"
 DB_PATH = Path.home() / ".claude" / "usage.db"

tests/test_dashboard.py

@@ -383,6 +383,20 @@ def test_404_for_unknown_path(self):
         except urllib.error.HTTPError as e:
             self.assertEqual(e.code, 404)
 
+    def test_index_injects_app_config(self):
+        # do_GET must substitute the __APP_CONFIG_JSON__ placeholder with a real
+        # JSON object (version + surface). The raw placeholder must never reach
+        # the browser, or window.APP_CONFIG would be a syntax error.
+        from scanner import VERSION
+        url = f"http://127.0.0.1:{self.port}/"
+        with urllib.request.urlopen(url) as resp:
+            body = resp.read().decode("utf-8")
+        self.assertNotIn("__APP_CONFIG_JSON__", body)
+        self.assertIn("window.APP_CONFIG =", body)
+        self.assertIn(VERSION, body)
+        # The HTTP test server keeps the default surface ("web").
+        self.assertIn('"surface": "web"', body)
+
 
 class TestHTMLTemplate(unittest.TestCase):
     def test_template_is_valid_html(self):
@@ -426,6 +440,22 @@ def test_today_range_button_present(self):
         # Bounds case: today returns start === end === today's ISO date
         self.assertIn("range === 'today'", HTML_TEMPLATE)
 
+    def test_app_config_placeholder_present(self):
+        """The head carries the server-substituted config placeholder and the
+        footer carries the element + JS the version/update feature drives."""
+        self.assertIn("__APP_CONFIG_JSON__", HTML_TEMPLATE)
+        self.assertIn("window.APP_CONFIG", HTML_TEMPLATE)
+        self.assertIn('id="footer-meta"', HTML_TEMPLATE)
+        self.assertIn("function initFooterMeta(", HTML_TEMPLATE)
+        self.assertIn("function checkForUpdate(", HTML_TEMPLATE)
+
+    def test_update_check_is_surface_gated(self):
+        """The GitHub update check and the extension promo are web-only: both
+        guard on surface !== 'vscode' so the embedded panel stays quiet."""
+        self.assertIn("APP_CONFIG.surface !== 'vscode'", HTML_TEMPLATE)
+        # The update check hits GitHub's public releases API, not any usage data.
+        self.assertIn("api.github.com/repos/phuryn/claude-usage/releases/latest", HTML_TEMPLATE)
+
 
 class TestPricingParity(unittest.TestCase):
     """Verify CLI and dashboard pricing tables stay in sync."""

tests/test_version.py

@@ -0,0 +1,75 @@
+"""Tests for the single source-of-truth version (scanner.VERSION).
+
+The runtime version lives in scanner.py because the canonical CHANGELOG.md is
+NOT bundled into the .vsix — only the three Python files are. These tests keep
+the three places a version is written from drifting: scanner.VERSION, the top
+CHANGELOG heading, and vscode-extension/package.json. If you bump one, bump all.
+"""
+
+import json
+import re
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+from scanner import VERSION
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+
+def _changelog_top_version():
+    """Return the version from the first '## vX.Y.Z' heading in CHANGELOG.md."""
+    changelog = (REPO_ROOT / "CHANGELOG.md").read_text(encoding="utf-8")
+    for line in changelog.splitlines():
+        m = re.match(r"^## v(\d+\.\d+\.\d+)(\s|$)", line)
+        if m:
+            return m.group(1)
+    return None
+
+
+def _package_json_version():
+    pkg = json.loads(
+        (REPO_ROOT / "vscode-extension" / "package.json").read_text(encoding="utf-8")
+    )
+    return pkg["version"]
+
+
+class TestVersion(unittest.TestCase):
+    def test_version_is_strict_semver(self):
+        self.assertRegex(VERSION, r"^\d+\.\d+\.\d+$")
+
+    def test_cli_reexports_same_version(self):
+        # cli.py imports VERSION from scanner so `cli.py --version` reports it.
+        import cli
+        self.assertEqual(cli.VERSION, VERSION)
+
+    def test_matches_changelog_heading(self):
+        top = _changelog_top_version()
+        self.assertEqual(
+            top, VERSION,
+            f"scanner.VERSION ({VERSION}) != top CHANGELOG heading ({top}). "
+            "Bump both in lockstep.",
+        )
+
+    def test_matches_package_json(self):
+        pkg = _package_json_version()
+        self.assertEqual(
+            pkg, VERSION,
+            f"scanner.VERSION ({VERSION}) != vscode-extension/package.json "
+            f"version ({pkg}). The .vsix asset filename embeds the package "
+            "version, so they must match.",
+        )
+
+    def test_cli_version_flag(self):
+        """`python cli.py --version` prints the version and exits 0."""
+        result = subprocess.run(
+            [sys.executable, "cli.py", "--version"],
+            cwd=REPO_ROOT, capture_output=True, text=True,
+        )
+        self.assertEqual(result.returncode, 0)
+        self.assertEqual(result.stdout.strip(), VERSION)
+
+
+if __name__ == "__main__":
+    unittest.main()

vscode-extension/package.json

@@ -2,7 +2,7 @@
   "name": "claude-usage-phuryn",
   "displayName": "Claude Code Usage by Paweł Huryn",
   "description": "Embed your Claude Code usage dashboard (token counts, costs, sessions, projects) directly inside VS Code. Reads local JSONL transcripts, no API calls.",
-  "version": "1.2.6",
+  "version": "1.3.0",
   "publisher": "PawelHuryn",
   "author": {
     "name": "Paweł Huryn",

vscode-extension/src/extension.ts

@@ -113,7 +113,10 @@ class Extension {
     const probeUrl = `http://${host}:${port}/api/data`;
     // --no-browser: the dashboard is embedded in the webview, so the bundled
     // cli.py must not also pop a system browser (it does by default for CLI users).
-    const spawnArgs = dashboardSpawnArgs(mode, python, ["--no-browser", "--host", host, "--port", String(port)]);
+    // --surface vscode: tells the dashboard it's embedded so its footer shows the
+    // version only — no "get the extension" promo (we're already in it) and no
+    // GitHub update check (VS Code updates the extension itself).
+    const spawnArgs = dashboardSpawnArgs(mode, python, ["--no-browser", "--host", host, "--port", String(port), "--surface", "vscode"]);
     if (!spawnArgs) {
       const msg = "Could not assemble a valid command to spawn the dashboard.";
       this.output.appendLine(msg);