diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 98946a4e..8f6e5abb 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -7,10 +7,12 @@ > > Keep this document updated as architecture changes are made. -> Current shipped build: `v0.51.54` (May 13, 2026). -> Automated coverage: 5303 tests via `pytest tests/ --collect-only -q`. CI runs on Python 3.11, 3.12, and 3.13 against every PR. +> Current shipped build: `v0.51.192` (May 31, 2026). +> Automated coverage: ~7,150 tests via `pytest tests/ --collect-only -q`. CI runs on +> Python 3.11, 3.12, and 3.13 (3 parallel shards each) against every PR, plus a ruff +> lint gate, a headless browser smoke test, and a Docker smoke test. > -> Notable architecture state as of v0.51.54: the bootstrap and first-run onboarding flow own setup discovery; the default WebUI state directory is `~/.hermes/webui`; `ctl.sh` provides a daemon wrapper for homelab installs; chat streaming is still WebUI-owned SSE with stream-ownership guards, cancellation, async manual compression, and turn-journal audit plumbing; provider/model discovery is profile-aware with live-model cache invalidation and custom-provider scoping. +> Notable architecture state: the bootstrap and first-run onboarding flow own setup discovery; the default WebUI state directory is `~/.hermes/webui`; `ctl.sh` provides a daemon wrapper for homelab installs; chat streaming is still WebUI-owned SSE with stream-ownership guards, cancellation, async manual compression, and turn-journal audit plumbing; provider/model discovery is profile-aware with live-model cache invalidation and custom-provider scoping. (Version/test-count numbers above are a periodic snapshot — the authoritative source is the latest git tag and `pytest --collect-only`.) --- diff --git a/README.md b/README.md index 567339cb..447709a3 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,20 @@ This gives you nearly **1:1 parity with Hermes CLI from a convenient web UI** wh --- +## Contents + +- [Why Hermes](#why-hermes) — what it is and how it compares +- [Quick start](#quick-start) — clone + `bootstrap.py` / `start.sh` / `ctl.sh` +- [Docker](#docker) — single- and multi-container deploys +- [Configuration & access](#what-startsh-discovers-automatically) — auto-discovery, overrides, remote/Tailscale/phone, manual launch +- [Running tests](#running-tests) +- [Features](#features) — chat, sessions, workspace, voice, profiles, security, themes, panels, mobile +- [Architecture](#architecture) — backend/frontend layout, state dir +- [Docs](#docs) — the full documentation index +- [Contributors](#contributors) + +--- + ## Why Hermes Most AI tools reset every session. They don't know who you are, what you worked on, or what @@ -480,7 +494,8 @@ Or using the agent venv explicitly: Tests run against an isolated server with a separate state directory. Production data and real cron jobs are never touched. Current snapshot: -**5303 tests collected** across **488 test files**. +**~7,150 tests collected** across **~700 test files**, run in CI on Python 3.11, +3.12, and 3.13 (3 parallel shards each). --- @@ -607,69 +622,100 @@ Production data and real cron jobs are never touched. Current snapshot: ## Architecture +No build step, no framework, no bundler — a Python standard-library HTTP server +and vanilla JS. The backend lives in `api/`, the frontend in `static/`. + +**Backend (`api/`)** + ``` -server.py HTTP routing shell + auth middleware (~446 lines) +server.py HTTP routing shell + auth middleware api/ - auth.py Optional password authentication, signed cookies (~366 lines) - config.py Discovery, globals, model detection, reloadable config (~4139 lines) - helpers.py HTTP helpers, security headers (~302 lines) - models.py Session model + CRUD + CLI bridge (~1927 lines) - onboarding.py First-run onboarding wizard, OAuth provider support (~1002 lines) - profiles.py Profile state management, hermes_cli wrapper (~1056 lines) - routes.py All GET + POST route handlers (~9772 lines) - state_sync.py /insights sync — message_count to state.db (~118 lines) - streaming.py SSE engine, run_agent, cancel support (~4420 lines) - updates.py Self-update check and release notes (~545 lines) - upload.py Multipart parser, file upload handler (~284 lines) - workspace.py File ops, workspace helpers, git detection (~810 lines) -static/ - index.html HTML template (~1323 lines) - style.css All CSS incl. mobile responsive, themes (~3767 lines) - ui.js DOM helpers, renderMd, tool cards, context indicator (~7216 lines) - workspace.js File preview, file ops, git badge (~369 lines) - sessions.js Session CRUD, collapsible groups, search, reload recovery (~3517 lines) - messages.js send(), SSE handlers, live streaming, session recovery (~2301 lines) - panels.js Cron, skills, memory, profiles, settings (~6480 lines) - commands.js Slash command autocomplete (~1302 lines) - boot.js Mobile nav, voice input, boot IIFE (~1607 lines) -tests/ - conftest.py Isolated test server/state fixtures - 488 test files 5303 tests collected -Dockerfile python:3.12-slim container image -docker-compose.yml Compose with named volume and optional auth -.github/workflows/ CI: multi-arch Docker build + GitHub Release on tag + auth.py Optional password authentication, signed cookies, passkeys + config.py Discovery, globals, model detection, reloadable config + helpers.py HTTP helpers, security headers + models.py Session model + CRUD + CLI/state.db bridge + onboarding.py First-run onboarding wizard, OAuth provider support + profiles.py Profile state management, hermes_cli wrapper + routes.py All GET + POST route handlers (if/elif dispatch, no decorators) + state_sync.py /insights sync — message_count to state.db + streaming.py SSE engine, run_agent, cancellation, compression + updates.py Self-update check and release notes + upload.py Multipart parser, file upload handler + workspace.py File ops, workspace helpers, git detection +``` + +**Frontend (`static/`)** + +``` +index.html HTML template +style.css All CSS incl. mobile responsive, themes + skins +ui.js DOM helpers, renderMd, tool cards, context indicator +workspace.js File preview, file ops, git badge, central api() fetch wrapper +sessions.js Session CRUD, collapsible groups, search, reload recovery +messages.js send(), SSE handlers, live streaming, session recovery +panels.js Cron, skills, memory, profiles, settings (Control Center) +commands.js Slash command autocomplete +boot.js Mobile nav, voice input, theme/skin boot, bfcache handler +``` + +**Tests + packaging** + +``` +tests/ Pytest suite (~7,150 tests; isolated server/state fixtures) +pyproject.toml Tooling config (ruff lint gate) — not a packaged distribution +Dockerfile python:3.12-slim container image +docker-compose.yml Compose with named volume and optional auth +.github/workflows/ CI: ruff + sharded pytest, browser smoke, Docker smoke, + multi-arch Docker build + GitHub Release on tag ``` State lives outside the repo at `~/.hermes/webui/` by default (sessions, workspaces, settings, projects, last_workspace). Override with `HERMES_WEBUI_STATE_DIR`. +Full design notes and the endpoint catalog are in [`ARCHITECTURE.md`](ARCHITECTURE.md). --- ## Docs -- `docs/why-hermes.md` -- why Hermes, mental model, and detailed comparison to Claude Code / Codex / OpenCode / Cursor -- `ROADMAP.md` -- feature roadmap and sprint history -- `ARCHITECTURE.md` -- system design, all API endpoints, implementation notes -- `TESTING.md` -- manual browser test plan and automated coverage reference -- `CHANGELOG.md` -- release notes per sprint -- `SPRINTS.md` -- forward sprint plan with CLI + Claude parity targets -- `THEMES.md` -- theme system documentation, custom theme guide -- `docs/CONTRACTS.md` -- project contract/RFC/design index for contributors and agents -- `docs/UIUX-GUIDE.md` -- UI/UX principles sourced from existing design docs and visual inventories -- `docs/docker.md` -- Docker compose setup, common failures, and bind-mount migration -- `docs/supervisor.md` -- launchd, systemd, supervisord, runit, and s6 process-supervisor setup -- `docs/onboarding.md` -- first-run wizard, provider setup, local model server Base URLs, and safe re-runs -- `docs/onboarding-agent-checklist.md` -- safety rules, evidence commands, and pass/fail checks for assistant-led install or reinstall support -- `docs/troubleshooting.md` -- diagnostic flows for common failures (e.g. "AIAgent not available") -- `docs/wsl-autostart.md` -- WSL2 auto-start at Windows login -- `docs/EXTENSIONS.md` -- administrator-controlled WebUI extension injection -- `docs/rfcs/README.md` -- RFC index for larger architecture and durability proposals +**Start here** +- [`docs/why-hermes.md`](docs/why-hermes.md) — why Hermes, the mental model, and a detailed comparison to Claude Code / Codex / OpenCode / Cursor +- [`docs/onboarding.md`](docs/onboarding.md) — first-run wizard, provider setup, local model server Base URLs, and safe re-runs +- [`docs/troubleshooting.md`](docs/troubleshooting.md) — diagnostic flows for common failures (e.g. "AIAgent not available") + +**Using & customizing** +- [`THEMES.md`](THEMES.md) — theme + skin system, custom theme guide +- [`docs/workspace-git.md`](docs/workspace-git.md) — the workspace Git controls +- [`docs/EXTENSIONS.md`](docs/EXTENSIONS.md) — administrator-controlled WebUI extension injection + +**Deploying & operating** +- [`docs/docker.md`](docs/docker.md) — Docker compose setup, common failures, and bind-mount migration +- [`docs/supervisor.md`](docs/supervisor.md) — launchd, systemd, supervisord, runit, and s6 process-supervisor setup +- [`docs/wsl-autostart.md`](docs/wsl-autostart.md) — WSL2 auto-start at Windows login +- [`docs/onboarding-agent-checklist.md`](docs/onboarding-agent-checklist.md) — safety rules and pass/fail checks for assistant-led install/reinstall support + +**Contributing & design** +- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contribution style, PR expectations, and local verification +- [`ARCHITECTURE.md`](ARCHITECTURE.md) — system design, all API endpoints, implementation notes +- [`TESTING.md`](TESTING.md) — manual browser test plan and automated coverage reference +- [`DESIGN.md`](DESIGN.md) — design tokens and the calm-console direction +- [`docs/UIUX-GUIDE.md`](docs/UIUX-GUIDE.md) — UI/UX principles sourced from the design docs and visual inventories +- [`docs/CONTRACTS.md`](docs/CONTRACTS.md) — project contract/RFC/design index for contributors and agents +- [`docs/rfcs/README.md`](docs/rfcs/README.md) — RFC index for larger architecture and durability proposals + +**Release history & plan** +- [`CHANGELOG.md`](CHANGELOG.md) — release notes per version +- [`ROADMAP.md`](ROADMAP.md) — feature roadmap and sprint history +- [`SPRINTS.md`](SPRINTS.md) — forward sprint plan with CLI + Claude parity targets +- [`CONTRIBUTORS.md`](CONTRIBUTORS.md) — the full community credit roll ## Contributors Hermes WebUI is built with help from the open-source community. Every PR — whether merged directly, absorbed into a batch release, or salvaged from a larger proposal — shapes the project, and we're grateful to everyone who has taken the time to contribute. -**137 contributors have shipped code that landed in a release tag** as of v0.51.58. The full credit roll lives in [`CONTRIBUTORS.md`](CONTRIBUTORS.md). The highlights: +Over **137 contributors** have shipped code that landed in a release tag. The full, +continuously-updated credit roll — including everyone with one or two PRs and the +special-thanks roll for design and architectural work — lives in +[`CONTRIBUTORS.md`](CONTRIBUTORS.md). A snapshot of the most prolific contributors: ### Top contributors (by PR count, including absorbed/batch-released work) diff --git a/ROADMAP.md b/ROADMAP.md index 2f07e779..4aceb531 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -2,7 +2,7 @@ > Web companion to the Hermes Agent CLI. Same workflows, browser-native. > -> Last updated: v0.51.31 (May 9, 2026) — 5028 tests collected — Release H 12-PR contributor batch (image-mode fix + race fixes + composer drafts + locale parity + custom-provider dedup + TTL config + heartbeat polish) +> Last updated: v0.51.192 (May 31, 2026) — ~7,150 tests collected. Recent themes: forward-looking ruff lint gate (#3273), Windows upgrade state-stranding hotfix (#2905), per-model context_length default-only guard (#3256), gateway-configured banner + tooltip i18n, and an ongoing concentric PR-triage cadence. > Test source: `pytest tests/ --collect-only -q` > Per-version detail: see [CHANGELOG.md](./CHANGELOG.md) diff --git a/TESTING.md b/TESTING.md index ead58268..6f5fb59b 100644 --- a/TESTING.md +++ b/TESTING.md @@ -1,14 +1,14 @@ # Hermes Web UI: Browser Testing Plan > This document is for manual browser testing by you or by a Claude browser agent. -> It covers user-facing features of the UI through v0.50.21 and later releases. +> It covers user-facing features of the UI across current releases. > Each section is written as a step-by-step test procedure with expected outcomes. > A browser agent (e.g. Claude with Chrome access) can execute this plan directly. > > Prerequisites: SSH tunnel is active on port 8787. Open http://localhost:8787 in browser. > Server health check: curl http://127.0.0.1:8787/health should return {"status":"ok"}. > -> Automated coverage: 5303 tests collected via `pytest tests/ --collect-only -q`. Tests run on every PR via GitHub Actions on Python 3.11, 3.12, and 3.13. The suite covers the bootstrap/static wizard, real provider config persistence (`config.yaml` + `.env`), the `/api/onboarding/*` backend, the onboarding skip/existing-config guard, CSS regression coverage for thinking/tool card animation, streaming session persistence, mobile layout breakpoints, locale parity across 11 languages, and hundreds of issue/PR-pinned regression tests. +> Automated coverage: ~7,150 tests collected via `pytest tests/ --collect-only -q`. Tests run on every PR via GitHub Actions on Python 3.11, 3.12, and 3.13 (3 parallel shards each), alongside a ruff lint gate, a headless browser smoke test, and a Docker smoke test. The suite covers the bootstrap/static wizard, real provider config persistence (`config.yaml` + `.env`), the `/api/onboarding/*` backend, the onboarding skip/existing-config guard, CSS regression coverage for thinking/tool card animation, streaming session persistence, mobile layout breakpoints, locale parity across 11 languages, and hundreds of issue/PR-pinned regression tests. > Run: `pytest tests/ -v --timeout=60` > > Local regression focus: verify that a previously closed workspace panel stays visually closed from first paint through boot completion on desktop refresh; there should be no brief open-then-close flash. @@ -1925,8 +1925,8 @@ Bridged CLI sessions: --- -*Last updated: v0.51.54, May 13, 2026* -*Total automated tests collected: 5303* +*Last updated: v0.51.192, May 31, 2026* +*Total automated tests collected: ~7,150 (run `pytest tests/ --collect-only -q` for the exact current count)* *Regression gate: tests/test_regressions.py* *Run: pytest tests/ -v --timeout=60* *Source: /*