@biffo/cli 0.39.0 → 0.41.0

package/_skeletons/plugin-template/.github/workflows/ci.yml

@@ -0,0 +1,124 @@
+name: CI
+
+# Scaled down from biffo-template's own root .github/workflows/ci.yml for a
+# single Python package: a plugin repo (per ADR-0003) extends the SDK and
+# has no JS/TS and no Terraform of its own — Terraform, if a plugin ships
+# any, is provisioned by the *consuming* project's infra, not this repo's
+# CI (see README's "What this repo does not build" section).
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  PYTHON_VERSION: '3.13'
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --all-groups
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --all-groups
+      - run: uv run pyright
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --all-groups
+      - run: uv run pytest --cov --cov-report=xml
+      - uses: codecov/codecov-action@v5
+        if: always()
+        with:
+          files: coverage.xml
+
+  validate-manifest:
+    name: Validate biffo.plugin.json
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --all-groups
+      # Authoritative check: load_manifest() runs the *real* Pydantic model
+      # (biffo_plugin_sdk.plugin.PluginManifest) that the SDK, the Core API's
+      # discover_plugin_manifests(), and `biffo plugin install` all actually
+      # validate against — same reasoning cli/src/lib/plugin-manifest.ts
+      # documents for why the CLI validates this way rather than against
+      # registry-schema.json directly (see the next step).
+      - name: Validate against the SDK's PluginManifest model (authoritative)
+        run: |
+          uv run python -c "
+          from biffo_plugin_sdk.plugin import load_manifest
+          manifest = load_manifest('biffo.plugin.json')
+          print(f'OK: {manifest.name}@{manifest.version} — '
+                f'{len(manifest.tables)} table(s), {len(manifest.api_routes)} route(s)')
+          "
+      # Advisory check, not a gate: registry-schema.json (vendored from
+      # _skeletons/registry/registry-schema.json in biffo-template) is the
+      # nominal marketplace registry schema, but its api_routes shape
+      # predates issue #19's table/operation CRUD-synthesis redesign — it
+      # still requires a free-form `handler` function-name field, and its
+      # `path` regex rejects the `{id}` path parameter every single-row
+      # route (read/update/delete) is required to have. A manifest that is
+      # valid per the real PluginManifest model above (checked and pinned in
+      # this repo's uv.lock) will therefore *fail* strict validation here —
+      # confirmed directly against this template's own example manifest.
+      # Run non-blocking until the registry schema is corrected upstream;
+      # see README.md's "Manifest validation" section for the full story.
+      - name: Validate against the vendored registry schema (advisory, non-blocking)
+        continue-on-error: true
+        run: |
+          uv run python -m jsonschema -i biffo.plugin.json registry-schema.json
+
+  security-secrets:
+    name: Secret Scan
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          fetch-depth: 0
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  security-deps:
+    name: Dependency Audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --all-groups
+      - run: uv run pip-audit

package/_skeletons/plugin-template/.github/workflows/release.yml

