@biffo/cli 0.38.0 → 0.41.0

package/_skeletons/registry/registry-schema.json

@@ -0,0 +1,294 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Biffo Plugin Manifest",
+  "description": "Schema for biffo.plugin.json — declares what a plugin provides and needs.",
+  "type": "object",
+  "required": ["name", "version", "tables", "api_routes", "ui_components"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Unique plugin slug (lowercase, kebab-case)."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semver version of this plugin release."
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "Human-readable summary shown in the marketplace."
+    },
+    "author": {
+      "type": "string",
+      "default": "Biffo Team",
+      "description": "Publisher name."
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Categorisation tags for filtering/search."
+    },
+    "required_core_version": {
+      "type": "string",
+      "default": ">=0.0.0",
+      "description": "Minimum Biffo core version (npm-style range)."
+    },
+    "tables": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*$",
+            "description": "PostgreSQL table name (snake_case)."
+          },
+          "columns": {
+            "type": "array",
+            "description": "Additional columns beyond id/tenant_id/created_at/updated_at, which are auto-injected on every table per ADR-0001 and must NOT be declared here — doing so fails validation (ColumnDefinition/PluginTableDefinition in services/api/src/api/models/plugin_table.py).",
+            "items": {
+              "type": "object",
+              "required": ["name", "type"],
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "not": { "enum": ["id", "tenant_id", "created_at", "updated_at"] },
+                  "description": "Column name. The names id, tenant_id, created_at, and updated_at are reserved (auto-injected) and rejected here."
+                },
+                "type": {
+                  "type": "string",
+                  "pattern": "^(String|Integer|Text|Boolean|Float|DateTime)(\\(.*\\))?$",
+                  "description": "SQLAlchemy column type constructor string, e.g. 'String(255)', 'Integer', or 'DateTime(timezone=True)'. Must be one of the base types plugin_table.py's _TYPE_MAP resolves (String, Integer, Text, Boolean, Float, DateTime) — anything else silently falls back to String, so this schema rejects it up front rather than allowing a PostgreSQL-style type name (e.g. UUID, TIMESTAMP) that looks valid but isn't."
+                },
+                "primary_key": {
+                  "type": "boolean",
+                  "default": false,
+                  "description": "Whether this is the primary key."
+                },
+                "nullable": {
+                  "type": "boolean",
+                  "default": false,
+                  "description": "Whether NULL values are allowed. Defaults to false (NOT NULL)."
+                },
+                "index": {
+                  "type": "boolean",
+                  "default": false,
+                  "description": "Create a database index on this column."
+                },
+                "default": { "type": "string", "description": "SQL default value expression." },
+                "description": {
+                  "type": "string",
+                  "default": "",
+                  "description": "Human-readable column description."
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "indexes": {
+            "type": "array",
+            "description": "Explicit (optionally multi-column or unique) indexes on the table, beyond any single-column indexes already requested via a column's index: true.",
+            "items": {
+              "type": "object",
+              "required": ["name", "columns"],
+              "properties": {
+                "name": { "type": "string", "description": "Index name in the database." },
+                "columns": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "minItems": 1,
+                  "description": "Column names included in the index."
+                },
+                "unique": {
+                  "type": "boolean",
+                  "default": false,
+                  "description": "Whether the index enforces uniqueness."
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "permissions": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "Declarative per-operation generic-CRUD permissions (ADR-0004; TablePermissions in services/api/src/api/models/plugin_table.py). Default-deny: an absent permissions block, an absent operation key, or an operation with allowed:false ALL make the table invisible to the generic CRUD layer for that operation. required_role is an any-of allow-list matched against the caller's roles (cognito:groups); an empty list means any authenticated caller. Tenant scoping (ADR-0001) is always applied and is deliberately not configurable here. Only the five operation keys below are permitted.",
+            "properties": {
+              "list": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "allowed": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Whether the generic CRUD layer exposes this operation at all."
+                  },
+                  "required_role": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "default": [],
+                    "description": "Any-of role allow-list; empty means any authenticated caller."
+                  }
+                }
+              },
+              "read": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "allowed": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Whether the generic CRUD layer exposes this operation at all."
+                  },
+                  "required_role": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "default": [],
+                    "description": "Any-of role allow-list; empty means any authenticated caller."
+                  }
+                }
+              },
+              "create": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "allowed": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Whether the generic CRUD layer exposes this operation at all."
+                  },
+                  "required_role": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "default": [],
+                    "description": "Any-of role allow-list; empty means any authenticated caller."
+                  }
+                }
+              },
+              "update": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "allowed": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Whether the generic CRUD layer exposes this operation at all."
+                  },
+                  "required_role": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "default": [],
+                    "description": "Any-of role allow-list; empty means any authenticated caller."
+                  }
+                }
+              },
+              "delete": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "allowed": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Whether the generic CRUD layer exposes this operation at all."
+                  },
+                  "required_role": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "default": [],
+                    "description": "Any-of role allow-list; empty means any authenticated caller."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "additionalProperties": false
+      },
+      "description": "Database tables the plugin creates via Alembic migrations."
+    },
+    "api_routes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["method", "path", "table", "operation"],
+        "properties": {
+          "method": {
+            "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"],
+            "description": "HTTP method. Must be compatible with `operation` (list/read=GET, create=POST, update=PUT/PATCH, delete=DELETE) — see plugin_route.py's _OPERATION_METHODS."
+          },
+          "path": {
+            "type": "string",
+            "pattern": "^/[a-zA-Z0-9/_{}-]+$",
+            "description": "Path relative to the plugin's mount point (/api/v1/plugins/<name>), e.g. '/widgets' or '/widgets/{id}'. Must start with '/'. Single-row operations (read/update/delete) address a row via an '{id}' path parameter; collection operations (list/create) must not."
+          },
+          "table": {
+            "type": "string",
+            "description": "Name of a table declared in this manifest's `tables` that this route exposes. A route cannot reference another plugin's table (RouteDefinition / parse_plugin_routes_from_manifest in services/api/src/api/models/plugin_route.py)."
+          },
+          "operation": {
+            "enum": ["list", "read", "create", "update", "delete"],
+            "description": "Generic CRUD operation the Core API synthesizes for this route against `table`, scoped to the caller's tenant_id (ADR-0001). A plugin manifest cannot ship executable handler code the Core API imports and runs (ADR-0002); routes are declarative (issue #19)."
+          },
+          "description": { "type": "string" }
+        }
+      },
+      "description": "Declarative generic-CRUD routes the Core API synthesizes against this plugin's own tables (issue #19 / ADR-0002), mounted under /api/v1/plugins/<name>."
+    },
+    "event_subscriptions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["detail_type"],
+        "properties": {
+          "source": { "type": "string", "default": "biffo.core" },
+          "detail_type": { "type": "string" },
+          "handler": { "type": "string" }
+        }
+      },
+      "description": "EventBridge events the plugin subscribes to."
+    },
+    "infra_modules": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "compute",
+          "storage",
+          "events",
+          "cdn",
+          "database",
+          "auth",
+          "networking",
+          "oidc",
+          "api-gateway"
+        ]
+      },
+      "description": "Terraform module categories the plugin provisions."
+    },
+    "ui_components": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["type", "label", "path"],
+        "properties": {
+          "type": {
+            "enum": ["nav-link", "page", "dashboard-widget", "modal", "dialog"],
+            "description": "UI component type."
+          },
+          "label": { "type": "string" },
+          "path": { "type": "string" },
+          "icon": { "type": "string" },
+          "requires_auth": { "type": "boolean", "default": true }
+        }
+      },
+      "description": "Portal UI elements the plugin adds."
+    },
+    "dependencies": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Python package dependencies (including biffo-plugin-sdk)."
+    }
+  },
+  "additionalProperties": false
+}

