@biffo/cli 0.313.4 → 0.314.0

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

@@ -80,8 +80,8 @@
     }
   ],
   "ui_components": [
-    { "type": "nav-link", "label": "Example Plugin", "path": "/admin/example-plugin" },
-    { "type": "page", "label": "Widgets", "path": "/admin/example-plugin/widgets" }
+    { "type": "nav-link", "label": "Example Plugin", "path": "/admin/plugins/example-plugin" },
+    { "type": "page", "label": "Widgets", "path": "/admin/plugins/example-plugin/widgets" }
   ],
   "seed": {
     "dir": "db/seed",
@@ -89,5 +89,17 @@
   },
   "dependencies": {
     "biffo-plugin-sdk": "^1.0"
+  },
+  "user_ingress": {
+    "required_group": "founder",
+    "app": "example_plugin.user_app:app"
+  },
+  "admin_ingress": {
+    "required_group": "admin",
+    "app": "example_plugin.admin_app:app"
+  },
+  "user_frontend": {
+    "dir": "web/dist",
+    "required_group": "founder"
   }
 }

package/_skeletons/plugin-template/pyproject.toml

@@ -15,6 +15,12 @@ dependencies = [
   "biffo-plugin-sdk>=1.0,<2.0",
   "aws-lambda-powertools[tracer]>=3.4.0",
   "httpx>=0.28.1",
+  # ASGI apps for the `user_ingress`/`admin_ingress` surfaces (ADR-0021) —
+  # the shared plugin host imports and mounts `<module>:app` directly, so this
+  # is the only new runtime dependency the two placeholder apps need (no
+  # mangum/pyjwt: the host provides the Lambda entry and enforces
+  # `required_group` itself — see user_app.py's docstring).
+  "fastapi>=0.115.0",
 ]
 
 [dependency-groups]

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

