docs: core is only for code shared between first-party entities
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>
This commit is contained in:
Alex Dunmow
parent
20c67b80ee
commit
accb305fa3
43
AGENTS.md
43
AGENTS.md
@ -1,9 +1,44 @@
|
||||
# Core SDK
|
||||
|
||||
Go module `git.dev.alexdunmow.com/block/core`. Shared Go code between the **CMS and the orchestrator** — template engine, block registry, shared types, proto definitions.
|
||||
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.** Its only consumers are the CMS and the orchestrator; it exists purely to share code between those two. Plugins must not import `block/core` — in the wasm-plugin era they are standalone artifacts built against the wasm ABI, not this module. (Core was previously the plugin SDK; that role is gone.)
|
||||
- **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.
|
||||
- **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`.
|
||||
|
||||
33
README.md
33
README.md
@ -1,8 +1,19 @@
|
||||
# BlockNinja Core
|
||||
|
||||
Shared Go code between the BlockNinja CMS and the orchestrator: types, interfaces, and utilities both need.
|
||||
Go code 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.
|
||||
|
||||
> **Not a plugin SDK.** Core is purely for sharing code between the CMS and the orchestrator. Plugins must **not** import `block/core` — in the wasm-plugin era they are standalone artifacts built against the wasm ABI. (Core previously served as the plugin SDK; that role is gone.)
|
||||
> **Scope rule:** core is ONLY for code needed by **two or more** of those
|
||||
> entities. Code with a single consumer belongs in that consumer's repo. The
|
||||
> standing direction is to shrink core — when a package's consumer count drops
|
||||
> to one, it gets migrated out.
|
||||
|
||||
> **Not a plugin SDK.** Plugins must **not** treat `block/core` as their SDK —
|
||||
> in the wasm-plugin era they are standalone artifacts built against the wasm
|
||||
> ABI (owned by the CMS: `cms/backend/abi/`, `cms/docs/abi/`). Core previously
|
||||
> served as the plugin SDK; that role is gone, and remaining plugin-era
|
||||
> surface here is legacy to be worked off, not a precedent.
|
||||
|
||||
## Package Structure
|
||||
|
||||
@ -12,7 +23,7 @@ Shared Go code between the BlockNinja CMS and the orchestrator: types, interface
|
||||
| `blocks/` | BlockMeta, BlockFunc, BlockRegistry interface, BlockContext |
|
||||
| `blocks/builtin/` | Reusable block implementations (HTMLBlock) |
|
||||
| `templates/` | TemplateRegistry interface |
|
||||
| `templates/bn/` | Shared templ components (head, engagement, toolbar) |
|
||||
| `templates/bn/` | Synced copy of the cms-authored bn chrome (see below) |
|
||||
| `auth/` | Claims types, context extractors |
|
||||
| `content/` | Content access interface |
|
||||
| `settings/` | Settings access interface |
|
||||
@ -23,10 +34,20 @@ Shared Go code between the BlockNinja CMS and the orchestrator: types, interface
|
||||
| `ai/` | AI tool registry interface and types |
|
||||
| `rbac/` | Role type definition |
|
||||
|
||||
### `templates/bn/` is a synced copy — do not edit here
|
||||
|
||||
The bn page chrome (head / toolbar / engagement / asset_hooks) is authored in
|
||||
`cms/backend/templates/bn` and copied here via the cms `make sync-templates`
|
||||
target, solely so guest-side plugin templates can compile it into their wasm.
|
||||
check-safety (check 31) fails cms commits while the copies drift. Change the
|
||||
chrome in cms, sync, then commit + tag + push here.
|
||||
|
||||
## Usage
|
||||
|
||||
Consumers are the CMS and the orchestrator only.
|
||||
|
||||
```go
|
||||
import "git.dev.alexdunmow.com/block/core/plugin"
|
||||
import "git.dev.alexdunmow.com/block/core/blocks"
|
||||
```
|
||||
|
||||
Versioned via git tags through the Gitea module proxy — never `replace`
|
||||
directives. All consumers are in-house; no backwards-compatibility shims —
|
||||
change the API and update the consumers.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user