feat(plugin-kit): let a hook handler reach its plugin's runtime

[jouwdan]

Part of MEI-115. This is a prerequisite discovered while designing the first-cohort webhooks plugin, so it lands before the plugins that need it.

The gap

A hook handler is called with the value and the hook's own context — nothing else. It has no data, no notify, no logger. So a plugin can filter a view or observe an event in memory, but it cannot record a row, queue a delivery, or raise a notification: it cannot react to the board durably at all.

That is not a corner case. It is the most obvious thing a plugin author expects to be able to do, and the evidence it bites is already in the tree — plugins/dues declares no hooks whatsoever and works entirely through routes, tasks and pages, and plugins/reference records hook calls into an in-memory array. The webhooks, RSS, analytics and calendar plugins on MEI-115's cohort list all need it.

The change

A third argument, a function that resolves this plugin's runtime context:

'post.created': async (post, context, runtime) => {
  const { data } = await runtime()
  await data.query('insert into plugin_example_outbox (post_id) values ($1)', [post.postId])
},

Why a function rather than the context itself. Hooks are the hot path — view.* filters run on every page and postbit.badges once per post — and a handler that never calls it costs nothing, so the pure view filters that dominate pay for none of it. It is also honest about failure: on a fixture-mode board there is no database and await runtime() rejects with a message saying so, rather than handing back something that pretends. Within a single handler call it resolves once and is reused.

The reach is the same one everything else gets, and no larger. data still refuses anything outside plugin_<key>_*, grants still refuses a group the operator has not opened, and a throw is still contained, counted, and subject to auto-disable.

Additive, so a minor and not a break. A two-argument handler still compiles and runs — verified: the only compile error across the whole tree was one call site in the example's test, not a single handler definition. Tests driving a handler directly pass unavailableHookRuntime(reason), whose every capability refuses with that reason.

Two structural fixes this required

Wiring the app's provider into the host exposed a real import cycle: plugin-host → the runtime builder → notifications → plugin-view → plugin-host. It surfaced as plugin-admin.test.ts failing to mock @meith/db.

• The runtime builder moves out of plugin-pages.ts into its own plugin-runtime.ts, so the host does not pull in the page-rendering graph.
• notifyFor defers its ./notifications import to the moment a plugin actually sends, which breaks the cycle and keeps the notification service off the hook path until used.

Validated

• pnpm verify fully green: 7948 tests, 452 files.
• 5 new host tests cover it: each plugin gets its own runtime, it is not built for a handler that does not ask, it is built once per call however often a handler asks, filters get it too, and a host built without a provider fails with a clear message and counts the failure like any other.
• plugins/reference — the ratchet — now exercises it on post.created.
• Documented in docs/customization/plugins.md; the scaffold templates regenerated from the updated example.

🤖 Generated with Claude Code

https://claude.ai/code/session_01G22SRRgkUV7doefmw9NMNf

---

Generated by Claude Code