@biffo/cli 0.199.0 → 0.199.2

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/dist/index.js

@@ -216,6 +216,34 @@ function latestCoreVersionFromTags(repo, git = defaultTagRunner, options = {}) {
 var CORE_TAG_PREFIX = "core-v";
 var defaultTagRunner = (args) => execFileSync("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
 
+// src/lib/git-tracked-files.ts
+import { execFileSync as execFileSync2 } from "child_process";
+import { realpathSync } from "fs";
+var defaultGit = (args) => execFileSync2("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+function gitTrackedFiles(root, git = defaultGit) {
+  let top;
+  try {
+    top = git(["-C", root, "rev-parse", "--show-toplevel"]).trim();
+  } catch {
+    return null;
+  }
+  if (!top) return null;
+  try {
+    if (realpathSync(top) !== realpathSync(root)) return null;
+  } catch {
+    return null;
+  }
+  let out;
+  try {
+    out = git(["-C", root, "ls-files", "-z"]);
+  } catch {
+    return null;
+  }
+  const files = out.split("\0").filter((p) => p !== "");
+  if (files.length === 0) return null;
+  return new Set(files);
+}
+
 // src/lib/core-manifest.ts
 var CORE_MANIFEST_FILE = "core-manifest.json";
 var CoreManifestSchema2 = z2.object({
@@ -315,8 +343,9 @@ function isTemplateOwned(relPath, manifest) {
 function toPosix(p) {
   return sep === "/" ? p : p.split(sep).join("/");
 }
-function listTemplateOwnedFiles(root, manifest) {
+function listTemplateOwnedFiles(root, manifest, options = {}) {
   const out = [];
+  const tracked = options.trackedOnly ? options.git ? gitTrackedFiles(root, options.git) : gitTrackedFiles(root) : null;
   function walk(dir) {
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
       if (entry.isDirectory() && HARD_EXCLUDED_DIRS.has(entry.name)) continue;
@@ -325,6 +354,7 @@ function listTemplateOwnedFiles(root, manifest) {
         walk(abs);
       } else if (entry.isFile()) {
         const rel = toPosix(relative(root, abs));
+        if (tracked && !tracked.has(rel)) continue;
         if (isTemplateOwned(rel, manifest)) out.push(rel);
       }
     }
@@ -335,10 +365,11 @@ function listTemplateOwnedFiles(root, manifest) {
 function sameFile(a, b) {
   return readFileSync2(a).equals(readFileSync2(b));
 }
-function computeCoreDiff(templateRoot, instanceRoot, manifest, baseRoot) {
-  const templateFiles = new Set(listTemplateOwnedFiles(templateRoot, manifest));
+function computeCoreDiff(templateRoot, instanceRoot, manifest, baseRoot, options = {}) {
+  const trackedOnly = options.git ? { trackedOnly: true, git: options.git } : { trackedOnly: true };
+  const templateFiles = new Set(listTemplateOwnedFiles(templateRoot, manifest, trackedOnly));
   const instanceFiles = new Set(listTemplateOwnedFiles(instanceRoot, manifest));
-  const baseFiles = baseRoot ? new Set(listTemplateOwnedFiles(baseRoot, manifest)) : void 0;
+  const baseFiles = baseRoot ? new Set(listTemplateOwnedFiles(baseRoot, manifest, trackedOnly)) : void 0;
   const diff = {
     added: [],
     removed: [],
@@ -687,9 +718,10 @@ var EMPTY_SUMMARY = () => ({
 });
 async function planCoreUpgrade(options) {
   const mergeFile = options.mergeFile ?? gitMergeFile;
-  const base = new Set(listTemplateOwnedFiles(options.baseDir, options.manifest));
+  const trackedOnly = { trackedOnly: true };
+  const base = new Set(listTemplateOwnedFiles(options.baseDir, options.manifest, trackedOnly));
   const ours = new Set(listTemplateOwnedFiles(options.oursDir, options.manifest));
-  const theirs = new Set(listTemplateOwnedFiles(options.theirsDir, options.manifest));
+  const theirs = new Set(listTemplateOwnedFiles(options.theirsDir, options.manifest, trackedOnly));
   const divergentPrefixes = readDivergenceConfig(options.oursDir).warnOnly.map((e) => e.prefix);
   const isDeclaredDivergent = (path) => divergentPrefixes.some((prefix) => path.startsWith(prefix));
   const paths = [.../* @__PURE__ */ new Set([...base, ...ours, ...theirs])].sort();
@@ -2401,7 +2433,7 @@ function applyMigrationCarry(instanceDir, plan) {
 }
 
 // src/lib/core-template-trees.ts
-import { execFileSync as execFileSync2 } from "child_process";
+import { execFileSync as execFileSync3 } from "child_process";
 import { mkdtempSync as mkdtempSync3, rmSync as rmSync3 } from "fs";
 import { tmpdir as tmpdir3 } from "os";
 import { join as join8 } from "path";
@@ -2409,8 +2441,8 @@ function coreTag(version) {
   parseCoreVersion(version);
   return `core-v${version}`;
 }
-var defaultGit = (args) => execFileSync2("git", args, { encoding: "utf8" });
-function workingTreeMatchesTag(repo, version, git = defaultGit) {
+var defaultGit2 = (args) => execFileSync3("git", args, { encoding: "utf8" });
+function workingTreeMatchesTag(repo, version, git = defaultGit2) {
   const tag = coreTag(version);
   try {
     const head = git(["-C", repo, "rev-parse", "HEAD"]).trim();
@@ -2430,7 +2462,7 @@ function tagExists(repo, tag, git) {
     return false;
   }
 }
-function materializeTemplateAtTag(repo, version, git = defaultGit) {
+function materializeTemplateAtTag(repo, version, git = defaultGit2) {
   const tag = coreTag(version);
   if (!tagExists(repo, tag, git)) {
     try {
@@ -2447,7 +2479,7 @@ function materializeTemplateAtTag(repo, version, git = defaultGit) {
   const tarball = join8(dir, ".tree.tar");
   try {
     git(["-C", repo, "archive", "--format=tar", "-o", tarball, tag]);
-    execFileSync2("tar", ["-x", "-f", tarball, "-C", dir]);
+    execFileSync3("tar", ["-x", "-f", tarball, "-C", dir]);
     rmSync3(tarball, { force: true });
   } catch (err) {
     rmSync3(dir, { recursive: true, force: true });

package/package.json

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