@biffo/cli 0.38.0 → 0.41.0

package/_skeletons/plugin-template/terraform/main.tf

@@ -0,0 +1,167 @@
+# Template Terraform module for a Biffo plugin (ADR-0003 chunk 12 / issues #25, #201).
+#
+# Copy this directory to modules/plugins/<name>/ inside a plugin repo (as
+# terraform/, per ADR-0003 section 2's plugin repo layout) and adjust as
+# needed. `biffo plugin install <name>@<minor>` copies that terraform/
+# directory into the user's monorepo at modules/plugins/<name>/ and then
+# generates the instantiating `module "plugin_<name>"` block — gated on
+# `enabled_plugins` — into infra/environments/<env>/plugins.generated.tf. That
+# file is CLI-owned and regenerated on every install/uninstall; main.tf is
+# never edited. See infra/environments/dev/README.md's "Adding a plugin".
+#
+# This module deliberately wraps two existing modules rather than
+# reimplementing Lambda/IAM/EventBridge from scratch:
+#   - modules/cloud/aws/compute — the plugin's Lambda function, with the
+#     same DLQ/logging/tracing/least-privilege IAM baseline every Biffo
+#     function gets.
+#   - modules/cloud/aws/events (via the shared event_bus_name passed in) —
+#     this module adds only the subscription rule/target/permission a
+#     plugin needs to react to events on the bus the root config already
+#     owns. No new bus is created.
+#
+# What this module does NOT do, per ADR-0002 ("no DB clients outside
+# services/api/", "microservices call the API via HTTP and react to
+# EventBridge events"):
+#   - It never creates a database, and never receives
+#     db_credentials_secret_arn — that variable is wired to the Core API's
+#     Lambda only (infra/environments/dev/main.tf's module "core_api" block).
+#     A plugin that needs platform data calls the Core API over HTTPS
+#     (BIFFO_CORE_API_URL, see variables.tf) using the plugin SDK's
+#     BiffoAPIClient, exactly like any other API consumer.
+#   - It never attaches to the VPC unless var.enable_vpc_access is set to
+#     true — see variables.tf's enable_vpc_access description for why.
+#
+# Loose coupling: this module must not reference other plugin modules or
+# their resources. Each plugin is instantiated independently by the root
+# config; nothing here should assume any other plugin is installed.
+
+terraform {
+  required_providers {
+    aws = { source = "hashicorp/aws", version = "~> 5.0" }
+  }
+}
+
+locals {
+  name_prefix   = "${var.project_name}-${var.environment}"
+  function_name = "${local.name_prefix}-plugin-${var.plugin_name}"
+  # A rule is created when the plugin subscribes to specific events, or when it
+  # is a generic forwarder that reacts to every event (subscribe_all).
+  has_subscriptions = var.subscribe_all || length(var.event_subscriptions) > 0
+  # Grant Core API access only when the root config told us which API to scope
+  # it to. Empty (the default) => the plugin never calls Core, so no grant.
+  grants_core_api_access = var.core_api_execution_arn != ""
+}
+
+# Compute — the plugin's Lambda function.
+module "function" {
+  source = "../../cloud/aws/compute"
+
+  project_name       = var.project_name
+  environment        = var.environment
+  function_name      = "plugin-${var.plugin_name}"
+  handler            = var.handler
+  runtime            = var.runtime
+  memory_size        = var.memory_size
+  timeout            = var.timeout
+  enable_vpc_access  = var.enable_vpc_access
+  vpc_id             = var.vpc_id
+  private_subnet_ids = var.private_subnet_ids
+  event_bus_name     = var.event_bus_name
+
+  # No db_credentials_secret_arn — see the ADR-0002 note above.
+  environment_variables = merge(
+    {
+      BIFFO_CORE_API_URL = var.core_api_url
+      BIFFO_PLUGIN_NAME  = var.plugin_name
+    },
+    var.environment_variables,
+  )
+
+  sqs_kms_key_id        = var.sqs_kms_key_id
+  cloudwatch_kms_key_id = var.cloudwatch_kms_key_id
+  tags                  = var.tags
+}
+
+# Events — subscribe the plugin's Lambda to its declared event_subscriptions
+# on the shared bus. Each subscription is matched as its own source +
+# detail-type pair via `$or`, rather than independent `source`/`detail-type`
+# arrays, to avoid EventBridge matching the cross product of unrelated
+# source/detail-type combinations when a plugin subscribes to more than one
+# event.
+resource "aws_cloudwatch_event_rule" "subscription" {
+  count          = local.has_subscriptions ? 1 : 0
+  name           = "${local.function_name}-events"
+  description    = "Routes subscribed events to the ${var.plugin_name} plugin"
+  event_bus_name = var.event_bus_name
+
+  # subscribe_all → match every event on the bus (a generic forwarder; the plugin
+  # decides what to do, so new triggers need no Terraform change — ADR-0010). Else
+  # a single subscription uses a flat pattern and two or more are OR-ed: EventBridge
+  # rejects a `$or` with fewer than 2 elements ("There must have at least 2 Objects
+  # in $or relationship"), so the single-subscription case must not use it.
+  # jsonencode is applied inside each branch so the conditional's arms are all
+  # strings — a `cond ? {a} : {b}` on differently-shaped objects is an "Inconsistent
+  # conditional result types" error at apply (validate misses it).
+  event_pattern = var.subscribe_all ? jsonencode({
+    source = [{ prefix = "" }]
+    }) : length(var.event_subscriptions) == 1 ? jsonencode({
+    source        = [var.event_subscriptions[0].source]
+    "detail-type" = [var.event_subscriptions[0].detail_type]
+    }) : jsonencode({
+    "$or" = [
+      for s in var.event_subscriptions : {
+        source        = [s.source]
+        "detail-type" = [s.detail_type]
+      }
+    ]
+  })
+
+  tags = var.tags
+}
+
+resource "aws_cloudwatch_event_target" "subscription" {
+  count          = local.has_subscriptions ? 1 : 0
+  rule           = aws_cloudwatch_event_rule.subscription[0].name
+  event_bus_name = var.event_bus_name
+  target_id      = "${var.plugin_name}-lambda"
+  arn            = module.function.function_arn
+}
+
+resource "aws_lambda_permission" "subscription" {
+  count         = local.has_subscriptions ? 1 : 0
+  statement_id  = "AllowEventBridgeInvoke"
+  action        = "lambda:InvokeFunction"
+  function_name = module.function.function_name
+  principal     = "events.amazonaws.com"
+  source_arn    = aws_cloudwatch_event_rule.subscription[0].arn
+}
+
+# Core API access (ADR-0009) — the plugin->Core auth path.
+#
+# ADR-0002 forbids this Lambda from touching the database, so anything it needs
+# from the platform it gets over HTTPS from the Core API. The Core API's
+# internal routes (/api/v1/internal/*) are IAM-authorized, not Cognito-JWT, so
+# the plugin authenticates by SigV4-signing with this Lambda role — see
+# biffo_plugin_sdk.SignedCoreClient, which BiffoPluginBase uses by default. No
+# bearer token, no shared secret, nothing to rotate.
+#
+# Scoped to the /api/v1/internal/* prefix on one API, never the whole API.
+data "aws_iam_policy_document" "core_api" {
+  count = local.grants_core_api_access ? 1 : 0
+
+  statement {
+    sid       = "InvokeCoreInternalApi"
+    effect    = "Allow"
+    actions   = ["execute-api:Invoke"]
+    resources = ["${var.core_api_execution_arn}/*/*/api/v1/internal/*"]
+  }
+}
+
+resource "aws_iam_role_policy" "core_api" {
+  count = local.grants_core_api_access ? 1 : 0
+  name  = "${local.function_name}-core-api"
+  # compute exposes the role via its ARN; derive the role name (last ARN
+  # segment) since aws_iam_role_policy wants the name, not the ARN.
+  role   = element(split("/", module.function.role_arn), length(split("/", module.function.role_arn)) - 1)
+  policy = data.aws_iam_policy_document.core_api[0].json
+}

