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

1.8 KiB

Raw Blame History

Plugin SDK

Go module git.dev.alexdunmow.com/block/pluginsdk.

Purpose: this is the ONE plugin-facing artifact. BlockNinja CMS plugins import this module and nothing else from the internal Go tree. Plugins must NOT import the first-party core module — core exists only for code shared between first-party entities (cms, orchestrator, ninja CLI).

The contract is proto, not Go

abi/proto/v1/*.proto is the contract. The host↔guest wire is proto-only; a plugin in ANY language generates its own bindings from these files.
abi/v1/ is the Go binding of that contract (abiv1). The rest of the Go surface here — plugin/, plugin/wasmguest/**, and the guest-facing type packages — is one language binding of the SDK. A non-Go plugin implements the ABI hooks directly and never sees these Go structs.

Critical Rules

NEVER use replace directives in go.mod — not here, not in any consumer. All 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. Change the API and update consumers.
Regenerate Go bindings after editing any .proto: make proto.

`templates/bn/` is a synced copy — do not author here

The bn page chrome (head / toolbar / engagement / asset_hooks) is authored in cms/backend/templates/bn and mechanically copied here via cms make sync-templates, solely so guest-side plugin templates can compile it into their wasm. check-safety check 31 fails cms commits while the copies drift. Never edit these files here directly — change them in cms and sync. (This chrome is transitional: it is deleted once host-side head/body injection lands — Phase 3.)

Design

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

1.8 KiB Raw Blame History