@@ -0,0 +1,114 @@
+name: Release
+
+# Runs on every push of a `v*` tag: bumps/verifies the version via
+# python-semantic-release, builds the sdist/wheel, and publishes to PyPI.
+#
+# ASPIRATIONAL PYPI PUBLISH: this repo (and every plugin repo forked from
+# this template) has no real PyPI project or publishing credential yet, so
+# the publish job below runs and fails at the
+# `pypa/gh-action-pypi-publish` step — that's expected, not a bug in this
+# template. Configure a publisher for *your* plugin's own PyPI project and
+# it starts publishing on the next tag push with no further changes. See
+# README.md's "PyPI publishing" section.
+#
+# Note this is about *this plugin's* own distribution. The SDK it depends
+# on, biffo-plugin-sdk, has its own release path upstream —
+# biffo-template's .github/workflows/publish-sdk.yml, triggered by an
+# `sdk-v*` tag — and its own independent semver. See README.md's
+# "biffo-plugin-sdk dependency" section for what that means for `uv sync`
+# before the SDK's first release lands.
+#
+# Prefer PyPI Trusted Publishing (OIDC) over a long-lived PYPI_API_TOKEN
+# when you set this up: it needs no stored secret to rotate or leak. The
+# `id-token: write` permission below is already in place for it, and
+# publish-sdk.yml upstream is a worked example.
+#
+# biffo-template does not use semantic-release anywhere else in the
+# monorepo (its own root has no release.yml — checked before writing this;
+# versioning there is manual) so there's no existing in-repo pattern to
+# follow. python-semantic-release is used here as the standard tool for a
+# single, independently-versioned Python package driven by Conventional
+# Commits (which this monorepo's own commitlint config already enforces on
+# every commit message, including in this plugin repo once forked).
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: write
+  id-token: write # required for PyPI trusted publishing
+
+env:
+  PYTHON_VERSION: '3.13'
+
+jobs:
+  release:
+    name: Build, Version & Publish
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/biffo-plugin-example/
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - run: uv sync --all-groups
+
+      # Full CI gate re-run on the tag, not just a build — a tag push must
+      # be at least as strict as a merged PR before anything is published.
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pyright
+      - run: uv run pytest --cov
+
+      - name: Determine version from tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Verify pyproject.toml version matches tag
+        run: |
+          project_version=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$project_version" != "${{ steps.version.outputs.version }}" ]; then
+            echo "::error::pyproject.toml version ($project_version) does not match tag ${GITHUB_REF_NAME}"
+            exit 1
+          fi
+
+      - name: Install python-semantic-release
+        run: uv tool install python-semantic-release
+
+      - name: Generate release notes
+        run: semantic-release changelog
+
+      - name: Build distribution
+        run: uv build
+
+      # PYPI PUBLISH — see the file-level comment above. This step is real
+      # and will run on every `v*` tag push, but has no credentials
+      # configured yet anywhere in the plugin ecosystem (this template, the
+      # SDK, or the RBAC reference plugin) and is expected to fail here
+      # until a PyPI project + trusted publisher (or PYPI_API_TOKEN) is set
+      # up for this specific plugin package.
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # Prefer PyPI's trusted publishing (OIDC, via the `id-token: write`
+          # permission above) over a long-lived API token where possible —
+          # configure a trusted publisher for this repo at
+          # https://pypi.org/manage/project/<name>/settings/publishing/
+          # once the project exists. Fall back to `password:
+          # ${{ secrets.PYPI_API_TOKEN }}` if trusted publishing isn't set
+          # up for this project yet.
+          skip-existing: true
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*

package/_skeletons/plugin-template/README.md