package/_skeletons/plugin-template/terraform/outputs.tf

@@ -0,0 +1,33 @@
+output "function_arn" {
+  description = "Lambda function ARN — aggregate this in the root config's plugin outputs."
+  value       = module.function.function_arn
+}
+
+output "function_name" {
+  value = module.function.function_name
+}
+
+# The plugin Lambda's execution role ARN. Useful for auditing, but note this is
+# deliberately NOT how the role reaches the Core API's
+# BIFFO_SERVICE_PRINCIPAL_ARN_ALLOWLIST — wiring this output into the core_api
+# module would create the dependency cycle core_api -> api_gateway -> plugin ->
+# core_api (issue #201). Allowlist the predictable assumed-role glob instead;
+# see README.md.
+output "role_arn" {
+  value = module.function.role_arn
+}
+
+output "role_name" {
+  description = "The plugin Lambda's execution role NAME — the value to interpolate into the Core API's BIFFO_SERVICE_PRINCIPAL_ARN_ALLOWLIST glob (arn:aws:sts::<acct>:assumed-role/<role-name>/*)."
+  value       = element(split("/", module.function.role_arn), length(split("/", module.function.role_arn)) - 1)
+}
+
+output "dlq_arn" {
+  description = "Dead letter queue ARN for failed invocations (both direct and EventBridge-triggered)."
+  value       = module.function.dlq_arn
+}
+
+output "event_rule_arn" {
+  description = "EventBridge rule ARN, or null when the plugin declares no event_subscriptions."
+  value       = local.has_subscriptions ? aws_cloudwatch_event_rule.subscription[0].arn : null
+}

