@biffo/cli 0.38.0 → 0.41.0

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

@@ -0,0 +1,219 @@
+# Mirrors the core project's deploy-infra.yml + deploy-app.yml shape, but
+# combined into one workflow with one job per phase (not one job pair PER
+# environment, unlike the core project) — this repo is small enough that a
+# single dynamic environment mapping (branch -> GitHub Environment) covers
+# dev/staging/prod without tripling the job definitions. Each GitHub
+# Environment (dev/staging/prod) still gets its own vars/secrets/required
+# reviewers exactly as `biffo sibling create` configures via
+# GitHubAdapter.createEnvironments — same governance, less duplicated YAML.
+name: Deploy
+
+on:
+  push:
+    branches: [dev, staging, main]
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: Target environment
+        required: true
+        type: choice
+        options: [dev, staging, prod]
+
+# Never cancel-in-progress here (unlike ci.yml) — this workflow runs
+# `terraform apply` and ships application code. A second trigger for the
+# same branch (e.g. a push landing right after a manual re-run) queues
+# behind the first instead of running alongside it or cancelling a live
+# apply mid-flight.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  id-token: write
+  contents: read
+
+env:
+  NODE_VERSION: '22'
+  TERRAFORM_VERSION: '~> 1.9'
+
+jobs:
+  resolve-environment:
+    name: Resolve target environment
+    runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-latest' }}
+    outputs:
+      environment: ${{ steps.resolve.outputs.environment }}
+    steps:
+      - id: resolve
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "environment=${{ inputs.environment }}" >> "$GITHUB_OUTPUT"
+          elif [ "${{ github.ref_name }}" = "main" ]; then
+            echo "environment=prod" >> "$GITHUB_OUTPUT"
+          else
+            echo "environment=${{ github.ref_name }}" >> "$GITHUB_OUTPUT"
+          fi
+
+  deploy-infra:
+    name: Deploy infra
+    needs: resolve-environment
+    runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-latest' }}
+    environment: ${{ needs.resolve-environment.outputs.environment }}
+    if: vars.SIBLING_DEPLOY_ENABLED == 'true'
+    defaults:
+      run:
+        working-directory: infra
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: hashicorp/setup-terraform@v4
+        with:
+          terraform_version: ${{ env.TERRAFORM_VERSION }}
+      - uses: aws-actions/configure-aws-credentials@v6
+        with:
+          role-to-assume: ${{ secrets.SIBLING_OIDC_ROLE_ARN }}
+          aws-region: ${{ vars.AWS_REGION || 'us-east-1' }}
+      - name: Generate backend config
+        run: |
+          cat > backend.hcl << 'EOF'
+          bucket = "${{ vars.TF_STATE_BUCKET }}"
+          key    = "${{ needs.resolve-environment.outputs.environment }}/terraform.tfstate"
+          region = "${{ vars.AWS_REGION || 'us-east-1' }}"
+          EOF
+      - run: terraform init -backend-config=backend.hcl
+      - run: terraform apply -auto-approve
+        env:
+          TF_VAR_project_name: ${{ vars.PROJECT_NAME }}
+          TF_VAR_environment: ${{ needs.resolve-environment.outputs.environment }}
+          TF_VAR_aws_region: ${{ vars.AWS_REGION || 'us-east-1' }}
+          TF_VAR_core_cognito_user_pool_id: ${{ vars.CORE_COGNITO_USER_POOL_ID }}
+          TF_VAR_core_cognito_client_id: ${{ vars.CORE_COGNITO_CLIENT_ID }}
+          TF_VAR_core_api_url: ${{ vars.CORE_API_URL }}
+          TF_VAR_core_portal_url: ${{ vars.CORE_PORTAL_URL }}
+          TF_VAR_cors_origins: ${{ vars.CORS_ORIGINS_JSON || '["http://localhost:3000"]' }}
+          # Empty until the core project's registration PR has merged — see
+          # variables.tf. Re-run this workflow (workflow_dispatch) once
+          # that PR merges and this var is set, to add the bucket policy.
+          TF_VAR_parent_cloudfront_distribution_arn: ${{ vars.PARENT_CLOUDFRONT_DISTRIBUTION_ARN || '' }}
+      - name: Export outputs to GitHub Actions variables
+        env:
+          GH_TOKEN: ${{ secrets.SIBLING_GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          gh variable set API_URL \
+            --body "$(terraform output -raw api_url)" \
+            --env "${{ needs.resolve-environment.outputs.environment }}"
+          gh variable set SITE_BUCKET_NAME \
+            --body "$(terraform output -raw site_bucket_name)" \
+            --env "${{ needs.resolve-environment.outputs.environment }}"
+          gh variable set SITE_BUCKET_REGIONAL_DOMAIN \
+            --body "$(terraform output -raw site_bucket_regional_domain)" \
+            --env "${{ needs.resolve-environment.outputs.environment }}"
+          gh variable set LAMBDA_FUNCTION_NAME \
+            --body "$(terraform output -raw lambda_function_name)" \
+            --env "${{ needs.resolve-environment.outputs.environment }}"
+
+  deploy-app:
+    name: Deploy app
+    needs: [resolve-environment, deploy-infra]
+    runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-latest' }}
+    environment: ${{ needs.resolve-environment.outputs.environment }}
+    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
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Install frontend deps
+        working-directory: apps/frontend
+        run: pnpm install --frozen-lockfile
+      - name: Build frontend
+        working-directory: apps/frontend
+        env:
+          NEXT_PUBLIC_SIBLING_NAME: ${{ vars.PROJECT_NAME }}
+          # The ROOT application sibling has an EMPTY PATH_PREFIX (issue #306):
+          # it serves "/" and takes the core distribution's default cache
+          # behaviour. `/${{ vars.PATH_PREFIX }}` would yield "/" for it, and
+          # Next.js refuses to build with a basePath of "/" ("has to be a path
+          # starting with /, but not ending with one"). Empty string is the
+          # correct value there, so the prefix is only prepended when there is
+          # one.
+          NEXT_PUBLIC_SIBLING_PATH_PREFIX: ${{ vars.PATH_PREFIX && format('/{0}', vars.PATH_PREFIX) || '' }}
+          NEXT_PUBLIC_BASE_PATH: ${{ vars.PATH_PREFIX && format('/{0}', vars.PATH_PREFIX) || '' }}
+          NEXT_PUBLIC_CORE_PORTAL_URL: ${{ vars.CORE_PORTAL_URL }}
+          NEXT_PUBLIC_CORE_COGNITO_USER_POOL_ID: ${{ vars.CORE_COGNITO_USER_POOL_ID }}
+          NEXT_PUBLIC_CORE_COGNITO_CLIENT_ID: ${{ vars.CORE_COGNITO_CLIENT_ID }}
+          NEXT_PUBLIC_API_URL: ${{ vars.API_URL }}
+        run: pnpm run build
+      - uses: aws-actions/configure-aws-credentials@v6
+        with:
+          role-to-assume: ${{ secrets.SIBLING_OIDC_ROLE_ARN }}
+          aws-region: ${{ vars.AWS_REGION || 'us-east-1' }}
+      - name: Sync frontend to S3
+        env:
+          PATH_PREFIX: ${{ vars.PATH_PREFIX }}
+          SITE_BUCKET_NAME: ${{ vars.SITE_BUCKET_NAME }}
+        run: |
+          # Uploaded under a key prefix matching this sibling's own path
+          # segment (basePath), because the core project's CloudFront
+          # forwards the full request URI (e.g. /<name>/foo.html) straight
+          # through to this bucket with no prefix stripping.
+          #
+          # ${VAR:+...} — expand to "<prefix>/" only when the prefix is
+          # non-empty. The ROOT application sibling (issue #306) has an empty
+          # prefix and syncs to the bucket root; the naive "$BUCKET/$PREFIX/"
+          # would give "s3://bucket//", whose keys all begin with a literal
+          # slash and match no request CloudFront ever forwards.
+          DEST="s3://${SITE_BUCKET_NAME}/${PATH_PREFIX:+${PATH_PREFIX}/}"
+          aws s3 sync apps/frontend/out/ "$DEST" \
+            --delete \
+            --cache-control "public, max-age=31536000, immutable" \
+            --exclude "*.html"
+          aws s3 sync apps/frontend/out/ "$DEST" \
+            --delete \
+            --cache-control "no-cache" \
+            --include "*.html"
+      - name: Invalidate the core project's CloudFront path
+        if: vars.PARENT_CLOUDFRONT_DISTRIBUTION_ID != ''
+        env:
+          PATH_PREFIX: ${{ vars.PATH_PREFIX }}
+          DISTRIBUTION_ID: ${{ vars.PARENT_CLOUDFRONT_DISTRIBUTION_ID }}
+        run: |
+          # "/*" for the root sibling, "/<prefix>/*" otherwise.
+          aws cloudfront create-invalidation \
+            --distribution-id "$DISTRIBUTION_ID" \
+            --paths "/${PATH_PREFIX:+${PATH_PREFIX}/}*"
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: '3.13'
+      - name: Package and deploy Lambda
+        working-directory: services/api
+        run: |
+          uv export --no-dev --output-file requirements.txt
+          uv pip install -r requirements.txt --target package/
+          cp -r src/ package/
+          cd package && zip -r ../lambda.zip .
+          aws lambda update-function-code \
+            --function-name "${{ vars.LAMBDA_FUNCTION_NAME }}" \
+            --zip-file fileb://../lambda.zip
+      - name: Smoke test the deployed Lambda
+        run: |
+          # Deploy succeeding just means the zip uploaded — it says nothing
+          # about whether the Lambda can actually boot (e.g. a native
+          # dependency built for the wrong Python ABI fails at import time,
+          # not at deploy time). GET /api/v1/health is unauthenticated by
+          # design specifically so this check can hit the real API Gateway
+          # route with no token, proving the Lambda imports and serves a
+          # request end to end, not just that code was uploaded.
+          aws lambda wait function-updated \
+            --function-name "${{ vars.LAMBDA_FUNCTION_NAME }}"
+          if ! curl -sf --retry 5 --retry-delay 3 --retry-all-errors \
+              "${{ vars.API_URL }}/api/v1/health"; then
+            echo "::error::Health check failed after deploy — the Lambda uploaded but isn't serving requests. Check CloudWatch logs for ${{ vars.LAMBDA_FUNCTION_NAME }}."
+            exit 1
+          fi

package/_skeletons/sibling-template/.github/workflows/destroy-infra.yml

@@ -0,0 +1,73 @@
+# Counterpart to deploy.yml, and the mechanism `biffo teardown` drives when the
+# core project it belongs to is torn down (issue #306).
+#
+# Without this workflow a sibling's own AWS resources — its S3 site bucket, its
+# Lambda, its API Gateway, its log groups — survive the core project's teardown
+# and keep billing, silently. `biffo teardown` pre-flights every registered
+# sibling for this file and refuses to start if one is missing, rather than
+# discovering it half way through and leaving a partially destroyed instance.
+#
+# Same single-dynamic-environment shape as deploy.yml (one job per phase, not
+# one job per environment), and the TF_VARs below must stay in step with
+# deploy.yml's `terraform apply` — a destroy run with different variables can
+# fail to resolve the very resources it is meant to remove.
+name: Destroy Infrastructure
+
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: Environment to destroy
+        required: true
+        type: choice
+        options: [dev, staging, prod]
+
+permissions:
+  id-token: write
+  contents: read
+
+# Never cancel in flight: a half-run `terraform destroy` is worse than a slow one.
+concurrency:
+  group: ${{ github.workflow }}-${{ inputs.environment }}
+  cancel-in-progress: false
+
+env:
+  TERRAFORM_VERSION: '~> 1.9'
+
+jobs:
+  destroy:
+    name: Destroy (${{ inputs.environment }})
+    runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-latest' }}
+    environment: ${{ inputs.environment }}
+    if: vars.SIBLING_DEPLOY_ENABLED == 'true'
+    defaults:
+      run:
+        working-directory: infra
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: hashicorp/setup-terraform@v4
+        with:
+          terraform_version: ${{ env.TERRAFORM_VERSION }}
+      - uses: aws-actions/configure-aws-credentials@v6
+        with:
+          role-to-assume: ${{ secrets.SIBLING_OIDC_ROLE_ARN }}
+          aws-region: ${{ vars.AWS_REGION || 'us-east-1' }}
+      - name: Generate backend config
+        run: |
+          cat > backend.hcl << 'EOF'
+          bucket = "${{ vars.TF_STATE_BUCKET }}"
+          key    = "${{ inputs.environment }}/terraform.tfstate"
+          region = "${{ vars.AWS_REGION || 'us-east-1' }}"
+          EOF
+      - run: terraform init -backend-config=backend.hcl
+      - run: terraform destroy -auto-approve
+        env:
+          TF_VAR_project_name: ${{ vars.PROJECT_NAME }}
+          TF_VAR_environment: ${{ inputs.environment }}
+          TF_VAR_aws_region: ${{ vars.AWS_REGION || 'us-east-1' }}
+          TF_VAR_core_cognito_user_pool_id: ${{ vars.CORE_COGNITO_USER_POOL_ID }}
+          TF_VAR_core_cognito_client_id: ${{ vars.CORE_COGNITO_CLIENT_ID }}
+          TF_VAR_core_api_url: ${{ vars.CORE_API_URL }}
+          TF_VAR_core_portal_url: ${{ vars.CORE_PORTAL_URL }}
+          TF_VAR_cors_origins: ${{ vars.CORS_ORIGINS_JSON || '["http://localhost:3000"]' }}
+          TF_VAR_parent_cloudfront_distribution_arn: ${{ vars.PARENT_CLOUDFRONT_DISTRIBUTION_ARN || '' }}

package/_skeletons/sibling-template/README.md

@@ -0,0 +1,164 @@
+# Sibling App Template
+
+> **This is a skeleton, not a live repository.** It lives at
+> `_skeletons/sibling-template/` inside `biffo-template` and is not itself
+> deployed or a member of biffo-template's pnpm/uv workspace — check
+> `pnpm-workspace.yaml` (only lists `apps/*`, `packages/*`, `cli`) and the
+> root `pyproject.toml`'s `[tool.uv.workspace]` (only lists `services/*`,
+> `services/_plugins/*`,
+> `packages/python-sdk`); neither lists `_skeletons/`. It exists to be
+> copied into a **brand-new, independent GitHub repository** by
+> `biffo sibling create <name>` (ADR-0007), which pushes this content in as
+> that new repo's first commit and rewrites `biffo.sibling.json` with real
+> values. No such external repo exists yet from this skeleton alone — that's
+> the point of it being a skeleton, not an oversight.
+>
+> To use it manually (outside `biffo sibling create`): copy this directory
+> out, rename the placeholder values in `biffo.sibling.json` and the two
+> `.env.example` files, then follow "Getting started" below.
+
+## What is a "sibling app"?
+
+A sibling is an independently-deployed microservice that still feels like
+part of one product: same login (it shares the **core project's** Cognito
+User Pool and App Client — not its own), same domain
+(`baseurl.com/<sibling-name>/*`, routed via the core project's own
+CloudFront distribution), but its own repo, its own CI/CD, its own AWS
+resources. Per ADR-0002 and ADR-0007, a sibling **never accesses a database
+directly** — the only way it reads or writes core-owned data is by calling
+the core project's own API (`services/api/core_client.py`). This template
+enforces that from the start: there is no `asyncpg`/`sqlalchemy`/`alembic`
+anywhere in `services/api/`, on purpose.
+
+## What's here
+
+```
+apps/frontend/            # Next.js 15 static export — the ONLY page is "<name> - Hello <username>",
+                           #   proving the shared-session SSO works. Copy the portal's own
+                           #   src/lib/auth.ts pattern here almost verbatim (see that file's comments).
+services/api/              # FastAPI + Mangum backend. Verifies the core project's Cognito JWT itself
+                           #   (defense in depth — API Gateway's own JWT authorizer is the first layer).
+                           #   core_client.py is the ONLY sanctioned way to reach core-owned data.
+infra/                     # Single Terraform root (no per-environment subfolders, unlike the core
+                           #   project — this repo is simple enough that one root + a Terraform
+                           #   workspace/backend key per environment is enough). No Cognito pool,
+                           #   no CloudFront distribution: those are the core project's, passed in
+                           #   as plain input variables (core_cognito_user_pool_id, etc.)
+modules/cloud/aws/         # Vendored (copied, not remote-sourced) compute/storage/api-gateway
+                           #   modules — this repo must stay self-contained; a git-sourced shared
+                           #   module would reintroduce the cross-repo-lifecycle coupling ADR-0003
+                           #   already rejected for plugins. Same call, made consistently here.
+.github/workflows/ci.yml   # Same 11 status checks as the core project (see DEFAULT_STATUS_CHECKS
+                           #   in the core project's cli/src/adapters/source-control/github/index.ts)
+.github/workflows/deploy.yml  # infra apply -> frontend build+sync -> Lambda package+deploy, combined
+                           #   into one workflow with a dynamic branch->environment mapping.
+biffo.sibling.json          # This sibling's name, its paired core project's name, its path prefix.
+                           #   Written by `biffo sibling create`; do not hand-edit path_prefix
+                           #   without also updating the core project's siblings.auto.tfvars.json.
+```
+
+## Standalone repo, not a monorepo package
+
+Both `apps/frontend/package.json` and `services/api/pyproject.toml` are
+fully standalone — no `workspace:*` dependencies, no Turborepo, no shared
+`@biffo/eslint-config`/`@biffo/typescript-config` packages (those only exist
+inside the `biffo-template` monorepo). `services/api/pyproject.toml` has its
+own `[build-system]` (hatchling) so `uv sync` works from a bare clone. This
+means `apps/frontend/eslint.config.mjs` and `tsconfig.json` duplicate rules
+the core project's shared packages would otherwise centralise — an
+intentional, small amount of duplication in exchange for this repo never
+needing anything from `biffo-template` at runtime or build time.
+
+`apps/frontend/pnpm-workspace.yaml` exists for the same reason, and is worth
+understanding before you delete it as redundant. `pnpm install` walks _up_ the
+directory tree looking for a workspace root. In a scaffolded sibling repo there
+is nothing above `apps/frontend` to find, so the file is inert. But while this
+skeleton still lives inside `biffo-template` — under `_skeletons/`, excluded
+from that repo's own workspace globs — `pnpm install` run from here would
+otherwise walk all the way up and install **biffo-template's root workspace**
+instead: it prints success against `../../../..`, leaves no `node_modules` here
+at all, and the next command fails for a reason that looks entirely unrelated.
+Declaring this directory a workspace root of its own terminates that walk.
+(A `preinstall` guard cannot help: pnpm never treats an excluded package as
+part of the install, so its lifecycle scripts never run.)
+
+## The build must not need Cognito credentials
+
+`pnpm run build` has to succeed with **no** `NEXT_PUBLIC_CORE_COGNITO_*` set,
+and `.github/workflows/ci.yml` runs it that way on every PR to keep it that
+way. `next build` prerenders `/` in Node, which imports `src/lib/auth.ts`; that
+module therefore constructs its Cognito user pool lazily, on first session
+read, never at module scope (the `CognitoUserPool` constructor throws outright
+when either id is missing). If you add module-scope code that requires real
+core config, the build breaks for everyone who has not exported the pool ids —
+starting with CI. Read config inside the function that needs it.
+
+## The two-phase CDN registration
+
+Registering this sibling on the core project's CloudFront distribution is
+necessarily a two-step handshake, not something this repo's own
+`terraform apply` can complete alone:
+
+1. `biffo sibling create` provisions this sibling's own S3 bucket/Lambda/API
+   Gateway first (`var.parent_cloudfront_distribution_arn` left empty — see
+   `infra/variables.tf` — so the bucket policy step is skipped; there's no
+   distribution ARN to trust yet).
+2. It then opens a PR against the **core project's** repo, appending this
+   sibling's `{ name, bucket_regional_domain }` to
+   `infra/siblings.auto.tfvars.json`. Once a human merges that PR and the
+   core project redeploys, `baseurl.com/<name>/*` starts routing to this
+   sibling's bucket, and the real distribution ARN exists.
+3. Set `parent_cloudfront_distribution_arn` (as `PARENT_CLOUDFRONT_DISTRIBUTION_ARN`,
+   a GitHub Environment variable) and re-run `.github/workflows/deploy.yml`
+   (`workflow_dispatch`) to add the bucket policy in a second apply.
+
+This ordering is a real dependency, not a bug — don't skip step 3 or the
+core project's CloudFront will get an origin it isn't allowed to read from.
+
+## Contribution guidelines
+
+- Conventional Commits (`feat`, `fix`, `chore`, `docs`, `test`, `infra`,
+  `security`, `refactor`, `perf`, `ci`), same as the core project.
+- Keep this repo doing one thing: this sibling's own feature. If you find
+  yourself wanting to read/write another sibling's data, go through the
+  core project's API and an EventBridge subscription, not a direct call.
+- Invariants inherited from the core project (ADR-0001/ADR-0002): every
+  piece of core-owned data this sibling touches is still scoped to
+  `tenant_id` server-side (the core API enforces this, not this repo) — and
+  no database client of any kind belongs in `services/api/`.
+- Before opening a PR:
+  ```bash
+  cd apps/frontend && pnpm install && pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run build
+  cd services/api && uv sync --all-groups && uv run ruff check . && uv run ruff format --check . && uv run pyright && uv run pytest
+  terraform fmt -check -recursive infra/ modules/
+  ```
+
+## Branch protection setup
+
+`biffo sibling create` configures this via the same
+`GitHubAdapter.configureBranchProtection` the core project uses (passing
+this repo's own `statusChecks` list — see that method's third parameter):
+
+| Setting                | Value                                                     |
+| ---------------------- | --------------------------------------------------------- |
+| Required status checks | The 11 jobs in `.github/workflows/ci.yml`, `strict: true` |
+| Required reviews       | 0 (solo-founder default; raise this yourself)             |
+| Dismiss stale reviews  | true                                                      |
+| Enforce for admins     | true                                                      |
+| Linear history         | true                                                      |
+| Allow force pushes     | false                                                     |
+| Allow deletions        | false                                                     |
+
+## Getting started (manual, outside `biffo sibling create`)
+
+1. Rename `biffo.sibling.json`'s `name`/`core_project`/`path_prefix`.
+2. Copy `apps/frontend/.env.example` to `.env.local` and fill in your core
+   project's real Cognito/API values for local dev.
+3. `cd infra && terraform init -backend-config=backend.hcl && terraform apply`
+   (generate `backend.hcl` yourself for local use — CI generates it inline,
+   see `deploy.yml`).
+4. Wire the GitHub Environment variables/secrets `deploy.yml` reads
+   (`CORE_COGNITO_USER_POOL_ID`, `CORE_COGNITO_CLIENT_ID`, `CORE_API_URL`,
+   `CORE_PORTAL_URL`, `SIBLING_OIDC_ROLE_ARN`, `TF_STATE_BUCKET`, etc.).
+5. Open the registration PR against your core project (`infra/siblings.auto.tfvars.json`)
+   yourself, or let `biffo sibling create` do it for you.

package/_skeletons/sibling-template/_gitignore

@@ -0,0 +1,71 @@
+# Dependencies
+node_modules
+.pnpm-store
+
+# Build outputs
+.next
+dist
+out
+next-env.d.ts
+*.tsbuildinfo
+
+# Python
+__pycache__
+*.py[cod]
+*.pyo
+.venv
+.uv
+*.egg-info
+.pytest_cache
+.ruff_cache
+.mypy_cache
+.pyright
+
+# Terraform
+.terraform
+.terraform.lock.hcl
+*.tfstate
+*.tfstate.*
+*.tfstate.backup
+crash.log
+crash.*.log
+override.tf
+override.tf.json
+*_override.tf
+*_override.tf.json
+.terraformrc
+terraform.rc
+tfplan
+backend.hcl
+
+# Biffo local project store — persisted by `biffo sibling create`, read by `biffo deploy`
+.biffo/
+
+# Environment & secrets — never commit these
+.env
+.env.*
+!.env.example
+!.env.test
+*.pem
+*.key
+*.crt
+*.p12
+secrets/
+
+# Editor
+.vscode
+.idea
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# Test coverage
+coverage
+htmlcov
+.coverage

package/_skeletons/sibling-template/apps/frontend/.env.example

@@ -0,0 +1,14 @@
+# Set at Next.js build time (see .github/workflows/deploy.yml) — inlined
+# into the static export, not read at runtime. All values below come from
+# the CORE project, not this sibling's own Terraform (ADR-0007): a sibling
+# has no Cognito pool or CloudFront distribution of its own.
+NEXT_PUBLIC_SIBLING_NAME=example-sibling
+NEXT_PUBLIC_SIBLING_PATH_PREFIX=/example-sibling
+NEXT_PUBLIC_BASE_PATH=/example-sibling
+NEXT_PUBLIC_CORE_PORTAL_URL=https://baseurl.com
+NEXT_PUBLIC_CORE_COGNITO_USER_POOL_ID=us-east-1_XXXXXXXXX
+NEXT_PUBLIC_CORE_COGNITO_CLIENT_ID=XXXXXXXXXXXXXXXXXXXXXXXXXX
+# This sibling's OWN API Gateway endpoint (from `terraform output api_url`),
+# NOT the core project's API — the frontend never calls the core API
+# directly (ADR-0002/ADR-0007).
+NEXT_PUBLIC_API_URL=https://XXXXXXXXXX.execute-api.us-east-1.amazonaws.com

package/_skeletons/sibling-template/apps/frontend/eslint.config.mjs

@@ -0,0 +1,10 @@
+import { FlatCompat } from '@eslint/eslintrc'
+
+const compat = new FlatCompat({ baseDirectory: import.meta.dirname })
+
+const config = [
+  { ignores: ['.next/**', 'next-env.d.ts', 'out/**'] },
+  ...compat.extends('next/core-web-vitals', 'next/typescript'),
+]
+
+export default config

package/_skeletons/sibling-template/apps/frontend/next.config.ts

@@ -0,0 +1,20 @@
+import type { NextConfig } from 'next'
+
+// basePath must match the "<name>" segment CloudFront routes on
+// (baseurl.com/<name>/*, see infra/main.tf's sibling registration) — the
+// parent's CDN forwards the full request URI (e.g. /<name>/foo.html)
+// straight to this sibling's S3 origin with no prefix stripping, so the
+// static export's own asset/link URLs must already include that prefix.
+// Set at build time; see .github/workflows/ci.yml / deploy.yml.
+const basePath = process.env['NEXT_PUBLIC_BASE_PATH'] ?? ''
+
+const nextConfig: NextConfig = {
+  output: 'export',
+  trailingSlash: true,
+  basePath,
+  images: {
+    unoptimized: true,
+  },
+}
+
+export default nextConfig

package/_skeletons/sibling-template/apps/frontend/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "sibling-frontend",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "amazon-cognito-identity-js": "^6.3.12",
+    "next": "^15.1.3",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.2.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^22.10.5",
+    "@types/react": "^19.0.7",
+    "@types/react-dom": "^19.0.3",
+    "@vitejs/plugin-react": "^4.7.0",
+    "eslint": "^9.18.0",
+    "eslint-config-next": "^15.1.3",
+    "jsdom": "^29.1.1",
+    "prettier": "^3.4.2",
+    "typescript": "^5.7.3",
+    "vite": "^6.4.3",
+    "vitest": "^4.1.0"
+  },
+  "pnpm": {
+    "overrides": {
+      "postcss@<8.5.10": ">=8.5.10"
+    }
+  }
+}