core/docs/codeless-bnp.md

Codeless .bnp — Declarative Plugins (WO-WZ-020)

A codeless .bnp is a plugin artifact with no plugin.wasm: pure declaration the host runs. No wazero compile, no instance pool, no capability binding — zero guest code ever executes. This is the end-state of "injection, not reliance" for themes, content sites, and template-only block packs: the plugin is data the host runs, not a program that links a library. No Go, no block/core dependency, no toolchain beyond the ninja CLI.

The classifier — exactly one rule

ninja plugin build classifies by repo shape:

• No Go source at the repo root → codeless. The manifest is synthesized from plugin.mod + the declarative files below; the artifact packs without a wasm. --codeless asserts this and fails if Go is present.
• Go source → wasm, exactly as before. A converted repo DELETES its Go — partial conversions keep a smaller wasm and still ship blocks/ + seed/ alongside it (both artifact kinds carry the declarative dirs).

The declarative / logic split

Codeless-expressible (declaration or host-rendered template):

• Blocks: a .ninjatpl template + declared data providers (the CMS's own provider set — posts, site, menus, authors, … ADR 0018). The host fetches, the engine renders. Defined in blocks/blocks.yaml — the SAME manifest-FS layout core builtin block definitions use.
• Master pages, theme presets, fonts, CSS manifest, icon packs, settings schema (manifest.yaml), assets (host-served), migrations (host-run Goose), seed data (seed/seed.json, applied via the WO-WZ-019 provisioner).
• Template overrides (WO-WZ-021): theme-scoped re-renders of builtin blocks. Declared in manifest.yaml as template_overrides: [{template: <system-key>, block: <block-key>}]; the source lives at templates/overrides/<template>/<block>.ninjatpl and is rendered host-side with the block's content map as the template context.
• Email wrappers (WO-WZ-021): email_wrappers: [<system-key>, …] in manifest.yaml, source at templates/email/<system>.ninjatpl. The context carries body (pre-rendered HTML — emit it with {{ body|safe }}), colors.* (snake_case hex tokens: primary, primary_foreground, secondary, secondary_foreground, background, foreground, muted, muted_foreground, border, card, card_foreground), site.* (name, logo_url, url, support_email), unsubscribe_url, preview_text. Render failure falls back to the unwrapped body.

Requires code (a wasm plugin):

• A block whose data no declared provider can produce; a computing tag or filter; HTTP handlers; background jobs; Load/Unload logic; RAG fetchers; media hooks; bridge services; AI tools; data_dir. A codeless manifest declaring any of these is rejected at build (ninja plugin verify / CodelessHookViolation) AND at load (cms reader codelessHookViolation).

Repo layout

my-theme/
  plugin.mod            # name/version/kind (data_dir forbidden)
  manifest.yaml         # optional: theme_presets/bundled_fonts/settings_schema
                        #   (JSON file refs), master_pages (JSON file),
                        #   required_icon_packs, css {...}, dependencies [...],
                        #   system_templates/page_templates,
                        #   template_overrides [{template, block}],
                        #   email_wrappers [system keys]
  blocks/
    blocks.yaml         # key/title/category/schema/template/providers per block
    hero.schema.json
    hero.ninjatpl
  templates/            # <system>/<key>.ninjatpl layout sources for the
                        #   system/page templates declared in manifest.yaml,
                        #   rendered host-side (blog/system/normal page layouts)
    overrides/<system>/<block>.ninjatpl   # template_overrides sources
    email/<system>.ninjatpl               # email_wrappers sources
  seed/
    seed.json           # settings {merge/override/ensure}, media, pages, menu_items
    hero.jpg            # media bytes referenced by seed.json entries
  assets/               # host-served statics
  migrations/           # Goose SQL, host-run under the plugin schema

ninja plugin build → <name>-<version>.bnp (tar.zst, no plugin.wasm, manifest.pb with codeless: true). ninja plugin verify re-runs the loader's checks standalone.

How the host runs it (cms plugin/codeless_loader.go)

• The .bnp reader accepts a missing plugin.wasm iff manifest.codeless, and rejects codeless manifests with computing-hook declarations.
• Load: blocks/ → blocks.LoadManifest → Registry.RegisterDefinition — rendering flows through the existing definition engine (providers + ninjatpl + layer fallback, WO-089..096). seed/seed.json → provisioner (EnsureMedia/MergeSiteSettings/EnsureSetting/EnsurePage/ EnsureMenuItem), idempotent by construction. Presets/fonts/CSS/master pages/settings schema come from the manifest exactly as for wasm plugins.
• Unload/disable: definitions unregister; seeded content stays (it is site data, not runtime state). Uninstall: normal teardown (schema/role drop, artifact removal).
• Hot-swap: codeless→codeless swaps run migrations first, then re-register definitions and re-apply seed. Wasm↔codeless transitions require uninstall + reinstall.

Mixed-form artifacts (WO-WZ-021)

A mixed .bnp keeps a plugin.wasm (it is NOT codeless) for genuine logic — a contact route, a Stripe handler, a background job — while everything the codeless surface can express stays declarative and host-rendered. This is how the B2 site conversions (coterieos / coteriehealth / bcms-public / judgefest) keep a minimal guest yet ship their page templates, overrides, email wrappers, master pages, presets, fonts, and CSS as data the host runs.

The classifier is unchanged: a repo with Go source at the root builds wasm. What changed is that a wasm build now folds an optional root manifest.yaml into the DESCRIBE-derived manifest.pb, exactly as BuildCodeless does — the SAME declarative key set: theme_presets / bundled_fonts / settings_schema (JSON-file refs, embedded into manifest.pb), master_pages (JSON file), system_templates / page_templates, template_overrides, email_wrappers, css, required_icon_packs, dependencies. The .ninjatpl sources ride the already-packed templates/ dir; blocks/ + seed/ ride along as before.

• Supplement / override, never wipe. A declarative key supplements the guest's DESCRIBE output (slice keys append; scalar/bytes keys overwrite) — but a key the manifest.yaml does NOT declare leaves the guest's value untouched. A repo with no manifest.yaml builds byte-for-byte as before.
• Host-render precedence at load (cms plugin/wasm_loader.go, registerWasmStatics). A page template / block override / email wrapper is host-rendered through the cms pongoengine (with the full synthesized page context — head_html / body_end_html / admin_banner_html) iff the artifact ships its convention-path source (templates/<system>/<key>.ninjatpl, templates/overrides/<template>/<block>.ninjatpl, templates/email/<system>.ninjatpl). Otherwise the guest forwarder stands. A reduced plugin's DESCRIBE may still list a template it no longer renders in-guest; the declarative source wins. Master pages / presets / fonts / CSS / icon packs flow from manifest.pb through the existing wasm registration path unchanged.
• Lifecycle rides the standard source-scoped Register / UnregisterBySource pipeline, so install / disable / uninstall / hot-swap / cross-form swap tear the declarative surfaces down with no extra wiring — identical to codeless.

Seed schema (seed/seed.json)

{
  "settings": {"merge": {"k": "v"}, "override": {"k": "v"}, "ensure": {"k": "v"}},
  "media":    [{"id": "<uuid>", "file": "hero.jpg", "alt": "", "folder": ""}],
  "pages":    [{"slug": "/", "title": "Home", "template_key": "landing",
                "parent_slug": "", "reconcile_blocks": false,
                "blocks": [{"block_key": "hero", "title": "Hero",
                            "content": {}, "slot": "main", "sort_order": 1}]}],
  "menu_items": [{"menu": "main", "label": "Home", "page_slug": "/", "sort_order": 1}]
}

Media id is the deterministic, template-referable key (media:<uuid>, {% img %}); bytes live in seed/ next to the JSON. Apply order: media → settings → pages → menu items.