package/_skeletons/plugin-template/terraform/variables.tf

@@ -0,0 +1,133 @@
+variable "project_name" {
+  description = "Biffo project name — passed through unchanged from the root config."
+  type        = string
+}
+
+variable "environment" {
+  description = "Deployment environment (dev/staging/prod) — passed through unchanged from the root config."
+  type        = string
+}
+
+variable "plugin_name" {
+  description = "Plugin slug, matching biffo.plugin.json's `name` field and the services/<name>/ directory this plugin was installed into (ADR-0003 section 2). Used to namespace every resource this module creates."
+  type        = string
+}
+
+variable "handler" {
+  description = "Lambda handler entrypoint, e.g. `src.lambda.main.handler` per the plugin repo layout in ADR-0003 section 2."
+  type        = string
+}
+
+variable "runtime" {
+  type    = string
+  default = "python3.13"
+}
+
+variable "memory_size" {
+  type    = number
+  default = 512
+}
+
+variable "timeout" {
+  type    = number
+  default = 30
+}
+
+variable "enable_vpc_access" {
+  description = <<-EOT
+    Attach this plugin's Lambda to a VPC. Leave false (the default) — per
+    ADR-0002, plugins never access the database directly, only the Core API
+    over HTTPS and EventBridge, so VPC attachment is normally unnecessary.
+    In NAT-less networking configs (e.g. dev's enable_nat_gateway = false),
+    attaching to the VPC would also cut off the outbound internet access
+    this Lambda needs to reach the Core API's public endpoint. Only enable
+    this if the plugin has a genuine, ADR-0002-compliant reason to reach a
+    VPC-only resource (e.g. ElastiCache) — never to reach the database.
+
+    Must be an explicit boolean, not inferred from whether vpc_id is set —
+    vpc_id can be only known after apply (e.g. if it were ever passed from
+    a VPC created in the same plan), and Terraform's count/for_each in the
+    underlying compute module cannot depend on a not-yet-known value.
+  EOT
+  type        = bool
+  default     = false
+}
+
+variable "vpc_id" {
+  description = "VPC to attach this plugin's Lambda to. Only used when enable_vpc_access is true."
+  type        = string
+  default     = ""
+}
+
+variable "private_subnet_ids" {
+  description = "Private subnets to place ENIs in. Only used when enable_vpc_access is true."
+  type        = list(string)
+  default     = []
+}
+
+variable "core_api_url" {
+  description = "Core API base URL (module.api_gateway.api_endpoint from the root config). Injected as BIFFO_CORE_API_URL — the plugin SDK's BiffoAPIClient reads this env var by default (packages/python-sdk/src/biffo_plugin_sdk/client.py). This is how plugins read/write platform data per ADR-0002 — never a direct DB connection."
+  type        = string
+  default     = ""
+}
+
+variable "core_api_execution_arn" {
+  description = <<-EOT
+    The Core API Gateway's execution ARN (module.api_gateway.execution_arn from
+    the root config, i.e. arn:aws:execute-api:<region>:<acct>:<api-id>). When
+    set, this plugin's Lambda role is granted execute-api:Invoke scoped to that
+    API's /api/v1/internal/* routes only — the plugin->Core auth mechanism from
+    ADR-0009 (IAM SigV4), which the plugin SDK's SignedCoreClient speaks.
+
+    Leave empty (the default) only if the plugin never calls the Core API. It
+    is not enough on its own: the Core API independently re-checks the caller
+    against BIFFO_SERVICE_PRINCIPAL_ARN_ALLOWLIST, so the plugin's role must
+    also be allowlisted there — see this module's README for the exact glob and
+    why it is a static string rather than this module's role_arn output.
+  EOT
+  type        = string
+  default     = ""
+}
+
+variable "event_bus_name" {
+  description = "Name of the shared EventBridge bus (module.events.event_bus_name from the root config). This module subscribes to it — it never creates its own bus, keeping every plugin's events on one platform-wide bus per ADR-0002."
+  type        = string
+}
+
+variable "event_subscriptions" {
+  description = "Events this plugin reacts to, mirroring biffo.plugin.json's `event_subscriptions` array (ADR-0003 section 2), e.g. [{ source = \"biffo.core\", detail_type = \"UserCreated\" }]. Leave empty if the plugin only calls the Core API and never reacts to events — no EventBridge rule is created in that case. Ignored when `subscribe_all` is true."
+  type = list(object({
+    source      = string
+    detail_type = string
+  }))
+  default = []
+}
+
+variable "subscribe_all" {
+  description = "Subscribe to every event on the bus (a generic forwarder). When true, `event_subscriptions` is ignored and the rule matches all events, so the plugin — not Terraform — decides what to act on and a new trigger needs no infra change (ADR-0010). Use for engines like the orchestrator that forward everything to the Core API for matching."
+  type        = bool
+  default     = false
+}
+
+variable "environment_variables" {
+  description = "Additional environment variables for the plugin's Lambda, merged over BIFFO_CORE_API_URL / BIFFO_PLUGIN_NAME. Do not put database connection details here — plugins never receive them (ADR-0002)."
+  type        = map(string)
+  default     = {}
+}
+
+variable "sqs_kms_key_id" {
+  description = "KMS key ID for the DLQ's SQS queue encryption (CKV_AWS_27). Leave empty for AWS-owned key."
+  type        = string
+  default     = ""
+}
+
+variable "cloudwatch_kms_key_id" {
+  description = "KMS key ID for CloudWatch log group encryption (CKV_AWS_158). Leave empty for AWS-owned key."
+  type        = string
+  default     = ""
+}
+
+variable "tags" {
+  type    = map(string)
+  default = {}
+}

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