@@ -0,0 +1,232 @@
+# Biffo Plugin Repository Template
+
+> **This is a skeleton, not a live repository.** It lives at
+> `_skeletons/plugin-template/` inside the `biffo-template` monorepo — the
+> same pattern `_skeletons/registry/` already uses for the plugin registry
+> (see that directory's `README.md`). Nothing in here runs as part of
+> biffo-template's own CI/CD, and this directory is **not** a member of the
+> monorepo's pnpm or uv workspace (check `pnpm-workspace.yaml` and the root
+> `pyproject.toml`'s `[tool.uv.workspace]` — neither lists `_skeletons/`).
+> It exists to be **copied into a brand-new GitHub repository** when someone
+> creates a Biffo plugin, per [ADR-0003](../../docs/ADR/0003-plugin-system-and-marketplace.md)
+> section 2 ("Plugin Repository Structure"). No such repository
+> (`keiranholloway/biffo-plugin-template` or otherwise) has actually been
+> created — that was an explicit decision for this issue (#26): build the
+> skeleton here, don't stand up a real external repo, so it can be reviewed
+> and iterated on like any other code change in this monorepo.
+>
+> To use it: copy this entire directory's contents (minus this note) into a
+> new repository, rename `example_plugin` throughout to your plugin's name,
+> replace `biffo.plugin.json` with your own manifest, and follow the setup
+> steps below.
+
+## What's here
+
+```
+plugin-template/
+├── .github/workflows/
+│   ├── ci.yml              # lint, typecheck, test, manifest validation, security scans — runs on PR
+│   └── release.yml         # semantic-release + PyPI publish — runs on `v*` tag push
+├── biffo.plugin.json        # example manifest: one table, four generic-CRUD routes
+├── registry-schema.json     # vendored copy of the registry's manifest JSON Schema (see below)
+├── pyproject.toml           # depends on biffo-plugin-sdk
+├── terraform/               # the plugin's own infra — Lambda, EventBridge subscription, Core API IAM
+│   ├── main.tf
+│   ├── variables.tf
+│   ├── outputs.tf
+│   └── README.md
+├── src/example_plugin/
+│   ├── __init__.py
+│   ├── manifest.py          # path to biffo.plugin.json
+│   ├── plugin.py            # ExamplePlugin(BiffoPluginBase) — the reference implementation
+│   └── main.py               # Lambda entrypoint dispatching EventBridge events
+└── tests/
+    ├── conftest.py
+    ├── fakes.py              # in-memory fake of the Core API's generic CRUD routes
+    └── test_example_plugin.py
+```
+
+This is the canonical plugin shape: the `BiffoPluginBase` subclass, the
+`src/<name>/{plugin.py, main.py}` layout, the manifest, the `terraform/`
+module, and the fake-Core-API test pattern.
+
+The working first-party example to read alongside it is the **orchestration
+engine** (`services/_plugins/orchestrator/` in the biffo-template monorepo) — same base
+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`
+seed, one `@subscribe` handler.
+
+> 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)
+> (authorization is a Core concern, not a plugin) and no longer exists.
+
+## Standalone repo, not a monorepo package
+
+Unlike biffo-template's own in-monorepo plugins (e.g. `services/_plugins/orchestrator/`,
+a uv workspace member that resolves `biffo-plugin-sdk` from the workspace and
+so needs no `[build-system]` of its own), this template's `pyproject.toml` **does** declare
+`[build-system]` (hatchling) because it's meant to live in its own
+repository with its own independent `uv sync` / `uv.lock`, not inside
+biffo-template's workspace. Once copied out, `uv sync && uv run pytest`
+works standalone with no dependency on the rest of biffo-template.
+
+## The `biffo-plugin-sdk` dependency: PyPI pin, pending the first release
+
+`pyproject.toml` declares:
+
+```toml
+dependencies = [
+  "biffo-plugin-sdk>=1.0,<2.0",
+  ...
+]
+```
+
+This is a **PyPI-style version pin**, and it is the correct end state: the
+SDK is versioned `1.0.0` and biffo-template's
+[`.github/workflows/publish-sdk.yml`](https://github.com/keiranholloway/biffo-template/blob/main/.github/workflows/publish-sdk.yml)
+builds and publishes it to PyPI (via Trusted Publishing) on a pushed
+`sdk-v*` tag. `>=1.0,<2.0` matches the `"biffo-plugin-sdk": "^1.0"` that
+`biffo.plugin.json` declares, and the SDK carries its own independent
+semver — it is **not** tied to the template's `core.version`, so a major
+bump here means the plugin API broke and nothing else.
+
+**Ordering caveat.** The release _pipeline_ exists; the _release_ does not
+yet. `biffo-plugin-sdk` has never been uploaded — the PyPI project is
+unregistered until the owner configures the Trusted Publisher and pushes
+`sdk-v1.0.0`. Until that happens, `uv sync` in a freshly-copied plugin repo
+still cannot resolve this dependency, and you need one of the two local
+overrides below. Once 1.0.0 is live, **delete the override** — the
+`dependencies` entry above already points at the real thing.
+
+Two ways to make local development work before that happens:
+
+1. **Path dependency** (if developing inside a biffo-template checkout,
+   e.g. for a plugin you plan to upstream into `services/`): add
+   ```toml
+   [tool.uv.sources]
+   biffo-plugin-sdk = { path = "../../packages/python-sdk", editable = true }
+   ```
+2. **Git dependency** (developing this plugin as a genuinely separate repo
+   against an unpublished SDK):
+   ```toml
+   [tool.uv.sources]
+   biffo-plugin-sdk = { git = "https://github.com/keiranholloway/biffo-template", subdirectory = "packages/python-sdk" }
+   ```
+
+Either override goes in `[tool.uv.sources]` only — the PyPI-style
+`dependencies` entry above stays as-is, so removing the override is the
+only change needed once the SDK actually ships to PyPI.
+
+## Manifest validation: why CI doesn't hard-gate on `registry-schema.json`
+
+`ci.yml`'s `validate-manifest` job runs two checks:
+
+1. **Authoritative, blocking**: `biffo_plugin_sdk.plugin.load_manifest()` —
+   the real Pydantic model the SDK, the Core API's
+   `discover_plugin_manifests()`, and `biffo plugin install` all actually
+   validate a manifest against.
+2. **Advisory, non-blocking** (`continue-on-error: true`): the vendored
+   `registry-schema.json` (a copy of `_skeletons/registry/registry-schema.json`
+   as of when this template was written), via
+   `python -m jsonschema -i biffo.plugin.json registry-schema.json`.
+
+These two checks currently **disagree**, and check 2 is expected to fail.
+`registry-schema.json`'s `api_routes` shape predates issue #19's
+declarative table/operation CRUD-synthesis redesign: it still requires a
+free-form `handler` function-name field (this template's manifest has no
+such field — routes are declared as `table`/`operation` pairs instead, per
+the real `RouteDef`/`RouteDefinition` models), and its `path` regex
+(`^/[a-z0-9/_-]+$`) rejects the literal `{`/`}` characters that every
+single-row route (`read`/`update`/`delete`) is required to have in its path
+(e.g. `/widgets/{id}`). This was verified directly, not assumed: running
+`jsonschema` against this template's own example manifest produces six
+errors, all in `api_routes`. `cli/src/lib/plugin-manifest.ts` in
+biffo-template already documents this exact same finding and deliberately
+validates against the real Pydantic/Zod models instead of
+`registry-schema.json` for the same reason.
+
+This template follows that precedent: the manifest you ship must pass
+check 1 (it's what actually gets enforced at plugin-install and db-init
+time); check 2 is kept for visibility, so a future correction of
+`registry-schema.json` upstream is easy to notice (it'll start passing) but
+never blocks your CI in the meantime. If `registry-schema.json` is
+corrected, remove this note and consider making check 2 blocking too.
+
+## Contribution guidelines
+
+- **Conventional Commits.** `feat: ...`, `fix: ...`, `chore: ...`,
+  `docs: ...`, `test: ...`, `refactor: ...`, `perf: ...` — the same types
+  biffo-template's own root `CLAUDE.md` documents. `release.yml`'s
+  changelog generation depends on this.
+- **One plugin, one repo.** Don't vendor unrelated code here — this repo
+  should contain exactly the plugin's manifest, source, tests, and
+  `terraform/`. The plugin's infrastructure lives in `terraform/` at the repo
+  root (ADR-0003 section 2), and **this template ships one** — see
+  [`terraform/README.md`](terraform/). The example plugin does need it: it
+  declares an `event_subscriptions` entry, so without a Lambda and an
+  EventBridge rule that subscription never fires. `biffo plugin install`
+  copies `terraform/` into the user's monorepo at `modules/plugins/<name>/`,
+  and it does so **silently only if the directory exists** — a plugin that
+  deletes it gets a clean install and dead event handlers. A CI guard in
+  biffo-template (`pnpm --filter @biffo/cli check:plugin-terraform`) fails any
+  manifest that declares `event_subscriptions` without a `terraform/`
+  directory; keep both in step.
+- **Every table gets `tenant_id`.** You never declare it yourself — it's
+  auto-injected (ADR-0001). Declaring `id`, `tenant_id`, `created_at`, or
+  `updated_at` in a table's `columns` fails manifest validation.
+- **No database client.** Plugins talk to the Core API over HTTP via the SDK's
+  Core client only (ADR-0002) — never `psycopg2`/`asyncpg`/SQLAlchemy against
+  the database directly. `BiffoPluginBase.api` is a SigV4-signing
+  `SignedCoreClient` by default (ADR-0009); `terraform/` grants the Lambda role
+  `execute-api:Invoke` on `/api/v1/internal/*`, and you must add that role to
+  the Core API's `BIFFO_SERVICE_PRINCIPAL_ARN_ALLOWLIST` — see
+  [`terraform/README.md`](terraform/).
+- **Run the full check suite before opening a PR:**
+  ```bash
+  uv sync --all-groups
+  uv run ruff check .
+  uv run ruff format --check .
+  uv run pyright
+  uv run pytest --cov
+  ```
+
+## Branch protection setup
+
+Once you've created the real repository from this skeleton, protect `main`
+with the **same settings biffo-template's own root repo uses**, codified as
+Terraform in `modules/source-control/github/main.tf`'s
+`github_branch_protection.main` resource in this monorepo — copy that
+module (or these settings) rather than inventing new ones:
+
+| Setting                              | Value                                                                                                                                                                       |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Required status checks               | `strict = true`; contexts: `CI / Lint`, `CI / Type Check`, `CI / Test`, `CI / Validate biffo.plugin.json`, `CI / Secret Scan` (the job names from this repo's own `ci.yml`) |
+| Required approving reviews           | 1                                                                                                                                                                           |
+| Dismiss stale reviews on new commits | Yes                                                                                                                                                                         |
+| Require review from Code Owners      | Yes (add a `.github/CODEOWNERS` file)                                                                                                                                       |
+| Enforce for admins                   | Yes                                                                                                                                                                         |
+| Require linear history               | Yes                                                                                                                                                                         |
+| Allow force pushes                   | No                                                                                                                                                                          |
+| Allow branch deletion                | No                                                                                                                                                                          |
+
+If you manage the new repo with Terraform too (recommended — see this
+monorepo's own "IaC as first-class citizen" convention), use
+`modules/source-control/github/` directly rather than hand-writing the
+equivalent `github_branch_protection` resource. If you're setting this up
+by hand via the GitHub UI instead: **Settings → Branches → Add branch
+protection rule**, pattern `main`, and set each field above to match.
+
+## PyPI publishing
+
+`release.yml` triggers on `v*` tag pushes, re-runs the full CI gate against
+the tagged commit, verifies the tag matches `pyproject.toml`'s
+`project.version`, builds the sdist/wheel, and publishes to PyPI via
+`pypa/gh-action-pypi-publish`. **This publish step will not succeed until a
+real PyPI project exists for this plugin and either a trusted publisher (OIDC)
+or a `PYPI_API_TOKEN` secret is configured** — see `release.yml`'s header
+comment for the full rationale (this is intentional, per issue #26's
+decision to build the release workflow as if publishing were real even
+though no plugin in the ecosystem is on PyPI yet).

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

@@ -0,0 +1,89 @@
+{
+  "name": "example-plugin",
+  "version": "0.1.0",
+  "description": "Reference example plugin shipped with the plugin repository template — a single table with generic list/create/read/delete routes. Replace this manifest with your own plugin's tables and routes.",
+  "author": "Biffo Team",
+  "tags": ["example"],
+  "required_core_version": ">=0.0.0",
+  "tables": [
+    {
+      "name": "example_widgets",
+      "columns": [
+        {
+          "name": "name",
+          "type": "String(100)",
+          "nullable": false,
+          "description": "Widget name."
+        },
+        {
+          "name": "description",
+          "type": "Text",
+          "nullable": true
+        },
+        {
+          "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."
+        }
+      ],
+      "indexes": [
+        {
+          "name": "idx_example_widgets_tenant_name",
+          "columns": ["tenant_id", "name"],
+          "unique": true
+        }
+      ],
+      "permissions": {
+        "list": { "allowed": true },
+        "read": { "allowed": true },
+        "create": { "allowed": true, "required_role": ["example-plugin.admin"] },
+        "delete": { "allowed": true, "required_role": ["example-plugin.admin"] }
+      }
+    }
+  ],
+  "api_routes": [
+    {
+      "method": "GET",
+      "path": "/widgets",
+      "table": "example_widgets",
+      "operation": "list",
+      "description": "List widgets for the caller's tenant."
+    },
+    {
+      "method": "POST",
+      "path": "/widgets",
+      "table": "example_widgets",
+      "operation": "create",
+      "description": "Create a widget."
+    },
+    {
+      "method": "GET",
+      "path": "/widgets/{id}",
+      "table": "example_widgets",
+      "operation": "read",
+      "description": "Get a single widget."
+    },
+    {
+      "method": "DELETE",
+      "path": "/widgets/{id}",
+      "table": "example_widgets",
+      "operation": "delete",
+      "description": "Delete a widget."
+    }
+  ],
+  "event_subscriptions": [
+    {
+      "source": "biffo.core",
+      "detail_type": "UserCreated",
+      "description": "Example subscription: logs newly created users. Replace with real logic, or remove this block if your plugin doesn't need it."
+    }
+  ],
+  "ui_components": [
+    { "type": "nav-link", "label": "Example Plugin", "path": "/admin/example-plugin" },
+    { "type": "page", "label": "Widgets", "path": "/admin/example-plugin/widgets" }
+  ],
+  "dependencies": {
+    "biffo-plugin-sdk": "^1.0"
+  }
+}

package/_skeletons/plugin-template/pyproject.toml

@@ -0,0 +1,100 @@
+[project]
+name = "biffo-plugin-example"
+version = "0.1.0"
+description = "Example Biffo plugin — replace this with your own plugin's name and description"
+requires-python = ">=3.13"
+dependencies = [
+  # biffo-plugin-sdk has a real release path as of biffo-template's
+  # .github/workflows/publish-sdk.yml: the package is versioned 1.0.0 and
+  # publishes to PyPI (via Trusted Publishing) when an `sdk-v*` tag is
+  # pushed. This pin is therefore the *correct end state* and is left as-is.
+  #
+  # ORDERING: the pin only resolves once the owner has actually pushed
+  # `sdk-v1.0.0` and PyPI has the release. Until that first publish,
+  # `uv sync` in a freshly-copied plugin repo cannot resolve it — the same
+  # as before this comment was written, so nothing regressed here; what
+  # changed is that the fix is now one tag push away rather than unbuilt.
+  # Deliberately NOT worked around with a git/path source in the committed
+  # file: baking one in would mean every plugin repo forked from this
+  # skeleton silently keeps building against a moving git ref long after
+  # the real release exists. Use a local `[tool.uv.sources]` override until
+  # then — see the README's "biffo-plugin-sdk dependency" section, which
+  # documents both options and says which to delete once 1.0.0 is live.
+  "biffo-plugin-sdk>=1.0,<2.0",
+  "aws-lambda-powertools[tracer]>=3.4.0",
+  "httpx>=0.28.1",
+]
+
+[dependency-groups]
+dev = [
+  "pytest>=8.3.4",
+  "pytest-asyncio>=0.25.2",
+  "pytest-cov>=6.0.0",
+  "ruff>=0.8.0",
+  "pyright>=1.1.0",
+  "jsonschema>=4.23.0",
+  "pip-audit>=2.7.3",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+# Explicit rather than relying on hatchling's default "package name matches
+# a src/ directory" heuristic — the project name (`biffo-plugin-example`)
+# is a distribution/PyPI name, while `example_plugin` is the importable
+# package name; they don't have to match, and won't once you rename this
+# template's package to your own plugin's name. Update this path when you do.
+packages = ["src/example_plugin"]
+
+[tool.ruff]
+target-version = "py313"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "B", "S", "UP", "ANN"]
+ignore = [
+  "S101", # allow assert in tests
+]
+
+[tool.ruff.lint.per-file-ignores]
+# S101: assert is the normal pytest idiom. ANN: test functions don't need
+# return-type annotations. S106: fakes.py's mock BiffoAPIClient(token=...)
+# is a fixed test fixture value, not a real credential.
+"tests/**/*.py" = ["S101", "ANN", "S106"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.pyright]
+pythonVersion = "3.13"
+typeCheckingMode = "standard"
+venvPath = "."
+venv = ".venv"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+asyncio_mode = "auto"
+
+[tool.coverage.run]
+source = ["src"]
+omit = ["*/tests/*"]
+
+# python-semantic-release config for release.yml. This repo does not use
+# semantic-release to *create* tags (unlike its most common setup) — it's
+# triggered by an already-pushed `v*` tag instead (see release.yml's header
+# comment), so only `version_toml` (for the tag/pyproject.toml consistency
+# check) and changelog generation are used; `semantic-release version`'s own
+# commit/tag/push behavior is never invoked in CI.
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+branch = "main"
+build_command = "uv build"
+
+[tool.semantic_release.changelog]
+changelog_file = "CHANGELOG.md"