accb305fa3
Purpose sharpened per Captain's direction: core exists solely for code shared between two or more first-party entities — cms, orchestrator, the ninja CLI, or future entities. Adds the admission test (single consumer → that repo, plugin-needed → wasm ABI), the shrink-core direction, and the templates/bn synced-copy rule (authored in cms, make sync-templates, check-safety 31, validation.go intentionally divergent). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
45 lines
2.1 KiB
Markdown
45 lines
2.1 KiB
Markdown
# Core SDK
|
|
|
|
Go module `git.dev.alexdunmow.com/block/core`.
|
|
|
|
**Purpose: core exists ONLY for code that must be shared between first-party
|
|
BlockNinja entities** — the **CMS**, the **orchestrator**, the **ninja CLI**,
|
|
and any future entity that genuinely needs to share code with the others.
|
|
|
|
## Admission test
|
|
|
|
Before adding anything here, ask: **do two or more first-party entities need
|
|
this code?**
|
|
|
|
- Needed by only one entity → it belongs in that entity's repo, not core.
|
|
- Needed by plugins → it does NOT belong here (see below); plugins build
|
|
against the wasm ABI, whose contract the CMS owns (`cms/backend/abi/`,
|
|
`cms/docs/abi/`).
|
|
|
|
The standing direction (Captain, 2026-07-07) is to **shrink core**: prefer
|
|
moving code out to its single consumer over adding more in. When a package's
|
|
consumer count drops to one, migrate it out.
|
|
|
|
## Critical Rules
|
|
|
|
- **Core is NOT for plugins.** Plugins are standalone wasm artifacts built
|
|
against the wasm ABI, not this module. (Core was previously the plugin SDK;
|
|
that role is gone, and remaining plugin-era surface is legacy to be worked
|
|
off, not a precedent.)
|
|
- **NEVER use `replace` directives in go.mod** — not in this repo, not in any
|
|
consumer. All module resolution goes through the Gitea module proxy. If you
|
|
need to test local changes, tag and push a version.
|
|
- All consumers are in-house — no backwards compatibility shims needed. Just
|
|
change the API and update consumers.
|
|
|
|
## Special case: `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 (`make
|
|
sync-templates` in cms) 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.
|
|
`templates/bn/validation.go` is intentionally divergent (cms's version bridges
|
|
the SDK ValidationTracker under both context keys) and is NOT part of the sync
|
|
set. Spec: cms `docs/superpowers/specs/2026-07-07-bn-chrome-single-source-design.md`.
|