@@ -0,0 +1,17 @@
+"""Make `example_plugin` and the test-local `fakes` module importable.
+
+This template is a standalone repo (not part of the biffo-template
+monorepo's uv workspace — see README's "Standalone repo" note), so
+`example_plugin` is installed normally via the project's own
+[build-system]/hatchling config when `uv sync` runs. This conftest only
+needs to put `tests/` itself on sys.path so `tests/test_example_plugin.py`
+can `import fakes` as a plain sibling module (pytest's rootdir insertion
+already covers this in most configurations, but the explicit path insert
+keeps this working from any cwd, matching the RBAC reference plugin's
+`services/rbac/tests/conftest.py` pattern in the biffo-template monorepo).
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))

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

@@ -0,0 +1,74 @@
+"""A tiny in-memory fake of the Core API's generic CRUD routes
+(`/api/v1/plugins/example-plugin/*`), used to test this plugin without a
+real Core API or network call.
+
+Mirrors the shape `build_plugin_router` in
+`services/api/src/api/routing/plugin_router.py` (biffo-template monorepo)
+actually produces (id auto-assigned, tenant_id auto-assigned, list/create/
+read/delete by path), so these tests exercise realistic request/response
+semantics rather than hand-picked canned responses. Copied from the RBAC
+reference plugin's `services/rbac/tests/fakes.py` (PR #76) and trimmed to
+this plugin's single `widgets` resource.
+"""
+
+from __future__ import annotations
+
+import json
+from itertools import count
+from typing import Any
+
+import httpx
+from biffo_plugin_sdk import BiffoAPIClient
+
+_BASE_PATH = "/api/v1/plugins/example-plugin"
+
+
+class FakeCoreApi:
+    """Fake backing store for the plugin's own generic CRUD routes."""
+
+    def __init__(self) -> None:
+        self.tables: dict[str, list[dict[str, Any]]] = {"widgets": []}
+        self.request_log: list[tuple[str, str]] = []
+        self._ids = count(1)
+
+    def client(self) -> BiffoAPIClient:
+        transport = httpx.MockTransport(self._handle)
+        async_client = httpx.AsyncClient(transport=transport)
+        return BiffoAPIClient(
+            base_url="https://core.example.com", token="test-jwt", client=async_client
+        )
+
+    def _handle(self, request: httpx.Request) -> httpx.Response:
+        path = request.url.path
+        assert path.startswith(_BASE_PATH), f"unexpected path: {path}"
+        self.request_log.append((request.method, path))
+
+        rest = path[len(_BASE_PATH) :].strip("/")
+        parts = rest.split("/") if rest else []
+        table = parts[0]
+        row_id = parts[1] if len(parts) > 1 else None
+        rows = self.tables.setdefault(table, [])
+
+        if request.method == "GET" and row_id is None:
+            return httpx.Response(200, json=rows)
+
+        if request.method == "GET" and row_id is not None:
+            row = next((r for r in rows if r["id"] == row_id), None)
+            if row is None:
+                return httpx.Response(404, json={"detail": "Not found"})
+            return httpx.Response(200, json=row)
+
+        if request.method == "POST":
+            payload = json.loads(request.content or b"{}")
+            row = {"id": f"id-{next(self._ids)}", "tenant_id": "default", **payload}
+            rows.append(row)
+            return httpx.Response(201, json=row)
+
+        if request.method == "DELETE" and row_id is not None:
+            before = len(rows)
+            self.tables[table] = [r for r in rows if r["id"] != row_id]
+            if len(self.tables[table]) == before:
+                return httpx.Response(404, json={"detail": "Not found"})
+            return httpx.Response(200, json={"deleted": True, "id": row_id})
+
+        return httpx.Response(404, json={"detail": "Not found"})

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

