block/core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
core/AGENTS.md
Alex Dunmow accb305fa3 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>
2026-07-07 09:42:00 +08:00

2.1 KiB
Raw Permalink Blame History

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.