feat: add automatic update check notification for binary users #1039

PR
PR description

Summary

  • Problem: Binary users have no way to know a new version exists without manually checking GitHub
  • Why it matters: Archon releases frequently and users fall behind without realizing it
  • What changed: Added cache-based update notification in CLI (stderr one-liner) and Web UI (TopNav badge). Fixed release skill asset count (6 -> 7).
  • What did not change (scope boundary): No auto-update, no dismiss-per-version, no config option for staleness window. Source builds are unaffected.

UX Journey

Before

CLI:
  $ archon workflow run assist "hello"
  [assist] Started
  [assist] Completed (3.2s)
  $                              <-- no update info

Web UI:
  ┌─────────────────────────────────────────────────────┐
  │  Chat   Dashboard   Workflows   Settings   v0.3.2  │  <-- static version
  └─────────────────────────────────────────────────────┘

After

CLI:
  $ archon workflow run assist "hello"
  [assist] Started
  [assist] Completed (3.2s)
  Update available: v0.3.2 → v0.4.0 — https://github.com/coleam00/Archon/releases/tag/v0.4.0
  $

Web UI:
  ┌──────────────────────────────────────────────────────────┐
  │  Chat   Dashboard   Workflows   Settings   v0.3.2 ● v0.4.0  │
  └──────────────────────────────────────────────────────────┘
                                                  └── pulsing dot, links to release

Architecture Diagram

Before

CLI (cli.ts)  ──▶  commands  ──▶  exit
Server (api.ts)  ──▶  /api/health  ──▶  version string
Web (TopNav.tsx)  ──▶  static version display

After

CLI (cli.ts)  ──▶  commands  ──▶  [+] printUpdateNotice()  ──▶  exit
                                      │
                                      ▼
                               [+] @archon/paths/update-check
                                      │
                                      ▼
                               [+] ~/.archon/update-check.json (cache)
                               [+] GitHub API /releases/latest (if stale)

Server (api.ts)  ──▶  [+] /api/update-check  ──▶  @archon/paths/update-check
Web (TopNav.tsx)  ──▶  [+] useQuery(['update-check'])  ──▶  /api/update-check

Connection inventory:

From To Status Notes
cli.ts @archon/paths modified Added checkForUpdate, BUNDLED_IS_BINARY, BUNDLED_VERSION imports
api.ts @archon/paths modified Added checkForUpdate import
api.ts system.schemas.ts new New schema file for update-check response
TopNav.tsx api.ts (web) new getUpdateCheck() API call
update-check.ts archon-paths.ts new getArchonHome() for cache path
update-check.ts GitHub API new Fetch /releases/latest

Label Snapshot

  • Risk: risk: low
  • Size: size: M
  • Scope: paths, cli, server, web, skills
  • Module: paths:update-check, cli:notification, server:api, web:topnav

Change Metadata

  • Change type: feature
  • Primary scope: multi

Linked Issue

  • None

Validation Evidence (required)

bun run validate  # All pass
  • Type check: 0 errors across 9 packages
  • Lint: 0 errors, 0 warnings
  • Format: All files pass
  • Tests: All pass including 18 new tests (isNewerVersion: 6, parseLatestRelease: 4, checkForUpdate: 5, getCachedUpdateCheck: 3)

Security Impact (required)

  • New permissions/capabilities? No
  • New external network calls? Yes — GitHub API /repos/coleam00/Archon/releases/latest (public, no auth, 60 req/hr limit)
  • Secrets/tokens handling changed? No
  • File system access scope changed? Yes — writes ~/.archon/update-check.json cache file
  • Risk: GitHub API call is unauthenticated, public endpoint. Cache file is in user-owned Archon home dir. All network errors silently swallowed — never affects CLI exit code.

Compatibility / Migration

  • Backward compatible? Yes
  • Config/env changes? No
  • Database migration needed? No

Human Verification (required)

  • Verified scenarios: Unit tests cover all core logic paths
  • Edge cases checked: Network timeout, corrupt cache, stale cache, equal versions, v-prefix stripping
  • What was not verified: Binary build end-to-end test (requires scripts/build-binaries.sh)

Side Effects / Blast Radius (required)

  • Affected subsystems/workflows: CLI exit path (adds up to 3s on first daily run), Web UI TopNav, new API endpoint
  • Potential unintended effects: 3s timeout on first daily CLI run could slow interactive workflows. Mitigated: only binary builds, only when cache is stale (once per 24h).
  • Guardrails/monitoring for early detection: All errors silently swallowed. --quiet flag suppresses notice entirely.

Rollback Plan (required)

  • Fast rollback command/path: Revert the commit. No database migration, no config changes.
  • Feature flags or config toggles: --quiet suppresses CLI notice. Source builds (BUNDLED_IS_BINARY === false) skip entirely.
  • Observable failure symptoms: Update notice showing wrong versions, or 3s delay on every CLI run (would indicate cache write failure).

Risks and Mitigations

  • Risk: GitHub API rate limit (60/hr unauthenticated)
    • Mitigation: 24h cache window means ~1 request/day per user
  • Risk: 3s timeout slows CLI once per day
    • Mitigation: Acceptable tradeoff; only binary builds, suppressed by --quiet

Summary by CodeRabbit

  • New Features

    • Automatic update checking with CLI notice and web UI indicator/link when a newer release exists
    • Public HTTP endpoint exposing update status for clients

  • Documentation

    • Docs updated to describe the update-check API and local cache (24‑hour TTL) and release workflow guidance

  • Tests

    • Added unit/integration tests covering update-check parsing, caching and network behavior
CUT
cutter bot commented just now

Cutter Summary

⚠ Coverage limit — Binary update-check is mocked at the network layer: the dev server always returns updateAvailable: false because the running stack is a source build (BUNDLED_IS_BINARY=false), so the badge is only reachable via a fixture response.