@@ -0,0 +1,50 @@
+"""Placeholder ASGI app backing this plugin's `admin_ingress` surface (ADR-0021).
+
+`biffo.plugin.json`'s `admin_ingress.app` names this module's `app` object. The
+**shared plugin host** imports it, provides the Lambda entry, and mounts it at
+`/api/v1/plugins/<name>/admin/*`, enforcing `admin_ingress.required_group`
+(ADR-0011) before a request ever reaches here — see `user_app.py`'s docstring
+for why this file does no auth of its own.
+
+**This is also `web-admin/`'s one reader (biffo-template#2008).** The skeleton
+shipped a full admin frontend at `web-admin/` that no manifest field referenced
+— an orphan directory nothing would ever build or serve. `AdminIngress` in the
+SDK is explicitly "the plugin's admin-gated API and optional static UI bundle":
+unlike `user_frontend` (a separate declarative `dir`, served directly by the
+host with no plugin code involved), the admin surface's static bundle is served
+*by the app this field names* — `web-admin/`'s own `vite.config.ts` already
+targets exactly this mount point (`base:
+'/api/v1/plugins/example-plugin/admin/'`).
+
+`web-admin/dist/` is the Vite build output — gitignored, and not built by this
+repo's CI (that wiring is follow-up work; #2008's scope is declaring the
+surfaces, not shipping the built bundle, mirroring `user_frontend.dir` above
+pointing at `web/dist` before that directory exists either — see #2009). The
+mount below is skipped when `dist/` is absent, so a fresh checkout and `pytest`
+need no build step and no edits (this issue's "done when" criterion) — once
+`web-admin` is built, dropping its `dist/` in place is enough to serve it, with
+no further code change.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+
+app = FastAPI(title="example-plugin admin ingress")
+
+# src/example_plugin/admin_app.py -> src/example_plugin -> src -> repo root
+# (plugin root, where web-admin/ lives alongside biffo.plugin.json).
+WEB_ADMIN_DIST = Path(__file__).resolve().parent.parent.parent / "web-admin" / "dist"
+
+
+@app.get("/ping")
+def ping() -> dict[str, str]:
+    """Identifies the plugin, so the mount can be proven real rather than guessed at."""
+    return {"plugin": "example-plugin", "surface": "admin_ingress"}
+
+
+if WEB_ADMIN_DIST.is_dir():
+    app.mount("/", StaticFiles(directory=str(WEB_ADMIN_DIST), html=True), name="web-admin")

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

@@ -0,0 +1,31 @@
+"""Placeholder ASGI app backing this plugin's `user_ingress` surface (ADR-0021).
+
+`biffo.plugin.json`'s `user_ingress.app` names this module's `app` object. The
+**shared plugin host** imports it, provides the Lambda entry, and mounts it at
+`/api/v1/plugins/<name>/*` — a plugin declaring `user_ingress` ships no Lambda
+handler and no infrastructure of its own for this surface (see `terraform/`:
+nothing here needs a per-plugin resource).
+
+**No auth in this file, on purpose.** The host enforces `user_ingress.required_group`
+(ADR-0011) before a request ever reaches a mounted app — see
+`biffo_plugin_sdk.user_serving`'s module docstring: its `require_group` dependency
+is only for an `isolated: true` plugin running in its own Lambda outside the
+shared host. Adding a second check here would be redundant at best and a
+divergent enforcement path at worst.
+
+This is intentionally a placeholder (biffo-template#2008): one route that
+identifies the plugin, enough to prove the mount is real, not enough to be
+mistaken for a feature. Replace it with your own user-facing routes.
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+app = FastAPI(title="example-plugin user ingress")
+
+
+@app.get("/ping")
+def ping() -> dict[str, str]:
+    """Identifies the plugin, so the mount can be proven real rather than guessed at."""
+    return {"plugin": "example-plugin", "surface": "user_ingress"}

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

@@ -0,0 +1,119 @@
+"""Pins the three platform surfaces `biffo.plugin.json` declares (biffo-template#2008).
+
+Before this, `_skeletons/plugin-template` declared none of `user_ingress`,
+`admin_ingress` or `user_frontend` — the platform already serves all three
+(the working reference is `keiranholloway/biffo-plugin-ideation`'s manifest),
+but every scaffolded plugin started life exposing none of them. This test
+guards three things at once:
+
+1. the manifest actually validates against the SDK's real `PluginManifest`
+   (`extra="forbid"`, so a typo in a block's keys fails loudly rather than
+   silently dropping the surface — see `README.md`'s "Manifest validation"
+   section for why that model, not `registry-schema.json`, is authoritative);
+2. each `*_ingress.app` reference actually resolves to a real, importable ASGI
+   app — not merely a string that looks right; and
+3. each placeholder app answers with something that identifies the plugin,
+   so the mount is real rather than guessed at (this issue's own "done when").
+"""
+
+from __future__ import annotations
+
+import importlib
+
+from biffo_plugin_sdk.plugin import load_manifest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from example_plugin.manifest import MANIFEST_PATH
+
+
+def _resolve_app(app_ref: str) -> FastAPI:
+    """Resolve a manifest `*_ingress.app` string ('<module>:<attr>') the same
+    way the shared plugin host would — a plain dynamic import, not a literal
+    reference to this test's own imports, so a manifest string that drifted
+    from the real module path would be caught here rather than passing by
+    coincidence."""
+    module_name, _, attr = app_ref.partition(":")
+    module = importlib.import_module(module_name)
+    return getattr(module, attr)
+
+
+class TestManifestDeclaresAllThreeSurfaces:
+    def test_manifest_validates_and_declares_user_ingress(self) -> None:
+        manifest = load_manifest(MANIFEST_PATH)
+        assert manifest.user_ingress is not None
+        assert manifest.user_ingress.required_group == "founder"
+        assert manifest.user_ingress.app == "example_plugin.user_app:app"
+
+    def test_manifest_declares_admin_ingress(self) -> None:
+        manifest = load_manifest(MANIFEST_PATH)
+        assert manifest.admin_ingress is not None
+        assert manifest.admin_ingress.required_group == "admin"
+        assert manifest.admin_ingress.app == "example_plugin.admin_app:app"
+
+    def test_manifest_declares_user_frontend(self) -> None:
+        manifest = load_manifest(MANIFEST_PATH)
+        assert manifest.user_frontend is not None
+        assert manifest.user_frontend.dir == "web/dist"
+        assert manifest.user_frontend.required_group == "founder"
+
+    def test_ui_components_no_longer_point_at_a_dead_admin_path(self) -> None:
+        """The old `/admin/example-plugin` paths matched none of the three real
+        surfaces (this issue's own finding) — pin that they now sit under the
+        portal's real installed-plugin route instead."""
+        manifest = load_manifest(MANIFEST_PATH)
+        paths = {c.path for c in manifest.ui_components}
+        assert paths == {
+            "/admin/plugins/example-plugin",
+            "/admin/plugins/example-plugin/widgets",
+        }
+
+
+class TestIngressAppsResolveAndIdentifyThePlugin:
+    def test_user_ingress_app_resolves_and_answers(self) -> None:
+        manifest = load_manifest(MANIFEST_PATH)
+        assert manifest.user_ingress is not None
+        app = _resolve_app(manifest.user_ingress.app)
+
+        response = TestClient(app).get("/ping")
+
+        assert response.status_code == 200
+        assert response.json() == {"plugin": "example-plugin", "surface": "user_ingress"}
+
+    def test_admin_ingress_app_resolves_and_answers(self) -> None:
+        manifest = load_manifest(MANIFEST_PATH)
+        assert manifest.admin_ingress is not None
+        app = _resolve_app(manifest.admin_ingress.app)
+
+        response = TestClient(app).get("/ping")
+
+        assert response.status_code == 200
+        assert response.json() == {"plugin": "example-plugin", "surface": "admin_ingress"}
+
+
+class TestAdminIngressWebAdminOrphanResolution:
+    """`web-admin/` had no manifest field referencing it (this issue's own
+    finding). `admin_app.py` is now its one reader — these pin that the
+    reference is real (the directory `admin_app` looks for is exactly
+    `web-admin/`, not a typo'd sibling) and that a repo state with no built
+    `dist/` yet (true of this skeleton and every fresh checkout, since `dist/`
+    is gitignored and nothing builds it here — see admin_app.py's docstring)
+    still imports and serves cleanly rather than raising at import time.
+    """
+
+    def test_web_admin_dist_path_points_at_the_real_directory(self) -> None:
+        from example_plugin.admin_app import WEB_ADMIN_DIST
+
+        assert WEB_ADMIN_DIST.parent.name == "web-admin"
+        assert WEB_ADMIN_DIST.name == "dist"
+        assert WEB_ADMIN_DIST.parent.is_dir(), "web-admin/ itself must still exist"
+
+    def test_static_mount_is_skipped_when_dist_is_absent(self) -> None:
+        from example_plugin.admin_app import WEB_ADMIN_DIST, app
+
+        assert not WEB_ADMIN_DIST.is_dir(), (
+            "this test asserts the no-build-yet behaviour; if dist/ has been "
+            "built locally, the skip path this test pins is not being exercised"
+        )
+        response = TestClient(app).get("/some/never-built/asset.js")
+        assert response.status_code == 404

package/_skeletons/plugin-template/uv.lock

@@ -2,6 +2,15 @@ version = 1
 revision = 3
 requires-python = ">=3.13"
 
+[[package]]
+name = "annotated-doc"
+version = "0.0.5"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/5a/8e/38aa427ed5402449e226975b649c5dc73ccadfefeb95e6aecb8f8ea4b6b6/annotated_doc-0.0.5.tar.gz", hash = "sha256:c7e58ce09192557605d8bbd92836d7e1d520ac9580096042c0bfd197efacf1bb", size = 10758, upload-time = "2026-07-28T13:50:58.129Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3e/30/e900b21425a860e195f32e37657aa1f7c7f2b1bfb26f03ca209b90933c06/annotated_doc-0.0.5-py3-none-any.whl", hash = "sha256:117bac03a25ede5df5440e855b32d556049ca169ead221505badf432fed4b101", size = 5302, upload-time = "2026-07-28T13:50:57.239Z" },
+]
+
 [[package]]
 name = "annotated-types"
 version = "0.8.0"
