pluginsdk/README.md

block/pluginsdk

The plugin-facing SDK for BlockNinja CMS plugins. Plugins import THIS module, never the first-party core module.

What lives here

• abi/proto/v1/ — THE single source-of-truth ABI proto tree for the wasm plugin contract. The wire between host and guest is proto-only; any language can generate its own bindings from these .proto files. (This tree used to be duplicated by hand in cms/backend/abi and core/abi; it now lives here once.)
• abi/v1/ — the generated Go bindings (abiv1). Regenerate with make proto.
• plugin/ — the Go registration + DI surface (PluginRegistration, CoreServices/ServiceDeps, block/template registries) and the minimal Go wasm transport shim under plugin/wasmguest/ (exports, dispatch, hostcalls, context rehydration), its capability stubs (plugin/wasmguest/caps/), and the database/sql driver over the host DB (plugin/wasmguest/bnwasm/).
• Guest-facing type packages plugins consume: blocks/ (incl. blocks/builtin, blocks/shared, blocks/tags), templates/ (the template registry + types, including PageDocument — the body-plus-envelope contribution a full-page template makes; the host owns the chrome), auth/, settings/, content/, gating/, crypto/, rbac/, video/, ai/, subscriptions/, menus/, datasources/.

The Go surface here is one language binding. The proto tree is the contract: a non-Go plugin implements the ABI hooks directly and never sees the Go structs.

Rules

• NEVER use replace directives in go.mod. Module resolution goes through the Gitea module proxy — to test local changes, tag and push a version.
• All consumers are in-house — no backwards-compatibility shims.
• Plugins import block/pluginsdk/..., never the first-party core module.

Design

Program spec (in the cms repo): docs/superpowers/specs/2026-07-07-proto-first-plugin-sdk-design.md.