bd73a2df24
All checks were successful
plugin-tests / test (push) Successful in 6s
CONTRIBUTING.md closes the "how do I add anything" gap: the protocol PRD defines the CONTRACT (what's allowed, what's verified), but until now recipes were implicit — readers had to reverse-engineer patterns from existing routes/vault_status.py + static/app.js + the STT migration. Five recipes, one decision flowchart: A Add a new /api/* endpoint B Add a new UI element (CSS/JS/asset) C Extend the loader API (add an 8th method) — STT migration is the example D Add a config value E Forced-internal escape hatch (use sparingly, discipline at 5 rows) Each recipe: numbered steps, file paths, commit message template, test requirement. Plus a PR checklist + quick-reference index. README.md gets a top-of-page pointer so a new contributor lands on the recipes within one click. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
67 lines
2.7 KiB
Markdown
67 lines
2.7 KiB
Markdown
# 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.
|
|
|
|
**Adding features?** Read [`CONTRIBUTING.md`](CONTRIBUTING.md) for the 5 recipes + decision flowchart.
|
|
|
|
## 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) |
|