@@ -70,6 +79,7 @@ source = { editable = "." }
 dependencies = [
     { name = "aws-lambda-powertools", extra = ["tracer"] },
     { name = "biffo-plugin-sdk" },
+    { name = "fastapi" },
     { name = "httpx" },
 ]
 
@@ -88,6 +98,7 @@ dev = [
 requires-dist = [
     { name = "aws-lambda-powertools", extras = ["tracer"], specifier = ">=3.4.0" },
     { name = "biffo-plugin-sdk", specifier = ">=1.0,<2.0" },
+    { name = "fastapi", specifier = ">=0.115.0" },
     { name = "httpx", specifier = ">=0.28.1" },
 ]
 
@@ -398,6 +409,22 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/07/6c/aa3f2f849e01cb6a001cd8554a88d4c77c5c1a31c95bdf1cf9301e6d9ef4/defusedxml-0.7.1-py2.py3-none-any.whl", hash = "sha256:a352e7e428770286cc899e2542b6cdaedb2b4953ff269a210103ec58f6198a61", size = 25604, upload-time = "2021-03-08T10:59:24.45Z" },
 ]
 
+[[package]]
+name = "fastapi"
+version = "0.141.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "annotated-doc" },
+    { name = "pydantic" },
+    { name = "starlette" },
+    { name = "typing-extensions" },
+    { name = "typing-inspection" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/8a/02/91e3416a8fdd715abb903a952a6bec7cdd8d14eed55d415fc8595524c319/fastapi-0.141.1.tar.gz", hash = "sha256:e8822fc40db1e1858054d7a949a888695bc9bdce70139178e33bd2871a453ca1", size = 425799, upload-time = "2026-07-29T17:18:05.568Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cb/03/10388a42375ee7e4ac9b94eb2c5c569c8b5795e377e701c9ac3ad63de890/fastapi-0.141.1-py3-none-any.whl", hash = "sha256:bfb91aa2d334c61cb35ba9a116fc123b3d3df31640b801cf57a7a78ec3f603b3", size = 131954, upload-time = "2026-07-29T17:18:04.364Z" },
+]
+
 [[package]]
 name = "filelock"
 version = "3.32.3"
