jabber.developer2
22977846a3
Replace the single file-structure.md with a stratified layout designed
for AI/agent skill consumption: tables and concrete identifiers over
prose, files loaded on demand, content separated by churn rate.
Layers:
- architecture/ stable structural reference (overview, source-map,
test-map, data-flow)
- patterns/ memory, commands, autocomplete, events, xmpp,
encryption, ui, plugins
- testing/ unit-tests, stubs, functional-tests, bench
- build/ local, docker, ci
- playbooks/ add-command, add-test, add-autocomplete,
add-event-handler, add-encryption
- gotchas.md append-only dated entries (seven seed entries)
- wip/ branch-specific notes; deleted on merge to master
Stable layers describe cproof on master only. In-flight feature
branches (currently feat/ai) get a single file under wip/.
INDEX.md is the entry map with churn labels; SKILL.md is the
always-loaded skill hint pointing to it.
68 lines
2.4 KiB
Markdown
68 lines
2.4 KiB
Markdown
# Plugins
|
|
|
|
`src/plugins/` exposes both a C plugin ABI and a Python plugin runtime. Both
|
|
funnel through a shared core that fires callbacks on cproof events.
|
|
|
|
## Files
|
|
|
|
| File | Role |
|
|
|---|---|
|
|
| `plugins.c/h` | Public surface: load/unload, list, dispatch hooks. |
|
|
| `c_plugins.c/h` | C plugin loader (dlopen). |
|
|
| `python_plugins.c/h` | Python plugin loader (embedded interpreter). |
|
|
| `c_api.c/h` | C-side API exposed **to** plugins. |
|
|
| `python_api.c/h` | Python-side API exposed **to** plugins. |
|
|
| `api.c/h` | Shared API helpers. |
|
|
| `profapi.c/h` | The `prof` Python module surface. |
|
|
| `callbacks.c/h` | Hooks: pre/post message, pre/post presence, etc. |
|
|
| `autocompleters.c/h` | Plugin-registered autocompleters. |
|
|
| `disco.c/h` | Service-discovery feature contributions from plugins. |
|
|
| `settings.c/h` | Per-plugin settings storage. |
|
|
| `themes.c/h` | Plugin-supplied themes. |
|
|
|
|
## Hook points
|
|
|
|
Plugins fire on events around (cf. `src/plugins/callbacks.c`):
|
|
- Pre/post message send, pre/post message receive.
|
|
- Pre/post chat-message-display.
|
|
- Pre/post connect, disconnect.
|
|
- Pre/post quit.
|
|
- Window-switch, room-join, room-leave.
|
|
|
|
The callback names follow `prof_pre_*` / `prof_post_*` in the plugin API
|
|
surface; in cproof internals they are dispatched via
|
|
`plugins_pre_chat_message_send()` and similar.
|
|
|
|
## API surface for plugins
|
|
|
|
C API (`c_api.h`) and Python API (`python_api.h`) are kept in sync — any
|
|
new function in one should land in the other unless explicitly C-only or
|
|
Python-only.
|
|
|
|
The Python wrapper is in `profapi.c/h` and is exposed as the `prof` module
|
|
inside plugins.
|
|
|
|
## Adding a plugin hook point
|
|
|
|
1. Define dispatcher in `plugins.c/h`:
|
|
`void plugins_<verb>_<event>(<args>);`
|
|
2. Wire callback storage in `callbacks.c/h`.
|
|
3. Expose to plugins via `c_api.c/h` and `python_api.c/h` (matching names).
|
|
4. Call the dispatcher at the appropriate site (usually in `src/event/` or
|
|
`src/xmpp/`).
|
|
5. Document the hook in cproof's plugin docs (out of scope for this repo).
|
|
|
|
## Testing
|
|
|
|
`tests/unittests/test_plugins_disco.{c,h}` covers plugin-disco feature
|
|
contribution; broader plugin-system testing is light. Stubs:
|
|
`tests/unittests/plugins/stub_*.c`.
|
|
|
|
## Pitfalls
|
|
|
|
- Plugin callbacks may re-enter cproof via the C/Python API. Ensure state is
|
|
consistent **before** firing a callback — see `patterns/events.md`.
|
|
- The Python interpreter is global; plugins share state. Don't assume
|
|
isolation.
|
|
- Plugin loading is not sandboxed; treat plugins as trusted code.
|