@biffo/cli 0.198.9 → 0.199.1

package/_skeletons/plugin-template/README.md

@@ -55,9 +55,36 @@ engine** (`services/_plugins/orchestrator/` in the biffo-template monorepo) —
 class, same layout, and it ships a real `terraform/` too. It has considerably
 more moving parts (workflow definitions, actions, SigV4 calls into the Core
 API); this template's `example_plugin` is deliberately the smallest version of
-the same shape: one table (`example_widgets`), four routes, one `on_install`
+the same shape: one table (`example_widgets`), four routes, one idempotent
 seed, one `@subscribe` handler.
 
+### Seeding: not from `on_install()`
+
+`BiffoPluginBase` requires `on_install()`, `on_uninstall()` and `on_upgrade()`,
+and they are **not invoked** — ADR-0003 §9 described a `biffo plugin install`
+that would call them and the call site was never built. Define them as no-ops,
+as `plugin.py` does. An earlier revision of this skeleton seeded through
+`on_install()`; anyone who copied it got a seed that silently never ran, the
+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:
+
+- **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
+  itself, because Starlette's `Mount` never delivers the lifespan scope — until
+  [#948](https://github.com/keiranholloway/biffo-template/pull/948) a plugin's
+  own `@app.on_event("startup")` was equally dead. It fires on every cold start,
+  so the seed must be idempotent; Core's own
+  `POST /api/v1/internal/plugins/me/config/seed` was not idempotent until
+  [#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.
+
 > Earlier revisions of this README pointed at an RBAC reference plugin at
 > `services/rbac/`. That plugin was removed by
 > [ADR-0011](https://github.com/keiranholloway/biffo-template/blob/main/docs/ADR/0011-authorization-is-a-core-concern.md)

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

@@ -24,7 +24,7 @@
           "name": "is_active",
           "type": "Boolean",
           "nullable": true,
-          "description": "Nullable because declared column defaults are not applied by the generated migration DDL (only the in-process SQLAlchemy model) — see README's 'Known limitations' section. Treat NULL as false; this plugin's own on_install() always sets it explicitly."
+          "description": "Nullable because declared column defaults are not applied by the generated migration DDL (only the in-process SQLAlchemy model) — see README's 'Known limitations' section. Treat NULL as false; this plugin's own seed always sets it explicitly."
         }
       ],
       "indexes": [

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

@@ -1,11 +1,17 @@
 """ExamplePlugin — this plugin's BiffoPluginBase implementation.
 
-Seeds a single default widget on install and reacts to
-`biffo.core/UserCreated` by logging the new user. Replace both with real
-logic for your own plugin — this exists to show a working, correctly-wired
-skeleton: constructor -> manifest loading -> `self.api` -> `@self.subscribe`
--> `on_install`/`on_uninstall`, exercised end to end by the tests in
-`tests/test_example_plugin.py`.
+Reacts to `biffo.core/UserCreated` by logging the new user, and carries an
+idempotent seed for its baseline row. Replace both with real logic for your
+own plugin — this exists to show a working, correctly-wired skeleton:
+constructor -> manifest loading -> `self.api` -> `@self.subscribe`, exercised
+end to end by the tests in `tests/test_example_plugin.py`.
+
+**`on_install()` / `on_uninstall()` are not invoked.** They are required by
+`BiffoPluginBase` and nothing calls them, so they are no-ops here and should
+be no-ops in your plugin (biffo-template#709). An earlier version of this
+skeleton seeded through `on_install()` — copying that gives you a seed that
+silently never runs. `seed_default_widget()` below shows where seeding
+actually goes.
 
 Modelled directly on the RBAC reference plugin's
 `services/rbac/src/rbac/plugin.py` (PR #76) in the biffo-template monorepo —
@@ -15,7 +21,6 @@ tables, an event-driven side effect, and an in-process (non-CRUD) helper.
 
 from __future__ import annotations
 
-import asyncio
 from typing import Any
 
 from aws_lambda_powertools import Logger
@@ -27,11 +32,11 @@ logger = Logger()
 
 _PLUGIN_BASE_PATH = "/api/v1/plugins/example-plugin"
 
-# Seeded by on_install(). Real plugins would seed whatever baseline data
-# their feature needs (RBAC's plugin.py seeds three roles, for example).
+# Seeded by seed_default_widget(). Real plugins would seed whatever baseline
+# data their feature needs.
 _DEFAULT_WIDGET: dict[str, Any] = {
     "name": "starter-widget",
-    "description": "Created automatically by on_install(). Safe to delete.",
+    "description": "Created by this plugin's own seed. Safe to delete.",
     "is_active": True,
 }
 
@@ -48,23 +53,50 @@ class ExamplePlugin(BiffoPluginBase):
             await self._log_user_created(event)
 
     def on_install(self) -> None:
-        """Called by the CLI when the plugin is installed.
+        """No-op. **Not invoked** — nothing calls it (biffo-template#709).
 
-        `BiffoPluginBase.on_install` is declared synchronous but
-        `BiffoAPIClient` is entirely async (same constraint the RBAC
-        reference plugin documents) — bridge with `asyncio.run` here and
-        keep the actual async logic in the public `seed_default_widget()`,
-        which tests and any future async caller can `await` directly.
+        `BiffoPluginBase` requires it, so it is defined; `biffo plugin
+        install` does not run it, and neither does anything else. Put no
+        logic here. Seeding goes in `seed_default_widget()` below.
         """
-        asyncio.run(self.seed_default_widget())
+        return None
 
     async def seed_default_widget(self) -> None:
-        """The async core of on_install().
-
-        Generic CRUD (issue #19) has no upsert — every POST creates a new
-        row — so this lists existing widgets first and only creates the
-        default one if it's missing by name, making repeated installs a
-        no-op instead of creating duplicate rows.
+        """Create this plugin's baseline row, idempotently.
+
+        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()`:
+
+        - **A plugin with an `api_ingress` ASGI app** (ADR-0021) seeds from
+          its app's *lifespan*, which the shared plugin host drives on the
+          first invocation of each process::
+
+              @asynccontextmanager
+              async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+                  await plugin.seed_default_widget()
+                  yield
+
+              app = FastAPI(lifespan=lifespan)
+
+          The host has to run that handshake itself, because Starlette's
+          `Mount` never delivers the lifespan scope to a mounted app — until
+          biffo-template#948 a plugin's own `@app.on_event("startup")` was as
+          dead as `on_install()`. It runs on every cold start, so the seed
+          must be idempotent (below), and Core's own seed endpoint
+          `POST /api/v1/internal/plugins/me/config/seed` was itself not
+          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.
+
+        Idempotency: generic CRUD (issue #19) has no upsert — every POST
+        creates a new row — so this lists existing widgets first and only
+        creates the default one if it's missing by name, making a repeated
+        cold start a no-op instead of accumulating duplicates.
         """
         existing = await self.api.get(f"{_PLUGIN_BASE_PATH}/widgets")
         existing_names = {row.get("name") for row in existing}
@@ -72,13 +104,12 @@ class ExamplePlugin(BiffoPluginBase):
             await self.api.post(f"{_PLUGIN_BASE_PATH}/widgets", json=dict(_DEFAULT_WIDGET))
 
     def on_uninstall(self) -> None:
-        """Called by the CLI when the plugin is uninstalled.
+        """No-op. **Not invoked** — nothing calls it (biffo-template#709).
 
-        No-op: dropping this plugin's tables is the CLI's job (ADR-0003
-        section 9 — `biffo plugin uninstall` applies a generated migration
-        that drops them). Override this if your plugin needs additional
-        cleanup beyond that (e.g. deleting objects it created outside its
-        own tables).
+        There is no teardown moment for it to belong to either: `biffo plugin
+        uninstall` removes the plugin's code and Terraform and deliberately
+        leaves its tables in place (ADR-0003 section 9). Cleanup beyond that
+        is a hand-written Alembic migration, not a hook.
         """
         return None
 

package/_skeletons/plugin-template/tests/test_example_plugin.py

@@ -1,5 +1,9 @@
-"""Tests for ExamplePlugin: manifest loading, lifecycle hooks, and the
-UserCreated event subscription.
+"""Tests for ExamplePlugin: manifest loading, the seed, and the UserCreated
+event subscription.
+
+`on_install()` / `on_uninstall()` are asserted to be no-ops, not to seed:
+they are **not invoked** by anything (biffo-template#709), so a test that
+proved seeding through them would be proving something that never happens.
 
 Modelled on the RBAC reference plugin's
 `services/rbac/tests/test_rbac_plugin.py` (PR #76) in the biffo-template
@@ -48,7 +52,7 @@ class TestSubscription:
         assert plugin.events.has_subscription("UserCreated")
 
 
-class TestOnInstall:
+class TestSeeding:
     async def test_seeds_default_widget(self) -> None:
         plugin, fake = _make_plugin()
 
@@ -73,22 +77,29 @@ class TestOnInstall:
         widget = fake.tables["widgets"][0]
         assert widget["is_active"] is True
 
+
+class TestLifecycleHooksAreNoOps:
+    """The ABC's hooks are **not invoked** by anything (biffo-template#709).
+
+    So the contract worth asserting is that they do nothing — in particular
+    that neither of them seeds. A plugin whose baseline data depends on one
+    of these ships a seed that never runs.
+    """
+
+    def test_on_install_is_a_noop_and_seeds_nothing(self) -> None:
+        plugin, fake = _make_plugin()
+
+        assert plugin.on_install() is None
+        assert fake.tables["widgets"] == []
+
     def test_on_uninstall_is_a_noop(self) -> None:
         plugin, _ = _make_plugin()
         assert plugin.on_uninstall() is None
 
-    def test_on_install_sync_bridge_seeds_widget(self) -> None:
-        """The public, ABC-compliant on_install() entrypoint (a plain sync
-        function calling asyncio.run(seed_default_widget()) internally) —
-        exercised from a genuinely synchronous test function, the same kind
-        of context the CLI would call it from, since asyncio.run() cannot be
-        nested inside pytest-asyncio's already-running loop."""
+    def test_on_upgrade_is_a_noop(self) -> None:
         plugin, fake = _make_plugin()
-
-        plugin.on_install()
-
-        names = {r["name"] for r in fake.tables["widgets"]}
-        assert names == {_DEFAULT_WIDGET["name"]}
+        assert plugin.on_upgrade("0.0.1") is None
+        assert fake.tables["widgets"] == []
 
 
 class TestUserCreatedLogsEvent:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.198.9",
+  "version": "0.199.1",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",