package/_skeletons/sibling-template/.github/renovate.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:recommended", "security:openssf-scorecard"],
+  "schedule": ["before 6am on Monday"],
+  "timezone": "UTC",
+  "prConcurrentLimit": 5,
+  "prHourlyLimit": 2,
+  "automerge": false,
+  "labels": ["dependencies"],
+  "packageRules": [
+    {
+      "matchUpdateTypes": ["patch"],
+      "matchDepTypes": ["devDependencies"],
+      "automerge": true
+    },
+    {
+      "matchManagers": ["terraform"],
+      "groupName": "terraform providers",
+      "schedule": ["before 6am on the first day of the month"]
+    },
+    {
+      "matchManagers": ["pip_requirements", "pyproject"],
+      "groupName": "python dependencies"
+    },
+    {
+      "matchPackageNames": ["next", "react", "react-dom"],
+      "groupName": "Next.js / React"
+    },
+    {
+      "matchDepTypes": ["action"],
+      "pinDigests": true
+    }
+  ],
+  "vulnerabilityAlerts": {
+    "labels": ["security"],
+    "automerge": true
+  }
+}

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

@@ -0,0 +1,185 @@
+# Scaled down from biffo-template's own root .github/workflows/ci.yml for a
+# single sibling app (ADR-0007): one frontend package (apps/frontend), one
+# backend service (services/api), one infra/ dir — no monorepo/Turborepo
+# filtering needed since there's exactly one of each. Jobs are consolidated by
+# toolchain (one JS job, one Python job) rather than one per check: GitHub bills
+# each job's wall time rounded up to a full minute and re-installs deps per job,
+# so a dozen sub-minute jobs are wasteful. Job *names* below match the core
+# project's consolidated CI — `biffo sibling create` configures this repo's
+# branch protection with that same status-check list (see
+# cli/src/adapters/source-control/github/index.ts's DEFAULT_STATUS_CHECKS).
+name: CI
+
+on:
+  push:
+    branches: [main, dev, staging]
+  pull_request:
+    branches: [main, dev, staging]
+  # Manual re-run, matching the core project's CI. Without this there is no way
+  # to trigger CI on a protected branch without pushing to it — and a sibling
+  # repo has the same branch protection, so the same recovery gap. See #293.
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  NODE_VERSION: '22'
+  PYTHON_VERSION: '3.13'
+
+jobs:
+  js:
+    # This job also runs a Build step. The name is deliberately NOT extended to
+    # say so: it is a required status check context, matched by string against
+    # DEFAULT_STATUS_CHECKS and against the branch protection already written
+    # onto every sibling repo created so far. Renaming it would leave those
+    # repos waiting forever on a context nothing reports.
+    name: JS (lint, types, test, audit)
+    runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-latest' }}
+    defaults:
+      run:
+        working-directory: apps/frontend
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: pnpm
+          cache-dependency-path: apps/frontend/pnpm-lock.yaml
+      - run: pnpm install --frozen-lockfile
+      # Check steps use `if: ${{ !cancelled() }}` so a failure in one still runs
+      # the rest — every failure surfaces in a single run, not just the first.
+      - name: Lint
+        if: ${{ !cancelled() }}
+        run: pnpm run lint
+      - name: Type check
+        if: ${{ !cancelled() }}
+        run: pnpm run typecheck
+      - name: Test
+        if: ${{ !cancelled() }}
+        run: pnpm run test
+      # Deliberately run with NO NEXT_PUBLIC_CORE_COGNITO_* in scope (issue
+      # #286). `next build` prerenders `/`, which imports src/lib/auth.ts; when
+      # that module built its Cognito pool eagerly the build blew up on any
+      # machine without the real pool ids exported, and nothing in CI caught it
+      # — the first person to find out was whoever had just scaffolded the
+      # sibling, debugging template code they did not write. A sibling's build
+      # must not need auth credentials, so this step is the assertion of that.
+      # Provide the real values in deploy.yml, where they are inlined into the
+      # artifact that actually ships.
+      - name: Build
+        if: ${{ !cancelled() }}
+        run: pnpm run build
+      - name: Dependency audit
+        if: ${{ !cancelled() }}
+        run: pnpm audit --audit-level=high
+
+  python:
+    name: Python (lint, types, test, security)
+    runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-latest' }}
+    defaults:
+      run:
+        working-directory: services/api
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --all-groups
+      - name: Lint
+        if: ${{ !cancelled() }}
+        run: uv run ruff check .
+      - name: Format check
+        if: ${{ !cancelled() }}
+        run: uv run ruff format --check .
+      - name: Type check
+        if: ${{ !cancelled() }}
+        run: uv run pyright
+      - name: Test
+        if: ${{ !cancelled() }}
+        run: uv run pytest --cov --cov-report=xml
+      - name: Coverage upload
+        if: ${{ !cancelled() }}
+        uses: codecov/codecov-action@v5
+        with:
+          files: services/api/coverage.xml
+      - name: SAST (Bandit)
+        if: ${{ !cancelled() }}
+        run: uv run bandit -r src/ -ll --format json -o bandit-report.json
+      - name: Upload Bandit report
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: bandit-report
+          path: services/api/bandit-report.json
+      - name: Dependency audit
+        if: ${{ !cancelled() }}
+        run: uv run pip-audit
+
+  security-secrets:
+    name: Secret Scan
+    runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-latest' }}
+    permissions:
+      contents: read
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          fetch-depth: 0
+      # gitleaks/gitleaks-action@v2 requires a paid GITLEAKS_LICENSE for
+      # organization-owned repos (tabsii-com), which isn't provisioned here.
+      # Install the free, open-source gitleaks CLI directly instead.
+      - name: Install gitleaks
+        run: |
+          curl -sSfL -o gitleaks.tar.gz https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz
+          echo "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb  gitleaks.tar.gz" | sha256sum -c -
+          tar -xzf gitleaks.tar.gz -C /usr/local/bin gitleaks
+          gitleaks version
+      # First pass: scan git history (fetch-depth: 0 above), catching secrets
+      # committed then removed within the same history.
+      #
+      # --log-opts is load-bearing (issue #258). gitleaks' default git log
+      # arguments include `--all`, so with fetch-depth: 0 — which fetches every
+      # remote ref, not just the one being built — the scan covers commits that
+      # live only on *unmerged* branches, letting anyone's open branch redden
+      # the integration branch and every open PR at once. Scoping to HEAD
+      # restricts the scan to commits reachable from the ref under test without
+      # weakening detection: the full reachable history is still walked, so a
+      # secret committed then removed within the branch is still caught, and on
+      # pull_request HEAD is the merge commit so the PR's own commits are in
+      # scope.
+      - name: gitleaks git history scan
+        run: gitleaks detect --redact -v --exit-code=2 --log-opts="--full-history HEAD"
+      # Second pass: scan every file in the working tree (no-git mode).
+      # This mirrors what generated repos see on their first CI run — the initial
+      # commit includes every template file, so secrets in unchanged files would
+      # pass the history scan above but fail there. Running both here closes the gap.
+      - name: gitleaks filesystem scan
+        run: gitleaks detect --no-git --redact -v --exit-code=2
+
+  infra-validate:
+    name: Terraform Validate & Security
+    runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-latest' }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: hashicorp/setup-terraform@v4
+        with:
+          terraform_version: '~> 1.9'
+      - name: Terraform fmt check
+        run: terraform fmt -check -recursive infra/ modules/
+      - name: Validate infra
+        working-directory: infra
+        run: |
+          terraform init -backend=false
+          terraform validate
+      - name: Checkov (Terraform SAST)
+        uses: bridgecrewio/checkov-action@v12
+        with:
+          directory: modules/
+          quiet: true
+          soft_fail: true
+          framework: terraform

