From accb305fa38524203f9a15cf02734134f07ec3d7 Mon Sep 17 00:00:00 2001 From: Alex Dunmow Date: Tue, 7 Jul 2026 09:42:00 +0800 Subject: [PATCH] docs: core is only for code shared between first-party entities MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- AGENTS.md | 43 +++++++++++++++++++++++++++++++++++++++---- README.md | 33 +++++++++++++++++++++++++++------ 2 files changed, 66 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 762b254..d00c4ed 100644 --- a/AGENTS.md +++ b/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`. diff --git a/README.md b/README.md index 6890241..325b153 100644 --- a/README.md +++ b/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.