SHA256

Files

docs: split context into layered, agent-oriented files

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.

2026-04-30 20:52:06 +03:00

2.4 KiB

Raw Permalink Blame History

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

Define dispatcher in plugins.c/h: void plugins_<verb>_<event>(<args>);
Wire callback storage in callbacks.c/h.
Expose to plugins via c_api.c/h and python_api.c/h (matching names).
Call the dispatcher at the appropriate site (usually in src/event/ or src/xmpp/).
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.

2.4 KiB Raw Permalink Blame History