ct-public/isparkclaw-webui
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: dynamic version badge — read from git tag, never hardcoded (#790)

Browse Source 
* fix: dynamic version badge — read from git tag, never hardcoded

The settings panel showed v0.50.87 and the HTTP Server: header said
HermesWebUI/0.50.38 — both hardcoded strings that drift further behind
with every release because there was no mechanism to keep them in sync.

Changes:
- api/updates.py: add _run_git() (moved before _detect_webui_version),
  _detect_webui_version(), and WEBUI_VERSION module constant resolved
  once at import time via 'git describe --tags --always --dirty'.
  Fallback chain: git → api/_version.py → 'unknown'.
- api/routes.py: inject webui_version into GET /api/settings response
  so the frontend can read it without a separate API call.
- static/panels.js: loadSettingsPanel() populates .settings-version-badge
  from settings.webui_version — one line after the existing api() call.
- static/index.html: replace stale hardcoded 'v0.50.87' with '—'
  placeholder; JS overwrites it as soon as the settings panel opens.
- server.py: replace hardcoded 'HermesWebUI/0.50.38' server_version with
  'HermesWebUI/' + WEBUI_VERSION.lstrip('v') — stays in sync automatically.
- Dockerfile: add ARG HERMES_VERSION=unknown and write api/_version.py
  so Docker images (where .git is excluded) still show the correct tag.
- .github/workflows/release.yml: pass build-args: HERMES_VERSION=${{ github.ref_name }}
  to the Docker build step on tag pushes.
- .gitignore: exclude api/_version.py (generated by Docker/CI, never committed).

No manual 'update the version badge' step is required going forward.
Tagging is sufficient — the badge and HTTP header update automatically.

Tests: 18 new tests in tests/test_version_badge.py covering the full
resolution chain, /api/settings injection, HTML placeholder, JS wiring,
and server.py import. 1596 tests pass total.

* fix: address review feedback on PR #790

- api/updates.py: replace exec() with regex parse for api/_version.py
  (no supply-chain risk from build artifact; exec unnecessary for one assignment)
- api/updates.py: cap git describe timeout at 3s (was 10s — import-time
  stall on NFS/.git would block server startup unnecessarily)
- server.py: lstrip('v') → removeprefix('v') (lstrip strips chars not prefix)
- server.py: emit bare 'HermesWebUI' when version is 'unknown' rather than
  'HermesWebUI/unknown' (log aggregators expect semver-ish suffix or none)
- CHANGELOG.md: add v0.50.124 entry for this user-visible change
- tests: rename exec-error test to reflect regex behaviour; add tests for
  removeprefix usage and unknown-version header guard (1598 tests total)

---------

Co-authored-by: nesquena-hermes <hermes@nesquena.com>
This commit is contained in:
nesquena-hermes
2026-04-20 20:36:53 -07:00
committed by GitHub
parent 81072d34d6
commit 38e215e8f8
10 changed files with 369 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.github/workflows/release.yml vendored
View File

@@ -52,5 +52,6 @@ jobs:
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
build-args: HERMES_VERSION=${{ github.ref_name }}
cache-from: type=gha
cache-to: type=gha,mode=max

3
.gitignore vendored
View File

@@ -28,6 +28,9 @@ copilot-instructions.md
screenshot-*.png
full-UI.png
# Version file written by Docker/CI build — generated, never committed
api/_version.py
# OS files
.DS_Store
Thumbs.db

6
CHANGELOG.md
View File

@@ -1,6 +1,10 @@
# Hermes Web UI -- Changelog
## [v0.50.123] — 2026-04-21
## [v0.50.124] — 2026-04-21
### Fixed
- **Settings version badge now shows the real running version** — the badge in the Settings → System panel was hardcoded to `v0.50.87` (36 releases behind) and the HTTP `Server:` header said `HermesWebUI/0.50.38` (85 behind). Both are now resolved dynamically at server startup from `git describe --tags --always --dirty`. Docker images (where `.git` is excluded) receive the correct tag via a build-time `ARG HERMES_VERSION` written to `api/_version.py`. No manual "update the badge" step is needed going forward — tagging is sufficient. Version file parsing uses regex instead of `exec()` for supply-chain safety. (#790)
### Fixed
- **Default model change surfaced stale value after model-list TTL cache landed** — `set_hermes_default_model()` now explicitly invalidates `_available_models_cache` after `reload_config()`. The 60s TTL cache introduced in v0.50.121 (#780) only invalidates on config-file mtime change, but `reload_config()` resyncs `_cfg_mtime` before `get_available_models()` runs — so the mtime check never fires and the POST response (plus downstream reads within the TTL window) returned the previous model until the cache expired. Root cause of the `test_default_model_updates_hermes_config` CI flake as well. (#788)

7
Dockerfile
View File

@@ -78,6 +78,13 @@ USER hermeswebuitoo
COPY . /apptoo
# Bake the git version tag into the image so the settings badge works even
# when .git is not present (it is excluded by .dockerignore).
# CI passes: --build-arg HERMES_VERSION=$(git describe --tags --always)
# Local builds that omit the arg get "unknown" as the fallback.
ARG HERMES_VERSION=unknown
RUN echo "__version__ = '${HERMES_VERSION}'" > /apptoo/api/_version.py
# Default to binding all interfaces (required for container networking)
ENV HERMES_WEBUI_HOST=0.0.0.0
ENV HERMES_WEBUI_PORT=8787

7
api/routes.py
View File

@@ -548,6 +548,13 @@ def handle_get(handler, parsed) -> bool:
settings = load_settings()
# Never expose the stored password hash to clients
settings.pop("password_hash", None)
# Inject the running version so the UI badge stays in sync with git tags
# without any manual release step.
try:
from api.updates import WEBUI_VERSION
settings["webui_version"] = WEBUI_VERSION
except Exception:
pass
return j(handler, settings)
if parsed.path == "/api/onboarding/status":

42
api/updates.py
View File

@@ -53,6 +53,48 @@ def _run_git(args, cwd, timeout=10):
return f'git failed to start: {exc}', False
def _detect_webui_version() -> str:
"""Detect the running WebUI version from git or a baked-in fallback file.
Resolution order:
1. ``git describe --tags --always --dirty`` — works in any git checkout.
Returns the exact tag on tagged commits (e.g. ``v0.50.124``), a
post-tag descriptor between releases (e.g. ``v0.50.124-1-ge91325d``),
or a bare SHA when no tags exist (shallow clones, fresh forks).
2. ``api/_version.py`` — a fallback written by the Docker / CI release
workflow when ``.git`` is not present in the image. Expected to define
``__version__ = 'vX.Y.Z'``.
3. ``'unknown'`` — last resort; displayed as-is in the settings badge.
"""
# Timeout capped at 3s: git describe on a healthy local repo is <50ms;
# a 10s stall on import (NFS-mounted .git, broken git binary) is unacceptable.
out, ok = _run_git(['describe', '--tags', '--always', '--dirty'], REPO_ROOT, timeout=3)
if ok and out:
return out
# Docker / baked-image fallback: api/_version.py written by CI at build time.
# Parse with regex rather than exec() — the file holds exactly one assignment
# and regex is sufficient; exec() on a build artifact is an unnecessary surface.
version_file = REPO_ROOT / 'api' / '_version.py'
if version_file.exists():
try:
import re as _re
m = _re.search(
r"""__version__\s*=\s*['"]([^'"]+)['"]""",
version_file.read_text(encoding='utf-8'),
)
if m:
return m.group(1)
except Exception:
pass
return 'unknown'
# Resolved once at import time — tags cannot change without a process restart.
WEBUI_VERSION: str = _detect_webui_version()
def _split_remote_ref(ref):
"""Split 'origin/branch-name' into ('origin', 'branch-name').

4
server.py
View File

@@ -18,6 +18,7 @@ from api.config import HOST, PORT, STATE_DIR, SESSION_DIR, DEFAULT_WORKSPACE
from api.helpers import j
from api.routes import handle_get, handle_post
from api.startup import auto_install_agent_deps, fix_credential_permissions
from api.updates import WEBUI_VERSION
class QuietHTTPServer(ThreadingHTTPServer):
@@ -44,7 +45,8 @@ class QuietHTTPServer(ThreadingHTTPServer):
class Handler(BaseHTTPRequestHandler):
timeout = 30 # seconds — kills idle/incomplete connections to prevent thread exhaustion
server_version = 'HermesWebUI/0.50.38'
_ver_suffix = WEBUI_VERSION.removeprefix('v')
server_version = ('HermesWebUI/' + _ver_suffix) if _ver_suffix != 'unknown' else 'HermesWebUI'
def log_message(self, fmt, *args): pass # suppress default Apache-style log
def log_request(self, code: str='-', size: str='-') -> None:

2
static/index.html
View File

@@ -596,7 +596,7 @@
<div class="settings-section-title">System</div>
<div class="settings-section-meta">Instance version and access controls.</div>
</div>
<span class="settings-version-badge">v0.50.87</span>
<span class="settings-version-badge">—</span>
</div>
<div class="settings-field" style="border-top:1px solid var(--border);padding-top:12px;margin-top:8px">
<label for="settingsPassword" data-i18n="settings_label_password">Access Password</label>

4
static/panels.js
View File

@@ -1199,6 +1199,10 @@ function _markSettingsDirty(){
async function loadSettingsPanel(){
try{
const settings=await api('/api/settings');
// Populate the version badge from the server — keeps it in sync with git
// tags automatically without any manual release step.
const vbadge=document.querySelector('.settings-version-badge');
if(vbadge && settings.webui_version) vbadge.textContent=settings.webui_version;
// Hydrate appearance controls first so a slow /api/models request
// cannot overwrite an in-progress theme/skin selection.
const themeSel=$('settingsTheme');

296
tests/test_version_badge.py Normal file
View File

@@ -0,0 +1,296 @@
"""
Tests for the dynamic version badge (issue: stale hardcoded version strings).
Covers:
1. api/updates.py: _detect_webui_version() resolution chain
2. api/updates.py: WEBUI_VERSION module constant is set and non-empty
3. api/routes.py: GET /api/settings includes webui_version key
4. static/index.html: hardcoded stale badge is gone
5. static/panels.js: loadSettingsPanel() populates badge from settings
6. server.py: server_version is not the old hardcoded string
"""
import importlib
import sys
import types
from pathlib import Path
from unittest.mock import patch, MagicMock
REPO_ROOT = Path(__file__).parent.parent
# ---------------------------------------------------------------------------
# 1. _detect_webui_version — resolution chain
# ---------------------------------------------------------------------------
class TestDetectWebUIVersion:
def _fresh_detect(self, mock_run_git=None, version_file_content=None, tmp_path=None):
"""Call _detect_webui_version() with controlled dependencies."""
import api.updates as upd
fake_root = tmp_path or Path('/nonexistent-path')
if version_file_content is not None:
vf = tmp_path / 'api' / '_version.py'
vf.parent.mkdir(parents=True, exist_ok=True)
vf.write_text(version_file_content, encoding='utf-8')
def _run_git_side_effect(args, cwd, timeout=10):
if mock_run_git is not None:
return mock_run_git(args, cwd, timeout)
return ('', False)
with patch.object(upd, '_run_git', side_effect=_run_git_side_effect), \
patch.object(upd, 'REPO_ROOT', fake_root):
return upd._detect_webui_version()
def test_git_success_returns_tag(self, tmp_path):
"""When git describe succeeds, returns the tag string directly."""
result = self._fresh_detect(
mock_run_git=lambda args, cwd, timeout: ('v0.50.123', True),
tmp_path=tmp_path,
)
assert result == 'v0.50.123'
def test_git_between_tags_returns_descriptor(self, tmp_path):
"""Between releases, git describe returns a post-tag descriptor — pass it through."""
result = self._fresh_detect(
mock_run_git=lambda args, cwd, timeout: ('v0.50.123-3-ge91325d', True),
tmp_path=tmp_path,
)
assert result == 'v0.50.123-3-ge91325d'
def test_git_failure_falls_back_to_version_file(self, tmp_path):
"""When git fails (Docker image), falls back to api/_version.py."""
result = self._fresh_detect(
mock_run_git=lambda args, cwd, timeout: ('', False),
version_file_content="__version__ = 'v0.50.100'\n",
tmp_path=tmp_path,
)
assert result == 'v0.50.100'
def test_git_failure_no_version_file_returns_unknown(self, tmp_path):
"""When git fails and no _version.py exists, returns 'unknown'."""
result = self._fresh_detect(
mock_run_git=lambda args, cwd, timeout: ('', False),
tmp_path=tmp_path,
)
assert result == 'unknown'
def test_version_file_malformed_returns_unknown(self, tmp_path):
"""Malformed _version.py (no recognisable __version__ assignment) returns 'unknown'."""
result = self._fresh_detect(
mock_run_git=lambda args, cwd, timeout: ('', False),
version_file_content="this is not valid python !!! ~~~\n",
tmp_path=tmp_path,
)
assert result == 'unknown'
def test_git_uses_correct_describe_flags(self, tmp_path):
"""git describe is called with --tags --always --dirty."""
called_args = []
def capture(args, cwd, timeout=10):
called_args.append(args)
return ('v0.50.123', True)
self._fresh_detect(mock_run_git=capture, tmp_path=tmp_path)
assert called_args, 'git was never called'
assert '--tags' in called_args[0]
assert '--always' in called_args[0]
assert '--dirty' in called_args[0]
# ---------------------------------------------------------------------------
# 2. WEBUI_VERSION module constant
# ---------------------------------------------------------------------------
class TestWebUIVersionConstant:
def test_webui_version_is_set(self):
"""WEBUI_VERSION is a non-empty string exported from api.updates."""
import api.updates as upd
assert hasattr(upd, 'WEBUI_VERSION'), 'WEBUI_VERSION not exported from api.updates'
assert isinstance(upd.WEBUI_VERSION, str)
assert upd.WEBUI_VERSION, 'WEBUI_VERSION must not be empty string'
def test_webui_version_is_not_old_hardcoded(self):
"""WEBUI_VERSION must not be the old stale value from server.py."""
import api.updates as upd
# These were the two stale hardcoded strings before this fix
assert upd.WEBUI_VERSION not in ('0.50.38', 'HermesWebUI/0.50.38'), (
'WEBUI_VERSION still holds the old hardcoded server.py value'
)
# ---------------------------------------------------------------------------
# 3. GET /api/settings includes webui_version
# ---------------------------------------------------------------------------
class TestSettingsEndpointVersion:
def test_api_settings_includes_webui_version(self):
"""GET /api/settings response dict must include webui_version key."""
import api.routes as routes
import api.updates as upd
# Patch load_settings to return a minimal dict (no disk I/O)
minimal_settings = {'send_key': 'enter', 'theme': 'dark'}
handler = MagicMock()
from urllib.parse import urlparse
parsed = urlparse('/api/settings')
captured = {}
def fake_j(h, data, status=200):
captured['data'] = data
with patch('api.routes.load_settings', return_value=dict(minimal_settings)), \
patch('api.routes.j', side_effect=fake_j):
routes.handle_get(handler, parsed)
assert 'webui_version' in captured.get('data', {}), (
'/api/settings response must contain webui_version key'
)
assert captured['data']['webui_version'] == upd.WEBUI_VERSION
def test_api_settings_webui_version_not_empty(self):
"""webui_version in /api/settings must be a non-empty string."""
import api.routes as routes
handler = MagicMock()
from urllib.parse import urlparse
parsed = urlparse('/api/settings')
captured = {}
def fake_j(h, data, status=200):
captured['data'] = data
with patch('api.routes.load_settings', return_value={}), \
patch('api.routes.j', side_effect=fake_j):
routes.handle_get(handler, parsed)
version = captured.get('data', {}).get('webui_version', '')
assert version, 'webui_version in /api/settings must not be empty'
def test_api_settings_no_password_hash(self):
"""password_hash must still be stripped even with version injection."""
import api.routes as routes
handler = MagicMock()
from urllib.parse import urlparse
parsed = urlparse('/api/settings')
captured = {}
def fake_j(h, data, status=200):
captured['data'] = data
with patch('api.routes.load_settings', return_value={'password_hash': 'secret123'}), \
patch('api.routes.j', side_effect=fake_j):
routes.handle_get(handler, parsed)
assert 'password_hash' not in captured.get('data', {}), (
'password_hash must still be stripped from /api/settings'
)
# ---------------------------------------------------------------------------
# 4. static/index.html — no stale hardcoded badge
# ---------------------------------------------------------------------------
class TestIndexHTMLBadge:
def _read_html(self):
return (REPO_ROOT / 'static' / 'index.html').read_text(encoding='utf-8')
def test_old_stale_version_removed_from_html(self):
"""The old hardcoded v0.50.87 badge must not appear in index.html."""
html = self._read_html()
assert 'v0.50.87' not in html, (
'Stale hardcoded version v0.50.87 still present in index.html. '
'The badge should be a neutral placeholder; JS populates it at runtime.'
)
def test_badge_element_still_present(self):
"""settings-version-badge span must still be in the DOM (JS needs the target)."""
html = self._read_html()
assert 'settings-version-badge' in html, (
'settings-version-badge span missing from index.html — JS cannot populate it'
)
# ---------------------------------------------------------------------------
# 5. static/panels.js — badge population from settings
# ---------------------------------------------------------------------------
class TestPanelsJSVersionBadge:
def _read_js(self):
return (REPO_ROOT / 'static' / 'panels.js').read_text(encoding='utf-8')
def test_panels_js_reads_webui_version(self):
"""loadSettingsPanel must reference settings.webui_version to populate the badge."""
src = self._read_js()
assert 'webui_version' in src, (
'panels.js loadSettingsPanel() must read settings.webui_version '
'to populate the badge dynamically'
)
def test_panels_js_targets_version_badge(self):
"""panels.js must target the .settings-version-badge element."""
src = self._read_js()
assert 'settings-version-badge' in src, (
'panels.js must query .settings-version-badge to update the badge text'
)
# ---------------------------------------------------------------------------
# 6. server.py — server_version not the old hardcoded string
# ---------------------------------------------------------------------------
class TestServerVersionHeader:
def test_server_version_not_old_hardcoded(self):
"""server.py Handler.server_version must not be the stale hardcoded value."""
src = (REPO_ROOT / 'server.py').read_text(encoding='utf-8')
assert 'HermesWebUI/0.50.38' not in src, (
'server.py still contains the old hardcoded server_version string. '
'It should use WEBUI_VERSION from api.updates.'
)
def test_server_version_uses_webui_version(self):
"""server.py must reference WEBUI_VERSION when setting server_version."""
src = (REPO_ROOT / 'server.py').read_text(encoding='utf-8')
assert 'WEBUI_VERSION' in src, (
'server.py must import and use WEBUI_VERSION from api.updates '
'to keep the HTTP Server: header in sync with git tags'
)
def test_server_py_imports_webui_version(self):
"""server.py must import WEBUI_VERSION from api.updates."""
src = (REPO_ROOT / 'server.py').read_text(encoding='utf-8')
assert 'from api.updates import WEBUI_VERSION' in src, (
'server.py must import WEBUI_VERSION from api.updates'
)
def test_server_version_no_slash_when_unknown(self):
"""When WEBUI_VERSION is 'unknown', server_version must be bare 'HermesWebUI' with no slash."""
src = (REPO_ROOT / 'server.py').read_text(encoding='utf-8')
# The guard must be present so log aggregators don't see 'HermesWebUI/unknown'
assert "'unknown'" in src or '"unknown"' in src, (
"server.py must guard against emitting 'HermesWebUI/unknown' as the server header"
)
def test_server_version_uses_removeprefix_not_lstrip(self):
"""server.py must use str.removeprefix() to strip 'v', not lstrip() which strips chars."""
src = (REPO_ROOT / 'server.py').read_text(encoding='utf-8')
assert 'lstrip' not in src, (
"server.py must use removeprefix('v') not lstrip('v') — lstrip strips characters, "
"not a prefix, and would incorrectly mangle strings like 'vvv0.50.124'"
)
assert 'removeprefix' in src, (
"server.py must use removeprefix('v') to strip the leading 'v' from the version tag"
)