33014fbea9
- CLAUDE.md: drop Karpathy block, list all 7 loader methods incl register_audio_attachment_processor - README: extend "Public extension API" to 7 methods Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
55 lines
3.0 KiB
Markdown
55 lines
3.0 KiB
Markdown
# svrnty-hermes-webui-plugin
|
|
|
|
**Classification:** Svrnty plugin for `nesquena/hermes-webui` (per `hermes/docs/SVRNTY-PLUGIN-PROTOCOL.md`)
|
|
*Inherits Karpathy 4 rules from `~/.claude/CLAUDE.md` — read them before coding.*
|
|
|
|
## What this is
|
|
|
|
THE single repo holding every Svrnty modification to hermes-webui: backend routes, brand skin (CSS/JS/fonts), assets, tests. Loaded at runtime via the plugin loader hook patched into the fork (ONE permanent fork commit).
|
|
|
|
**Replaces:**
|
|
- `hermes-ext/` (deprecated — brand skin migrating in)
|
|
- 4 prior fork commits in `hermes-webui/api/` (deprecated — migrated to `routes/`)
|
|
|
|
## Hard rules
|
|
|
|
- ONLY interact with hermes-webui via the public extension API: `api.register_route` · `api.register_static` · `api.inject_script` · `api.inject_stylesheet` · `api.config_get` · `api.logger` · `api.register_audio_attachment_processor`
|
|
- Any other upstream import → `CONNECTION-MAP.md` under **forced internal dependencies** with written justification + risk
|
|
- `CONNECTION-MAP.md` is **AST-generated**, never hand-edited
|
|
- Every PR regenerates `CONNECTION-MAP.md` (CI enforces)
|
|
- Secrets via credctl / env only — never in repo, never on argv, never in logs
|
|
- Plugin code = stateless wrappers; state lives in upstream (or in upstream-managed `state.db`)
|
|
|
|
## Structure
|
|
|
|
```
|
|
plugin.py # entry: register(api) wires everything
|
|
routes/<feature>.py # one file per /api/<feature> endpoint
|
|
static/{app.js,app.css,fonts/} # brand skin (subsumes hermes-ext)
|
|
CONNECTION-MAP.md # AST-generated dependency map (do NOT hand-edit)
|
|
manifest.yaml # plugin metadata + upstream version pin
|
|
pyproject.toml # pip-installable
|
|
scripts/
|
|
ast-connection-map.py # regenerates CONNECTION-MAP.md
|
|
upstream-sync.py # fetches upstream tags + runs CI matrix
|
|
boot-smoke.py # spin up + curl every plugin endpoint
|
|
tests/{unit,integration,evals}/
|
|
.github/workflows/
|
|
plugin-tests.yml # push: unit + integration
|
|
connection-map-check.yml # PR: regen + diff vs committed
|
|
upstream-drift.yml # daily cron: detect upstream tags + run matrix
|
|
```
|
|
|
|
## Sources
|
|
|
|
- Protocol PRD: `../docs/SVRNTY-PLUGIN-PROTOCOL.md` (the contract — 7 loader API methods, §10 validator assertions)
|
|
- Upstream fork: `../hermes-webui/` (holds ONLY the loader patch + pristine upstream)
|
|
- Deprecated: `../hermes-ext/` (migrating into `static/`)
|
|
|
|
## Gotchas
|
|
|
|
- Adding a route: drop file in `routes/`, register in `plugin.py` via `api.register_route`. Do NOT touch hermes-webui's `api/routes.py`
|
|
- After ANY structural change: `python3 scripts/ast-connection-map.py` then commit the regen. CI fails PR otherwise
|
|
- New loader API methods require: protocol PRD bump + `protocol-validate.sh` assertion + fork loader patch update
|
|
- Adding upstream imports: justify in `CONNECTION-MAP.md` BEFORE the import lands — the AST gen will flag it, but reviewer should see the rationale committed alongside
|