@ebalzan/ci 0.0.0-stage → 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ebalzan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,303 @@
-# Temporary Holding Version
+# ebalzan/ci
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@ebalzan/ci)](https://www.npmjs.com/package/@ebalzan/ci)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+**One set of CI/CD rules for every GitHub repo you own.** Point a repo at this
+one and it gets the same branch model, the same commit convention, the same
+automatic semver releases, the same repository settings and the same branch
+protection as every other repo — and when a rule changes here, it changes
+everywhere.
+
+It has three parts:
+
+| Part                                         | What it is                                                                                                                                                                                     |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Reusable workflows** (`.github/workflows`) | Called by four thin files in each repo: auto issue + PR per branch, PR-title check, the evergreen `dev → main` PR, and the release (bump, tag, GitHub Release).                                |
+| **CLI** (`npx @ebalzan/ci`)                  | `onboard` a repo in one command; `bootstrap` its Actions variables, secrets, settings and rulesets from shared + per-repo files (one repo or `--all`); validate commit messages in a git hook. |
+| **Shared config** (`config/`)                | The house rules: shared Actions variables, repository settings, branch rulesets — each overridable per repo.                                                                                   |
+
+```text
+  feat/login ── push ──▶ issue + PR into dev          (auto-work-items)
+                          │  PR title checked          (pr-title)
+                          ▼  squash-merge
+                         dev ──▶ one dev → main PR     (promote-dev-to-main)
+                          │       "feat: promote dev to main (v1.4.0)"
+                          ▼  squash-merge = release approval
+                         main ──▶ v1.4.0 tag + GitHub Release, dev synced   (release)
+                                   └─▶ your own deploy job, chained on the tag
+```
+
+---
+
+## Contents
+
+- [Quick start](#quick-start)
+- [What every repo gets](#what-every-repo-gets)
+- [Using the workflows by hand](#using-the-workflows-by-hand)
+- [Commands](#commands)
+- [Configuration in one minute](#configuration-in-one-minute)
+- [Versions and updates](#versions-and-updates)
+- [Requirements and limits](#requirements-and-limits)
+- [Documentation](#documentation)
+- [Contributing](#contributing) · [License](#license)
+
+---
+
+## Quick start
+
+**Prerequisites:** [GitHub CLI](https://cli.github.com) logged in as an admin of
+the repo (`gh auth login`, plus `gh auth refresh -s project` if you use project
+boards), Node.js ≥ 20, git, and bash (Linux, macOS, WSL or Git Bash).
+
+**1. Put the shared secrets in one place** (once per machine). Every repo gets
+these as repository secrets:
+
+```bash
+mkdir -p ~/.config/ebalzan-ci
+cat > ~/.config/ebalzan-ci/secrets.env <<'EOF'
+# Writes the issue/PR descriptions. Optional: without it the body is a stub.
+ANTHROPIC_API_KEY=sk-ant-...
+# Classic PAT, scopes `repo` + `project`. Optional: lets the bots' PRs trigger
+# PR Checks and write to Projects (v2) boards. Why classic: docs/GITHUB_ACTIONS_SETUP.md
+GH_PROJECT_TOKEN=ghp_...
+EOF
+```
+
+A repo's **own** secrets (deploy credentials, …) go in the same folder, under
+`repos/<owner>/<repo>/` — e.g. `repos/me/my-api/secrets.production.env` for its
+`production` environment. Then `bootstrap --all` works with no checkouts
+([ARCHITECTURE §7](docs/ARCHITECTURE.md#7-where-you-run-commands)).
+
+**2. Onboard a repo**, from its checkout:
+
+```bash
+cd my-repo
+npx @ebalzan/ci onboard --dry-run   # see exactly what it will do
+npx @ebalzan/ci onboard             # do it
+```
+
+That creates a `ci/onboard-ebalzan-ci` branch with the four workflow callers, a
+starter `.github/actions.env`, `renovate.json`, the `.gitignore` lines for
+secrets files and, for Node repos, the husky `commit-msg` hook and the
+[`@ebalzan/config`](https://www.npmjs.com/package/@ebalzan/config) Prettier and
+ESLint wiring; creates `dev` if missing; tags the repo `ebalzan-ci`; applies
+the variables, secrets, settings and rulesets; and pushes. The new
+`auto-pr.yml` opens the PR into `dev` on that very push.
+
+**3. Merge it** (squash), then merge the `dev → main` PR that appears: that is
+the repo's first release.
+
+From then on, the flow is just:
+
+```bash
+git switch dev && git pull
+git switch -c feat/search-filters
+git commit -m "feat(search): add filters"      # the hook checks the format
+git push -u origin feat/search-filters         # issue + PR into dev appear
+```
+
+Full walkthrough and the manual alternative: [docs/ONBOARDING.md](docs/ONBOARDING.md).
+
+---
+
+## What every repo gets
+
+| Rule                 | What it means                                                                                                                                                                        | Details                                                                                  |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| Branch model         | Work branches `<type>/<desc>` → `dev` (integration) → `main` (releases). Only the automated promotion PR merges into `main`.                                                         | [CI_FLOW](docs/CI_FLOW.md)                                                               |
+| Commit convention    | Conventional Commits with the types `feat fix docs style refact perf test build ci chore revert`. Checked locally by the hook and on every PR title.                                 | [COMMIT_GUIDE](docs/COMMIT_GUIDE.md)                                                     |
+| Branch ↔ title match | A `feat/` branch needs a `feat:` title (minor), any other type a patch-level title, unless it is marked breaking (`!`).                                                              | [CI_FLOW §3](docs/CI_FLOW.md#stage-2--pr-checks)                                         |
+| Work items           | Every pushed work branch gets a tracking issue and a PR into `dev`, labelled, assigned, optionally on a milestone and a Projects (v2) board with priority/size/estimate/dates.       | [AUTO_WORK_ITEMS](docs/AUTO_WORK_ITEMS_WORKFLOW.md)                                      |
+| Releases             | Every push to `main` is a release: semver bump from the commits since the last tag, `vX.Y.Z` tag, GitHub Release, `package.json` bumped if there is one (tag-only otherwise).        | [CI_FLOW §4](docs/CI_FLOW.md#4-version-bump-rules-commit-scan)                           |
+| Repo settings        | Squash-merge only, squash commit titled from the PR title, branches deleted after merge.                                                                                             | [REPO_RULES](docs/REPO_RULES.md)                                                         |
+| Branch rulesets      | `main` cannot be deleted or force-pushed; `dev` cannot be deleted; an opt-in rule requires PRs + the title check.                                                                    | [REPO_RULES](docs/REPO_RULES.md)                                                         |
+| Code style (Node)    | Prettier, ESLint and TypeScript rules from [`@ebalzan/config`](https://www.npmjs.com/package/@ebalzan/config), extended — not copied — by each repo.                                 | [ARCHITECTURE §10](docs/ARCHITECTURE.md#10-the-two-packages-ebalzanci-and-ebalzanconfig) |
+| Dev tooling versions | A Renovate preset keeps Prettier, ESLint, husky, lint-staged, TypeScript and both `@ebalzan` packages on the same versions everywhere — one grouped PR a week, nothing else touched. | [renovate/tooling.json](renovate/tooling.json)                                           |
+
+Every rule can be overridden per repo, in that repo — see
+[Configuration](#configuration-in-one-minute).
+
+**What stays in each repo:** the four small caller files (two identical
+everywhere, two with the repo's own jobs added), its build/test jobs, its
+deploy, and its own variables and secrets. Which file is which, what runs
+where, and how to structure a deploy: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+---
+
+## Using the workflows by hand
+
+`onboard` writes these for you ([templates/](templates/)), but nothing more is
+needed than four small files. Each holds only what a reusable workflow cannot:
+the trigger, the permissions and the secrets.
+
+```yaml
+# .github/workflows/auto-pr.yml
+name: Auto Create Work Items
+on:
+  push:
+    branches-ignore: [main, dev]
+    tags-ignore: ['**']
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+  repository-projects: write
+jobs:
+  work-items:
+    uses: ebalzan/ci/.github/workflows/auto-work-items.yml@v2
+    secrets:
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      GH_PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
+```
+
+```yaml
+# .github/workflows/release.yml — with a deploy chained on the new tag
+name: Release
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: write
+  pull-requests: read
+jobs:
+  release:
+    uses: ebalzan/ci/.github/workflows/release.yml@v2
+  deploy:
+    needs: release
+    if: ${{ needs.release.outputs.tag != '' }}
+    uses: ./.github/workflows/deploy.yml
+    with:
+      image_tag: ${{ needs.release.outputs.tag }}
+```
+
+| Reusable workflow         | Inputs (all optional)                                     | Secrets                                 | Caller must grant                                                                       |
+| ------------------------- | --------------------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------- |
+| `auto-work-items.yml`     | `runs-on` (`ubuntu-latest`), `base-branch` (`dev`)        | `ANTHROPIC_API_KEY`, `GH_PROJECT_TOKEN` | `contents: read`, `issues: write`, `pull-requests: write`, `repository-projects: write` |
+| `pr-title.yml`            | `runs-on`                                                 | —                                       | `contents: read`                                                                        |
+| `promote-dev-to-main.yml` | `runs-on`                                                 | `GH_PROJECT_TOKEN`                      | `contents: read`, `issues: write`, `pull-requests: write`                               |
+| `release.yml`             | `runs-on`, `sync-dev` (`true`) · **outputs** `tag`, `sha` | —                                       | `contents: write`, `pull-requests: read`                                                |
+
+Secrets are passed by name: `secrets: inherit` is only guaranteed within one
+organization. Variables need no passing — inside a reusable workflow, `vars` are
+the **caller's**. Call `pr-title.yml` from a job named `title` so the check is
+reported as `title / Validate PR Title`, the name the rulesets require.
+
+---
+
+## Commands
+
+```text
+npx @ebalzan/ci <command> [options]      # or `ebalzan-ci` once installed
+```
+
+| Command        | Does                                                                                                  |
+| -------------- | ----------------------------------------------------------------------------------------------------- |
+| `onboard`      | Adds the templates on a branch, creates `dev`, tags the repo, bootstraps it, pushes.                  |
+| `bootstrap`    | Syncs variables, secrets, settings and rulesets onto one repo (`-C dir`, `-R owner/repo`) or `--all`. |
+| `reset`        | Deletes Actions variables/secrets on a repo after a typed confirmation.                               |
+| `commit-msg`   | Validates a commit message; the husky hook calls it.                                                  |
+| `path`         | Prints the package directory.                                                                         |
+| `sync-managed` | Deprecated: refreshes old local copies of the validator.                                              |
+
+Every command has `--help`, and `bootstrap`, `reset` and `onboard` have
+`--dry-run`. Full reference: [docs/CLI.md](docs/CLI.md).
+
+---
+
+## Configuration in one minute
+
+Everything is a file, merged in two layers — **the repo's value always wins**:
+
+```text
+                     shared (this package)              repo
+Actions variables    config/actions.env              +  .github/actions.env
+repository secrets   ~/.config/ebalzan-ci/secrets.env +  ~/.config/ebalzan-ci/repos/<owner>/<repo>/secrets.env
+environment secrets  …/secrets.<env>.env              +  …/repos/<owner>/<repo>/secrets.<env>.env
+                                                         (or the repo's gitignored .github/secrets*.env)
+repo settings        config/repo-settings.json        +  .github/repo-settings.json   (deep merge)
+branch rulesets      config/rulesets/<name>.json      +  .github/rulesets/<name>.json (deep merge)
+```
+
+`ebalzan-ci bootstrap` shows the merged plan (`--dry-run`), labelling each key
+`shared`, `repo`, `repo (overrides shared)` or `repo (same as shared:
+redundant)`, and applies it. Shared **variables** are never copied onto repos:
+the actions read `config/actions.env` at run time from the version the caller
+pins, so changing one is a release, not a sync.
+
+`--all` acts on every repo tagged with the `ebalzan-ci` topic (which `onboard`
+adds) plus any listed in `config/repos.env`.
+
+- Every key, its default and who reads it: [docs/CONFIGURATION.md](docs/CONFIGURATION.md)
+- Variables vs secrets, repository vs environment scope: [docs/GITHUB_ACTIONS_SETUP.md](docs/GITHUB_ACTIONS_SETUP.md)
+- Settings and rulesets: [docs/REPO_RULES.md](docs/REPO_RULES.md)
+
+---
+
+## Versions and updates
+
+This repo releases itself with its own pipeline, and the version means the
+same thing in both places:
+
+- **Callers pin a major tag**: `uses: ebalzan/ci/…@v2`. Every release moves
+  `v2` to it, so fixes and new features reach every repo with no change on
+  their side. Pinning `@v2.3.1` or a SHA freezes only the workflow file — the
+  actions inside it still follow `v2` ([why](docs/ARCHITECTURE.md#9-versions-what-a-pin-freezes)).
+- **The npm package** `@ebalzan/ci` has the same version as the tag.
+- **Breaking changes** (a removed input, a new required permission or secret, a
+  renamed variable) only ever ship as a new major (`v3`). `v2` stays where it is,
+  and each repo moves when you are ready.
+
+What changed in each release: [GitHub Releases](https://github.com/ebalzan/ci/releases).
+Upgrading from the private `tracebim-ci` v1: [docs/MIGRATION.md](docs/MIGRATION.md).
+
+---
+
+## Requirements and limits
+
+- **GitHub.com** repos. The reusable workflows are public, so any repo — personal
+  or organization — can call them.
+- **The flow is fixed:** `main` + `dev` + typed work branches + squash merges.
+  That is the point (the same rules everywhere), not an accident. `runs-on`,
+  the board, labels, milestone, priorities, sizes and descriptions are
+  configurable; the branch model and commit types are not.
+- **Rulesets** need a public repo or a paid plan (GitHub Pro/Team) for private
+  ones; on the free plan `bootstrap` warns and skips them. Everything else works
+  on the free plan.
+- **Projects (v2) boards owned by a personal account** need a _classic_ PAT
+  (`GH_PROJECT_TOKEN`); fine-grained tokens cannot reach them.
+- **The CLI needs bash** (Linux, macOS, WSL, Git Bash). The `commit-msg` command
+  needs a POSIX `sh`.
+- The work-item descriptions are written by Claude (Anthropic API) when
+  `ANTHROPIC_API_KEY` is set; without it a plain template is used.
+
+---
+
+## Documentation
+
+| Doc                                                          | Covers                                                                         |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| [ARCHITECTURE](docs/ARCHITECTURE.md)                         | What is shared vs repo-specific, what runs where, deploys, design decisions    |
+| [ONBOARDING](docs/ONBOARDING.md)                             | Adding a repo with `onboard`, or by hand; what each generated file is for      |
+| [CI_FLOW](docs/CI_FLOW.md)                                   | Branch → `dev` → `main` → release, stage by stage; bump rules; troubleshooting |
+| [COMMIT_GUIDE](docs/COMMIT_GUIDE.md)                         | Commit types, PR titles, versioning, for people writing commits                |
+| [AUTO_WORK_ITEMS_WORKFLOW](docs/AUTO_WORK_ITEMS_WORKFLOW.md) | The issue / PR / board automation in detail                                    |
+| [CONFIGURATION](docs/CONFIGURATION.md)                       | Every variable, secret and config file, with defaults                          |
+| [GITHUB_ACTIONS_SETUP](docs/GITHUB_ACTIONS_SETUP.md)         | Where a value belongs (variable/secret, repo/environment) and why              |
+| [REPO_RULES](docs/REPO_RULES.md)                             | Repository settings and branch rulesets                                        |
+| [CLI](docs/CLI.md)                                           | Every command and option                                                       |
+| [MIGRATION](docs/MIGRATION.md)                               | From `ebalzan/tracebim-ci` v1 to `ebalzan/ci` v2                               |
+| [CONTRIBUTING](CONTRIBUTING.md)                              | Working on this repo: layout, tests, releasing, publishing to npm              |
+
+---
+
+## Contributing
+
+Issues and PRs are welcome. This repo uses its own rules, so a PR needs a
+typed branch and a Conventional Commit title. Setup, tests and the release
+process: [CONTRIBUTING.md](CONTRIBUTING.md). Security reports:
+[SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) © ebalzan

package/bin/_json.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+//
+// _json.mjs — JSON helpers for the bash tools (bash has no JSON of its own, and
+// node is already a requirement of the package). Not a public command.
+//
+//   merge FILE...          Deep-merge the files left to right (later wins) and
+//                          print the result. Objects merge key by key; arrays
+//                          and scalars are replaced whole. Missing files are
+//                          skipped. Top-level keys starting with `$` (e.g.
+//                          "$comment") are documentation and are dropped.
+//   get FILE KEY           Print one top-level value (strings unquoted).
+//   diff DESIRED CURRENT   Print `key<TAB>current<TAB>desired` for every
+//                          top-level key of DESIRED whose value differs in
+//                          CURRENT. Exit 0 either way.
+//
+// Used by gh-bootstrap.sh for config/repo-settings.json and config/rulesets/.
+
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import process from 'node:process'
+import { pathToFileURL } from 'node:url'
+
+function fail(message) {
+  console.error(`_json.mjs: ${message}`)
+  process.exit(2)
+}
+
+function read(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch (error) {
+    fail(`${file}: ${error instanceof Error ? error.message : error}`)
+  }
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function deepMerge(base, override) {
+  if (!isPlainObject(base) || !isPlainObject(override)) return override
+  const merged = { ...base }
+  for (const [key, value] of Object.entries(override)) {
+    merged[key] = key in base ? deepMerge(base[key], value) : value
+  }
+  return merged
+}
+
+export function stripDocKeys(value) {
+  if (!isPlainObject(value)) return value
+  return Object.fromEntries(Object.entries(value).filter(([key]) => !key.startsWith('$')))
+}
+
+export function diffTopLevel(desired, current) {
+  const rows = []
+  for (const [key, value] of Object.entries(desired)) {
+    const now = current?.[key]
+    if (JSON.stringify(now) !== JSON.stringify(value)) {
+      rows.push([key, now === undefined ? '(unset)' : JSON.stringify(now), JSON.stringify(value)])
+    }
+  }
+  return rows
+}
+
+function main(argv) {
+  const [command, ...args] = argv
+  switch (command) {
+    case 'merge': {
+      const docs = args.filter(file => existsSync(file)).map(read)
+      if (docs.length === 0) fail('merge: none of the files exist')
+      process.stdout.write(`${JSON.stringify(stripDocKeys(docs.reduce(deepMerge)), null, 2)}\n`)
+      return
+    }
+    case 'get': {
+      const [file, key] = args
+      const value = read(file)?.[key]
+      if (value === undefined || value === null) return
+      process.stdout.write(typeof value === 'string' ? value : JSON.stringify(value))
+      return
+    }
+    case 'diff': {
+      const [desired, current] = args
+      for (const row of diffTopLevel(read(desired), read(current))) {
+        process.stdout.write(`${row.join('\t')}\n`)
+      }
+      return
+    }
+    default:
+      fail(`unknown command '${command ?? ''}' (merge | get | diff)`)
+  }
+}
+
+// Run as a script, not when imported by the tests.
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  main(process.argv.slice(2))
+}

package/bin/_lib.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+#
+# _lib.sh — shared helpers for the ebalzan/ci GitHub-config tools.
+# This file is *sourced*, not executed. The sourcing script owns `set -euo pipefail`.
+#
+# Also meant to be sourced by a repo's own admin scripts, so keep it free of
+# anything specific to one script. Find it with the CLI:
+#
+#   source "$(npx --no-install ebalzan-ci path)/bin/_lib.sh"
+#
+# Bash 3.2 compatible (macOS /bin/bash): no associative arrays, no mapfile.
+
+# ---- pretty output -----------------------------------------------------------
+if [[ -t 1 && -z "${NO_COLOR:-}" ]]; then
+  BOLD=$'\033[1m'; DIM=$'\033[2m'; RED=$'\033[31m'; GREEN=$'\033[32m'
+  YELLOW=$'\033[33m'; CYAN=$'\033[36m'; RESET=$'\033[0m'
+else
+  BOLD=''; DIM=''; RED=''; GREEN=''; YELLOW=''; CYAN=''; RESET=''
+fi
+info() { printf '%s\n' "$*"; }
+step() { printf '%s==>%s %s\n' "$CYAN$BOLD" "$RESET" "$*"; }
+ok()   { printf '%s ✓%s %s\n' "$GREEN" "$RESET" "$*"; }
+warn() { printf '%s ! %s%s\n' "$YELLOW" "$*" "$RESET"; }
+die()  { printf '%s ✗ %s%s\n' "$RED" "$*" "$RESET" >&2; exit 1; }
+
+# ---- dotenv helpers ----------------------------------------------------------
+# Print only KEY=VALUE lines (drop comments and blanks). Missing file → nothing.
+clean_env() { [[ -f "$1" ]] && grep -vE '^[[:space:]]*(#|$)' "$1" || true; }
+# Print just the key names from an env file.
+env_keys()  { clean_env "$1" | sed -E 's/=.*//'; }
+# Count the KEY=VALUE lines in an env file (0 if missing/empty).
+env_count() { clean_env "$1" | grep -c . || true; }
+# Read a single value: env_get FILE KEY. A missing key or file prints nothing
+# and still succeeds, so `x="$(env_get ...)"` is safe under `set -e`.
+env_get()   { { clean_env "$1" | grep -E "^$2=" | head -1 | cut -d= -f2-; } || true; }
+# Strip one pair of matching surrounding quotes, as dotenv parsers do.
+unquote()   {
+  local v="$1"
+  if [[ ${#v} -ge 2 && ( ( "${v:0:1}" == '"' && "${v: -1}" == '"' ) || ( "${v:0:1}" == "'" && "${v: -1}" == "'" ) ) ]]; then
+    v="${v:1:${#v}-2}"
+  fi
+  printf '%s' "$v"
+}
+
+# ---- gh helpers --------------------------------------------------------------
+require_gh() {
+  command -v gh >/dev/null 2>&1 \
+    || die "GitHub CLI (gh) is not installed: https://cli.github.com"
+}
+require_auth() {
+  gh auth status >/dev/null 2>&1 \
+    || die "gh is not authenticated. Run: gh auth login   (board scope: gh auth refresh -s project)"
+}
+
+# detect_repo [DIR] — OWNER/REPO of the checkout at DIR (default: cwd). Prints it.
+# Starts from the git remote, then asks GitHub for the canonical name, so a repo
+# that was transferred (whose old remote URL still redirects) resolves to where
+# it lives now — the scope its variables and secrets actually belong to.
+detect_repo() {
+  local dir="${1:-.}" repo canonical
+  repo="$(git -C "$dir" remote get-url origin 2>/dev/null \
+    | sed -E 's#(git@|ssh://git@|https://)([^/:]+)[:/]##; s#\.git$##' || true)"
+  if [[ -n "$repo" ]]; then
+    canonical="$(gh repo view "$repo" --json nameWithOwner -q .nameWithOwner 2>/dev/null || true)"
+    [[ -n "$canonical" ]] && repo="$canonical"
+  fi
+  printf '%s' "$repo"
+}
+
+# Web URL of a Projects (v2) board. User-owned boards live under /users/, not
+# /orgs/ — the owner type decides, so ask the API and default to users.
+project_url() { # project_url OWNER NUMBER
+  local kind
+  kind="$(gh api "users/$1" -q .type 2>/dev/null || true)"
+  if [[ "$kind" == "Organization" ]]; then
+    printf 'https://github.com/orgs/%s/projects/%s' "$1" "$2"
+  else
+    printf 'https://github.com/users/%s/projects/%s' "$1" "$2"
+  fi
+}
+
+# ---- prompts -----------------------------------------------------------------
+# confirm "question" → 0 if the user answers y/Y
+confirm() {
+  local reply
+  printf '%s%s [y/N] %s' "$YELLOW" "$1" "$RESET"
+  read -r reply
+  [[ "$reply" =~ ^[Yy]$ ]]
+}
+# confirm_typed EXPECTED "prompt" → 0 only if the user types EXPECTED verbatim
+confirm_typed() {
+  local reply
+  printf '%s%s%s ' "$YELLOW" "$2" "$RESET"
+  read -r reply
+  [[ "$reply" == "$1" ]]
+}
+
+# ---- repo discovery ----------------------------------------------------------
+# ci_repos_root CI_ROOT — where `--all` looks for local checkouts
+# (<root>/<repo name>). TRACEBIM_REPOS_ROOT is the pre-2.0 name, still honoured.
+ci_repos_root() {
+  printf '%s' "${CI_REPOS_ROOT:-${TRACEBIM_REPOS_ROOT:-$(dirname "$1")}}"
+}
+
+# managed_repos REPOS_FILE CI_ROOT — every OWNER/REPO `--all` acts on, one per
+# line, de-duplicated: the repos of REPOS_OWNER (default: the gh user) tagged
+# with REPOS_TOPIC, plus the explicit REPOS list. A REPOS entry without a slash
+# is a pre-2.0 checkout directory name under ci_repos_root; its slug comes from
+# that checkout's remote.
+managed_repos() {
+  local file="$1" ci_root="$2" topic owner entry root
+  topic="$(unquote "$(env_get "$file" REPOS_TOPIC)")"
+  owner="$(unquote "$(env_get "$file" REPOS_OWNER)")"
+  root="$(ci_repos_root "$ci_root")"
+  {
+    if [[ -n "$topic" ]]; then
+      [[ -n "$owner" ]] || owner="$(gh api user -q .login 2>/dev/null || true)"
+      [[ -n "$owner" ]] || die "REPOS_TOPIC is set but the gh user is unknown. Run gh auth login, or set REPOS_OWNER."
+      gh repo list "$owner" --topic "$topic" --no-archived --limit 1000 \
+        --json nameWithOwner -q '.[].nameWithOwner' \
+        || die "Could not list $owner's repos tagged '$topic'."
+    fi
+    for entry in $(unquote "$(env_get "$file" REPOS)"); do
+      if [[ "$entry" == */* ]]; then
+        printf '%s\n' "$entry"
+      elif [[ -d "$root/$entry" ]]; then
+        detect_repo "$root/$entry"; printf '\n'
+      else
+        warn "REPOS entry '$entry' has no checkout at $root/$entry — use OWNER/REPO."
+      fi
+    done
+  } | awk 'NF && !seen[tolower($0)]++'
+}
+
+# local_checkout SLUG CI_ROOT — the local checkout of SLUG, if there is one:
+# this repo itself, or <ci_repos_root>/<repo name> whose remote is SLUG. Prints
+# nothing otherwise.
+local_checkout() {
+  local slug="$1" ci_root="$2" dir found
+  for dir in "$ci_root" "$(ci_repos_root "$ci_root")/${slug#*/}"; do
+    [[ -d "$dir/.git" || -f "$dir/.git" ]] || continue
+    found="$(detect_repo "$dir")"
+    if [[ "$(printf '%s' "$found" | tr '[:upper:]' '[:lower:]')" == "$(printf '%s' "$slug" | tr '[:upper:]' '[:lower:]')" ]]; then
+      (cd "$dir" && pwd); return 0
+    fi
+  done
+  return 0
+}
+
+# print_help SCRIPT — the script's leading comment block, minus the shebang.
+print_help() {
+  awk 'NR>1 && /^#/{ sub(/^# ?/, ""); print; next } NR>1{ exit }' "$1"
+}