# Consumer conventions

These shared actions and workflows are deliberately thin — they assume the
consuming repo follows the FSH conventions below. If a repo diverges, override
the relevant input or keep a local definition for that one piece.

## Repo-wide

- **Org / default branch.** All repos live under `FSHTech` and use `main` as the
  default branch (release, docs, and sibling clones all target `main`).
- **Pin to an exact release tag.** Consumers reference everything at the exact
  `vX.Y.Z` tag release-please cuts (`…@v1.3.0`) — there is no moving major tag.
  Renovate keeps the pins current; bump the tag to adopt a new release.
- **Thin callers.** Each repo keeps its own `.github/workflows/*.yml`, but those
  files only own the `on:` trigger + inputs and delegate to the reusable
  workflows / composite actions here. Job orchestration that is genuinely
  repo-specific (the `lint` job graph) stays local but is *built from* these
  actions.
- **`actions/checkout` first.** Every composite action assumes the repo is
  already checked out and (for lint/test/build actions) the language toolchain
  action has already run.

## Everything runs through `just`

Lint, type-check, test, build and generate all run via `just-run` (`just
<recipe>`). The language-specific part is only the install that runs first
(`setup-python` + `uv-sync`, or `setup-node`). So **every repo exposes its CI
steps as `just` recipes in a root `justfile`** — the canonical names are `lint`,
`type-check`, `coverage-ci` (CI test gate), `docs`, and for app/template repos
`gen` / `bootstrap` / `validate`. This is what lets one generic runner serve
both the Python and the Node repos.

## Python repos (`setup-python` → `uv-sync` → `just-run`, plus `pre-commit`)

- **uv project** with a committed `uv.lock` at the repo root (the
  `setup-python` cache keys on it). Python is pinned to 3.14 unless
  `python-version` is overridden.
- **Dependency groups.** `dev` (tests + general dev) and `lint` (ruff, zuban,
  pre-commit, and anything the local hooks import). Jobs pass these to `uv-sync`
  via `args`: `--group dev --group lint` (lint), `--group lint` (pre-commit's
  default sync), `--group dev` (tests). Monorepos add `--all-packages`.
- **Justfile** with at least `lint`, `type-check`, `coverage-ci` recipes (run by
  `just-run`), and `docs` if the repo publishes Sphinx docs.
- **`.pre-commit-config.yaml`** at the repo root. `ruff` / `ruff-format` are
  skipped by `pre-commit` (the lint job covers them); list any other hooks that
  can't run in CI via the `skip` input (e.g. `js-format`,
  `check-control-blank-lines` when that tree isn't materialised).
- **Coverage** configured in `pyproject.toml`; the `coverage-ci` recipe runs
  `coverage run -m pytest` + a report. DB-backed suites attach a `postgres`
  service in the calling job and pass `DATABASE_URL` via env.

## Node repos (`setup-node` → `just-run`)

- **`.nvmrc`** at the repo root pins the Node version.
- **Yarn Classic (v1).** `setup-node` runs `yarn install --frozen-lockfile`;
  use `cache: yarn` layout and a committed `yarn.lock`.
