hermes/svrnty-hermes-webui-plugin
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(plugin): initial scaffold — plugin loader entry + AST + CI workflows (P1.B/C/D)

Browse Source 
THE single repo holding every Svrnty modification to nesquena/hermes-webui per
the SVRNTY-HERMES Plugin Protocol PRD (hermes/docs/SVRNTY-PLUGIN-PROTOCOL.md).
This scaffold is the empty vessel; Phase 2 migrates the existing fork
modifications (STT, vault status, brand skin) into it.

Contents:
  plugin.py                          register(api) entry; reads 6-method
                                     contract; wires static + routes
  svrnty_hermes_webui_plugin/        package wrapper for pip install
  manifest.yaml                      plugin name · version · upstream pin
  pyproject.toml                     pip-installable
  routes/__init__.py                 placeholder until Phase 2 migration
  static/                            placeholder for brand skin migration
  CONNECTION-MAP.md                  AST-generated; 4 public API calls, 0 forced
  scripts/ast-connection-map.py      AST walker; modes: regen · --check · --diff
  tests/{unit,integration,evals}/    skeleton for Phase 3 eval suite
  .github/workflows/
    plugin-tests.yml                 push: unit + integration + map check
    connection-map-check.yml         PR: regen + diff vs committed
    upstream-drift.yml               daily cron: detect new upstream tags +
                                     run matrix (activates when Gitea runner
                                     registered on Svrnty infra)

Karpathy 4 rules in CLAUDE.md; every subagent inherits them via the workspace
contract.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Svrnty
2026-05-23 09:59:45 -04:00
commit 4264c6cbe8
14 changed files with 706 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+64
View File
@@ -0,0 +1,64 @@
# svrnty-hermes-webui-plugin
THE single repo holding every Svrnty modification to `nesquena/hermes-webui`. Loaded at runtime via the plugin loader hook patched into the fork.
**Protocol contract:** [`hermes/docs/SVRNTY-PLUGIN-PROTOCOL.md`](../docs/SVRNTY-PLUGIN-PROTOCOL.md) — read this before contributing.
## Install
```bash
# 1. Install the plugin in the same venv as hermes-webui
pip install -e ~/workspaces/hermes/svrnty-hermes-webui-plugin
# 2. Tell hermes-webui to load it
export HERMES_WEBUI_PYTHON_PLUGIN=svrnty_hermes_webui_plugin
# or set in docker-compose.override.yml under environment:
# 3. Restart hermes-webui — endpoints under /api/* + assets under /plugins/svrnty/* land
```
Without `HERMES_WEBUI_PYTHON_PLUGIN`, hermes-webui runs vanilla (no Svrnty mods).
## What's in here
| Dir | What |
|---|---|
| `plugin.py` | Entry point — `register(api)` wires routes + static |
| `routes/` | One file per Svrnty `/api/*` endpoint (transcribe, vault_status, …) |
| `static/` | Brand skin: `app.js`, `app.css`, Montserrat fonts |
| `CONNECTION-MAP.md` | **AST-generated** map of every upstream symbol this plugin touches |
| `scripts/` | Tooling — AST walker, upstream sync, boot smoke |
| `tests/` | Unit · integration · evals (each upstream-sync runs evals) |
| `.github/workflows/` | Plugin-tests · connection-map-check · upstream-drift CI |
## Public extension API
The plugin loader (one fork commit in hermes-webui) exposes exactly 6 methods:
```python
api.register_route(path, method, handler) # add /api/<path>
api.register_static(prefix, directory) # serve files under /plugins/<prefix>/...
api.inject_script(url) # add <script> to index.html
api.inject_stylesheet(url) # add <link> to index.html
api.config_get(key, default) # safe upstream config read
api.logger(name) # namespaced logger
```
Touching anything else in hermes-webui = a Rule 2 violation per the protocol. Document the escape hatch in `CONNECTION-MAP.md` under "forced internal dependencies".
## Hygiene
- `make sync-upstream` — one-command rebase against latest upstream + report
- `python scripts/ast-connection-map.py` — regenerate the map
- `python scripts/boot-smoke.py` — start + curl every plugin endpoint
- `pytest tests/` — full suite (unit + integration + evals)
## Status
| Component | State |
|---|---|
| Loader hook in `hermes-webui` | TBD (Phase 1) |
| Plugin scaffold | Phase 1 in progress |
| Migrated features (transcribe, vault_status, brand skin) | TBD (Phase 2) |
| Automation (drift CI, sync command, eval suite) | TBD (Phase 3) |
| Upstream PR | TBD (Phase 4) |