@@ -0,0 +1,108 @@
+"""Tests for ExamplePlugin: manifest loading, lifecycle hooks, and the
+UserCreated event subscription.
+
+Modelled on the RBAC reference plugin's
+`services/rbac/tests/test_rbac_plugin.py` (PR #76) in the biffo-template
+monorepo.
+"""
+
+from __future__ import annotations
+
+from biffo_plugin_sdk import BiffoEvent
+from fakes import FakeCoreApi
+
+from example_plugin.plugin import _DEFAULT_WIDGET, ExamplePlugin
+
+
+def _make_plugin() -> tuple[ExamplePlugin, FakeCoreApi]:
+    fake = FakeCoreApi()
+    plugin = ExamplePlugin(api=fake.client())
+    return plugin, fake
+
+
+class TestManifestLoading:
+    def test_manifest_name_and_version(self) -> None:
+        plugin, _ = _make_plugin()
+        assert plugin.manifest.name == "example-plugin"
+        assert plugin.manifest.version == "0.1.0"
+
+    def test_manifest_declares_the_widgets_table(self) -> None:
+        plugin, _ = _make_plugin()
+        table_names = {t.name for t in plugin.manifest.tables}
+        assert table_names == {"example_widgets"}
+
+    def test_register_returns_manifest_registration(self) -> None:
+        plugin, _ = _make_plugin()
+        registration = plugin.register()
+        assert registration["name"] == "example-plugin"
+        assert {t["name"] for t in registration["tables"]} == {"example_widgets"}
+        assert {r["path"] for r in registration["api_routes"]} == {
+            "/widgets",
+            "/widgets/{id}",
+        }
+
+
+class TestSubscription:
+    def test_subscribes_to_user_created(self) -> None:
+        plugin, _ = _make_plugin()
+        assert plugin.events.has_subscription("UserCreated")
+
+
+class TestOnInstall:
+    async def test_seeds_default_widget(self) -> None:
+        plugin, fake = _make_plugin()
+
+        await plugin.seed_default_widget()
+
+        names = {r["name"] for r in fake.tables["widgets"]}
+        assert names == {_DEFAULT_WIDGET["name"]}
+
+    async def test_is_idempotent(self) -> None:
+        plugin, fake = _make_plugin()
+
+        await plugin.seed_default_widget()
+        await plugin.seed_default_widget()
+
+        assert len(fake.tables["widgets"]) == 1
+
+    async def test_default_widget_marked_active(self) -> None:
+        plugin, fake = _make_plugin()
+
+        await plugin.seed_default_widget()
+
+        widget = fake.tables["widgets"][0]
+        assert widget["is_active"] is True
+
+    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."""
+        plugin, fake = _make_plugin()
+
+        plugin.on_install()
+
+        names = {r["name"] for r in fake.tables["widgets"]}
+        assert names == {_DEFAULT_WIDGET["name"]}
+
+
+class TestUserCreatedLogsEvent:
+    async def test_dispatch_does_not_raise(self) -> None:
+        """The example handler only logs — this proves the subscription is
+        wired end to end (event -> EventSubscriber -> handler) without
+        raising, the same shape a real handler with side effects would be
+        tested in (see RBAC's test_rbac_plugin.py for a handler that
+        actually mutates state via self.api)."""
+        plugin, _ = _make_plugin()
+
+        event = BiffoEvent(
+            detail_type="UserCreated",
+            tenant_id="default",
+            payload={"cognito_sub": "user-123", "email": "new@example.com"},
+        )
+        await plugin.events.dispatch(event)

package/_skeletons/registry/README.md

@@ -0,0 +1,27 @@
+# Biffo Plugin Manifest Schema Validator
+
+Validates `biffo.plugin.json` against the registry schema.
+Used by: CLI install flow, registry CI, SDK register_plugin().
+
+## Usage
+
+```bash
+python -m jsonschema -i biffo.plugin.json registry-schema.json
+```
+
+Or programmatically:
+
+```python
+from jsonschema import validate, ValidationError
+
+with open("registry-schema.json") as f:
+    schema = json.load(f)
+
+with open("biffo.plugin.json") as f:
+    manifest = json.load(f)
+
+try:
+    validate(instance=manifest, schema=schema)
+except ValidationError as e:
+    print(f"Invalid manifest: {e.message}")
+```

package/_skeletons/registry/plugins.json

@@ -0,0 +1,5 @@
+{
+  "schema_version": "1.0",
+  "last_updated": "2026-06-30T00:00:00Z",
+  "plugins": []
+}