@biffo/cli 0.281.0 → 0.283.0

package/_skeletons/plugin-template/README.md

@@ -69,8 +69,42 @@ plugin deploying clean with empty tables and the symptom surfacing wherever
 those rows were read
 ([#709](https://github.com/keiranholloway/biffo-template/issues/709)).
 
-Baseline data goes in one of two places instead, and `seed_default_widget()` in
-`plugin.py` documents both at the call site:
+**Baseline data — the rows a feature needs before it works at all, not a
+single plugin's own config — has a declared mechanism now
+([#1554](https://github.com/keiranholloway/biffo-template/issues/1554)):**
+`biffo.plugin.json`'s `seed` block. This skeleton demonstrates it:
+
+```json
+"seed": {
+  "dir": "db/seed",
+  "baseline_tables": ["example_widgets"]
+}
+```
+
+`dir` names a directory of idempotent `.sql` files (`db/seed/000_default_widget.sql`
+here) — `biffo plugin install`/`upgrade` vendor them into the installing
+instance's `db/imports/_plugin-example-plugin/`, where that instance's
+existing "Apply DDL imports" deploy step (ADR-0005) applies them on every
+deploy. No token, no per-tenant API call, no new deploy machinery — it is the
+same mechanism `db/imports/<name>/` always was, just declared in the manifest
+instead of a step nobody was told to perform. `baseline_tables` names which of
+this manifest's own `tables` the seed populates; the instance's deploy then
+fails loudly, by table and by tenant, if one ends up empty
+(`biffo:plugin-baseline-check`) — instead of the feature silently rendering
+nothing, which is what actually happened and is the incident #1554 records.
+
+**The idempotency contract is not optional and is checksum-enforced.** Once a
+seed file has been applied anywhere, editing it makes the next deploy fail
+loudly (ADR-0005 §4) rather than silently re-applying or silently skipping. A
+later change to your baseline data ships as a new, additively-numbered file —
+see `db/seed/000_default_widget.sql`'s own header comment for the full
+contract and the `INSERT ... SELECT ... WHERE NOT EXISTS` shape every file
+here must follow.
+
+This is a second, complementary mechanism to the one below — not a
+replacement for it. `seed_default_widget()` in `plugin.py` still demonstrates
+**self-seeding at startup**, which is the right tool for a plugin's own
+runtime config rather than tenant-scoped table rows:
 
 - **If your plugin declares an `api_ingress` ASGI app** (ADR-0021), seed from
   that app's lifespan. The shared plugin host runs each mounted app's lifespan
@@ -82,8 +116,11 @@ Baseline data goes in one of two places instead, and `seed_default_widget()` in
   [#1000](https://github.com/keiranholloway/biffo-template/pull/1000), so treat
   this route as new and check your own.
 - **If it doesn't** — like `example_plugin`, which is event-only — there is no
-  startup to hang anything on. Put the rows in a SQL module in the instance's
-  `db/imports/<name>/`, applied by `biffo data apply` on every deploy.
+  startup to hang anything on. The `seed` manifest block above is its only
+  option, and is now the recommended default for baseline table rows even for
+  a plugin that does have an ASGI app: it reaches every tenant in one
+  statement, needs no running plugin process, and fails the deploy loudly
+  instead of only whenever a request happens to hit the lifespan hook.
 
 > Earlier revisions of this README pointed at an RBAC reference plugin at
 > `services/rbac/`. That plugin was removed by

package/_skeletons/plugin-template/biffo.plugin.json

@@ -83,6 +83,10 @@
     { "type": "nav-link", "label": "Example Plugin", "path": "/admin/example-plugin" },
     { "type": "page", "label": "Widgets", "path": "/admin/example-plugin/widgets" }
   ],
+  "seed": {
+    "dir": "db/seed",
+    "baseline_tables": ["example_widgets"]
+  },
   "dependencies": {
     "biffo-plugin-sdk": "^1.0"
   }

package/_skeletons/plugin-template/db/seed/000_default_widget.sql

@@ -0,0 +1,47 @@
+-- example-plugin's baseline-row seed (biffo-template#1554).
+--
+-- Declared by biffo.plugin.json's `seed` block (`dir: "db/seed"`,
+-- `baseline_tables: ["example_widgets"]`). `biffo plugin install`/`upgrade`
+-- vendor every *.sql file in this directory into the installing instance's
+-- `db/imports/_plugin-example-plugin/`, where that instance's existing
+-- "Apply DDL imports" deploy step (ADR-0005) applies it on every deploy —
+-- no token, no per-tenant API call, no new deploy machinery. See
+-- README.md's "Seeding" section and `plugin.py`'s `seed_default_widget()`
+-- docstring for the two-mechanism picture this is one half of.
+--
+-- IDEMPOTENCY CONTRACT (read before copying this into your own plugin):
+-- once applied, this file is checksum-tracked in ddl_import_history — an
+-- edit to it after that point makes the next deploy fail loudly rather than
+-- silently re-applying or silently skipping (ADR-0005 section 4). A later
+-- change to this plugin's baseline data must ship as a NEW, additively
+-- numbered file (001_..., 002_...), never as an edit to this one.
+--
+-- INSERT ... SELECT ... WHERE NOT EXISTS is the shape every seed file here
+-- must follow: it reads the known tenants from `users` (Core's own
+-- Alembic-managed table — see plugin_baseline_check.py's module docstring
+-- for why that, not a generic `tenants` table, is what "known tenant" means
+-- in this template) and inserts exactly one starter widget per tenant that
+-- doesn't already have one, so re-running this file on every deploy is
+-- always a no-op once each tenant has its row. Mirrors the shape (same
+-- name, same description, same idempotent "insert if missing by name" logic)
+-- of `seed_default_widget()` in `plugin.py` — that one seeds lazily, over
+-- the API, from one plugin process's own ASGI lifespan; this one seeds every
+-- known tenant in a single statement, from the instance's own deploy step.
+-- Both are legitimate; which one to use for YOUR plugin is exactly the
+-- question BiffoPluginBase's class docstring answers.
+INSERT INTO example_widgets (id, tenant_id, name, description, is_active, created_at, updated_at)
+SELECT
+  gen_random_uuid()::text,
+  known_tenant.tenant_id,
+  'starter-widget',
+  'Created by this plugin''s baseline seed. Safe to delete.',
+  true,
+  now(),
+  now()
+FROM (SELECT DISTINCT tenant_id FROM users) AS known_tenant
+WHERE NOT EXISTS (
+  SELECT 1
+  FROM example_widgets existing
+  WHERE existing.tenant_id = known_tenant.tenant_id
+    AND existing.name = 'starter-widget'
+);

package/_skeletons/plugin-template/registry-schema.json

@@ -284,6 +284,25 @@
       },
       "description": "Portal UI elements the plugin adds."
     },
+    "seed": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["dir"],
+      "properties": {
+        "dir": {
+          "type": "string",
+          "pattern": "^[\\w][\\w./-]*$",
+          "description": "Plugin-relative directory of baseline-seed .sql files (ADR-0005 DDL import). `biffo plugin install`/`upgrade` vendor every *.sql file directly under this directory (non-recursive) into the instance's db/imports/_plugin-<name>/, where the instance's existing deploy step applies it idempotently on every deploy via ddl_import_history checksum tracking. IDEMPOTENCY CONTRACT: files here must be safe to re-run — an INSERT ... SELECT ... WHERE NOT EXISTS pattern against a stable natural key, never a bare INSERT. They are checksum-locked once applied: editing an already-shipped file makes the next deploy fail loudly (ADR-0005 section 4) rather than silently re-applying or silently skipping. Ship a new, additively-numbered file for a later change instead of editing one already released."
+        },
+        "baseline_tables": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": [],
+          "description": "Names of this manifest's own `tables` that the seed DDL in `dir` guarantees are populated for every known tenant. Checked post-deploy (the `biffo:plugin-baseline-check` Lambda event, run from the deploy workflow after DDL imports are applied) — a table listed here with no rows for a tenant this deployment already knows about is a loud, specific deploy failure instead of a silently-empty feature (biffo-template#1554)."
+        }
+      },
+      "description": "Declares this plugin's tenant-scoped baseline-row seed. Optional — a plugin with no baseline data omits this key entirely, and nothing is vendored or checked for it."
+    },
     "tools": {
       "type": "array",
       "items": {

package/_skeletons/plugin-template/src/example_plugin/plugin.py

@@ -64,6 +64,18 @@ class ExamplePlugin(BiffoPluginBase):
     async def seed_default_widget(self) -> None:
         """Create this plugin's baseline row, idempotently.
 
+        **This is the ASGI-lifespan self-seeding path — for tenant-scoped
+        BASELINE TABLE rows (what a fresh install needs before the feature
+        works at all), prefer the declared `seed` manifest block instead
+        (biffo-template#1554): see `biffo.plugin.json`'s `seed` key and
+        `db/seed/000_default_widget.sql`, which seeds this same table for
+        every known tenant in one statement via the instance's existing
+        DDL-import deploy step, with no running plugin process and no
+        per-tenant request needed to trigger it.** This method stays as the
+        worked example of the *other* legitimate path — a plugin's own
+        runtime config, or anything that genuinely needs to run as this
+        plugin's own code rather than as SQL.
+
         Nothing in this skeleton calls this — deliberately. **Where you call
         it from depends on what kind of plugin you are building**, and
         neither answer is `on_install()`:
@@ -88,10 +100,9 @@ class ExamplePlugin(BiffoPluginBase):
           idempotent until #1000. Verify your seed; do not assume it.
 
         - **An event-only plugin like this one** declares no `api_ingress`,
-          so it has no startup at all. Its baseline rows belong in a SQL
-          module in the *instance's* `db/imports/<name>/`, applied by
-          `biffo data apply` on every deploy — the mechanism the first-party
-          plugins use.
+          so it has no startup at all. Its baseline rows belong in the `seed`
+          manifest block described above — the mechanism the first-party
+          plugins use, now declared rather than a hand-run script.
 
         Idempotency: generic CRUD (issue #19) has no upsert — every POST
         creates a new row — so this lists existing widgets first and only

package/_skeletons/registry/registry-schema.json

@@ -284,6 +284,25 @@
       },
       "description": "Portal UI elements the plugin adds."
     },
+    "seed": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["dir"],
+      "properties": {
+        "dir": {
+          "type": "string",
+          "pattern": "^[\\w][\\w./-]*$",
+          "description": "Plugin-relative directory of baseline-seed .sql files (ADR-0005 DDL import). `biffo plugin install`/`upgrade` vendor every *.sql file directly under this directory (non-recursive) into the instance's db/imports/_plugin-<name>/, where the instance's existing deploy step applies it idempotently on every deploy via ddl_import_history checksum tracking. IDEMPOTENCY CONTRACT: files here must be safe to re-run — an INSERT ... SELECT ... WHERE NOT EXISTS pattern against a stable natural key, never a bare INSERT. They are checksum-locked once applied: editing an already-shipped file makes the next deploy fail loudly (ADR-0005 section 4) rather than silently re-applying or silently skipping. Ship a new, additively-numbered file for a later change instead of editing one already released."
+        },
+        "baseline_tables": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": [],
+          "description": "Names of this manifest's own `tables` that the seed DDL in `dir` guarantees are populated for every known tenant. Checked post-deploy (the `biffo:plugin-baseline-check` Lambda event, run from the deploy workflow after DDL imports are applied) — a table listed here with no rows for a tenant this deployment already knows about is a loud, specific deploy failure instead of a silently-empty feature (biffo-template#1554)."
+        }
+      },
+      "description": "Declares this plugin's tenant-scoped baseline-row seed. Optional — a plugin with no baseline data omits this key entirely, and nothing is vendored or checked for it."
+    },
     "tools": {
       "type": "array",
       "items": {