- **Yarn workspaces** with `@fsh/*` scoped package names.
- **Justfile** exposing the same recipe names (`lint`, `type-check`, `build`,
  `test`) that wrap the underlying `yarn workspace …` calls, so `just-run`
  drives Node the same way it drives Python. (A repo that still calls `yarn`
  directly in its workflow hasn't adopted the runner yet — give it a `justfile`.)
- **`LINT_IMPORT_CYCLES`** is honored by the shared eslint flat-config preset
  (turns on `import/no-cycle`); set it in the `lint` recipe or the job env.

## Sibling deps from CodeArtifact (`codeartifact-login`)

FSH libraries (`fsh-lib`, `codegen`, `codegen-database`, `@fsh/*`) are published
to CodeArtifact and resolved as ordinary pinned dependencies — no cloning. CI
runs `codeartifact-login` (assumes the read role via OIDC, then exports
`UV_INDEX_URL` and writes `~/.netrc` for uv/pip + `~/.npmrc` for `@fsh` npm).
The calling job needs `permissions: id-token: write` and the `CODEARTIFACT_*`
repo variables (provisioned by the infra source-code stack).

**Local-dev editable override.** Repos that want live sibling editing keep
`[tool.uv.sources]` path overrides (`../<repo>`; JS `file:` links) so a local
`uv sync` resolves siblings from the checkout next door. CI sets
`UV_NO_SOURCES=1` (workflow-level `env:`) so it *ignores* those overrides and
resolves the published package from CodeArtifact instead. The committed
`uv.lock` is the registry (no-sources) form — `UV_NO_SOURCES` can't override an
editable entry baked into the lock, so generate it with `uv lock --no-sources`;
a local `uv sync` re-resolves to the editable form (don't commit that).

**`just` modules are the exception.** Recipe modules are vendored from the
`just-packages` git repo by `just-vendor` over per-repo deploy keys
(`DEPLOY_KEY_JUST_PACKAGES`, `DEPLOY_KEY_JUST_PACKAGE_MANAGER`) — there's no
CodeArtifact equivalent for `just` files, so those deploy keys stay.

## PR titles (`pr-title.yml`)

- PR titles follow Conventional Commits. Each repo passes its allowed `scopes`
  (always include `deps`, `ci`, `release`). `requireScope` defaults to false.

## Releases (`release-python.yml`, `release-npm.yml`)

- **release-please** configured in-repo: `release-please-config.json` +
  `.release-please-manifest.json`. Single-package repos emit `release_created`;
  monorepos emit `releases_created` (+ `paths_released` for npm).
- **Optional `RELEASE_TOKEN`** secret (a PAT so release-please PRs re-trigger
  CI); falls back to `GITHUB_TOKEN`. Pass via `secrets: inherit`.
- **CodeArtifact via OIDC** — infra provides these as **repo/org variables**:
  `CODEARTIFACT_PUBLISH_ROLE_ARN`, `CODEARTIFACT_REGION`, `CODEARTIFACT_DOMAIN`,
  `CODEARTIFACT_DOMAIN_OWNER`, and the repo URL
  (`CODEARTIFACT_PYPI_REPOSITORY_URL` for python,
  `CODEARTIFACT_NPM_REPOSITORY_URL` for npm). The publish job requests
  `id-token: write` and assumes the publisher role — no static credentials.
- **Build system.** Python repos build with `uv build` (pyproject
  `build-system`); npm repos build only the buildable `@fsh/*` workspaces (the
  `build-command` input — `@fsh/eslint-config` has no build script and publishes
  source as-is).

## Deploys (`deploy-ecs.yml`)

App repos deploy by calling the reusable `deploy-ecs.yml` workflow with a single
`tier` input (`prod` | `staging`). The thin caller maps branch → tier (`main` →
prod, `staging` → staging) plus a `workflow_dispatch` escape hatch.

- **Mutable branch tags drive deploys.** ECS pins `branch-main` (prod) /
  `branch-staging` (staging), so a deploy is: re-push the tag for each image
  (`ecr-build-push`), run migrations once in the primary region
  (`ecs-run-migration`), then `force-new-deployment` per region (`ecs-deploy`).
  Warm-standby regions additionally gate on `ecr-wait-replication` (ECR
  cross-region replication is async).
- **Infra provides the repo variables**: `DEPLOY_ROLE_ARN` (ECS deploy role,
  restricted to the `main`/`staging` refs), `DEPLOY_ECR_PUSH_ROLE_ARN` (image
  push, any ref), `DEPLOY_ECR_REGISTRY`, `DEPLOY_ECR_REPO_PREFIX`, and a
  `DEPLOY_CONFIG_<TIER>` JSON document per tier (image tag + the per-region
  cluster/service/migrate-task coordinates). Jobs request
  `permissions: id-token: write` — no static credentials.
- **Checkout is a complete build context.** The generated trees (`_generated/`)
  are committed, so the build jobs run no codegen. A repo that gitignores them
  must add a generate step before `ecr-build-push`.
- **Dockerfile secret contract.** Images that resolve private deps take
  CodeArtifact auth as BuildKit secrets: the be image mounts
  `id=uv_index_url` as `UV_INDEX_URL` (run `codeartifact-login` first, pass
  `secret-envs: uv_index_url=UV_INDEX_URL`), the render image mounts
  `id=npmrc` at `/root/.npmrc` (pass `secret-files: npmrc=/home/runner/.npmrc`).

## Docs (`docs.yml`)

- A **Cloudflare Pages project is pre-provisioned** by infra, which supplies the
  `CLOUDFLARE_API_TOKEN` secret (pass via `secrets: inherit`) and the
  `CLOUDFLARE_ACCOUNT_ID` / `CLOUDFLARE_PAGES_PROJECT` variables, with the custom
  domain bound to the `main` (production) branch.
- **Python docs**: `just docs` builds Sphinx into `docs/_build/html`.
  **Node docs**: a Storybook build assembled into a site dir. The caller passes
  the `runtime`, `build-command`, and `output-dir`.
- A docs build needing a **service container** (codegen-database's Sphinx build
  talks to postgres) can't use `docs.yml` — `services:` can't pass through
  `workflow_call` — so it keeps a local docs workflow.

## Tooling versions

- **OPA / Regal** are pinned (`setup-opa` defaults 1.16.2 / 0.34.1) — bump
  deliberately, since OPA's `--schema` typechecker and Regal's lint rules evolve
  and can surface new failures.