@@ -1005,6 +1032,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/32/46/9cb0e58b2deb7f82b84065f37f3bffeb12413f947f9388e4cac22c4621ce/sortedcontainers-2.4.0-py2.py3-none-any.whl", hash = "sha256:a163dcaede0f1c021485e957a39245190e74249897e2ae4b2aa38595db237ee0", size = 29575, upload-time = "2021-05-16T22:03:41.177Z" },
 ]
 
+[[package]]
+name = "starlette"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b5/b4/205b0d5241d934e8add0c38aa924c4f9fb7330834ff11e5444db964ec3f9/starlette-1.6.0.tar.gz", hash = "sha256:d4e3ac5e546444960c710297a3c9fc3f7ebae1b7e963f3d36173b49da535be9b", size = 2716969, upload-time = "2026-08-08T18:27:57.512Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c8/cb/6a6a47d5b464bd08695d254f3da6e7986cc70c9fa5d778eda57538edfe56/starlette-1.6.0-py3-none-any.whl", hash = "sha256:a86dd39d14bb45f85a3d18525215a9ef0cfd1f192ac793220e72598c90335f0c", size = 75969, upload-time = "2026-08-08T18:27:56.196Z" },
+]
+
 [[package]]
 name = "tomli"
 version = "2.4.1"

package/package.json

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