package/_skeletons/sibling-template/.github/workflows/codeql.yml

@@ -0,0 +1,56 @@
+name: 'CodeQL'
+
+on:
+  push:
+    branches: [main, dev, staging]
+  pull_request:
+    branches: [main, dev, staging]
+  schedule:
+    # Weekly catch-up scan (Tuesday 05:17 UTC) for issues that land outside
+    # PR review (e.g. direct merges onto a branch).
+    - cron: '17 5 * * 2'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-latest' }}
+    # CodeQL code scanning requires GitHub Advanced Security (GHAS) on private
+    # repos — the analysis runs but the SARIF upload fails without it. So this
+    # is opt-in: enable GHAS on the repo, then set the repo variable
+    # ENABLE_CODE_SCANNING=true. Left dormant (not failing) otherwise.
+    if: vars.ENABLE_CODE_SCANNING == 'true'
+    timeout-minutes: 15
+    permissions:
+      # Required for CodeQL to upload SARIF results.
+      security-events: write
+      contents: read
+      actions: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - language: javascript-typescript
+            build-mode: none
+          - language: python
+            build-mode: none
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+          queries: security-extended
+
+      # autobuild intentionally omitted (build-mode 'none'):
+      # - the frontend (apps/frontend) is TypeScript that CodeQL analyses
+      #   directly, no build required.
+      # - the sibling's Python (services/api) has no build step CodeQL needs.
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: '/language:${{ matrix.language }}'