Alex Dunmow 1aa4c42d58 docs: reword core-boundary note to keep the block/core grep gate clean

The README/AGENTS prose mentioned the literal `block/core` token when stating
that plugins must not import it. Reword to "the first-party core module" so
`grep -rn block/core` over the repo returns zero hits — P2 can use that grep as
a hard verification that no code (or doc) reintroduces a core dependency.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-07 10:54:20 +08:00

2.4 KiB

Raw Blame History

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/ (registry + templates/pongo), templates/bn/ (the templ chrome — see sync rule below), 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.

`templates/bn` synced-copy rule

templates/bn/* is authored in the cms repo (cms/backend/templates/bn) and synced into here via cms make sync-templates. Do not hand-edit the copy in this repo — edit it in cms and re-sync. Drift is enforced by check-safety check 31 (check-safety/check_templatesync.go), which compares this repo's templates/bn against the cms authoritative copy. (This chrome is transitional: it is deleted from the SDK once host-side head/body injection lands — Phase 3.)

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.

2.4 KiB Raw Blame History