template-git-repo 0.1.0

package/template/.github/workflows/auto-merge-and-create-prs.yml

@@ -0,0 +1,102 @@
+# A twice-daily sweep that keeps branches from being forgotten: it merges every
+# open PR that is already green and unblocked, then opens a PR for any branch
+# that does not have one.
+#
+# This is the backstop for agent sessions that push a branch and never open a
+# PR, and for PRs whose merge was skipped because a check finished after the
+# per-PR auto-merge workflow had already run.
+
+name: Auto-merge PRs and create missing PRs
+
+on:
+  schedule:
+    # 00:00 and 12:00 UTC. Scheduled workflows can be delayed under high
+    # GitHub Actions load — this is a sweep, not a deadline.
+    - cron: "0 */12 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: auto-merge-and-create-prs
+  cancel-in-progress: false
+
+jobs:
+  maintain-pull-requests:
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ secrets.GIT_TOKEN || secrets.GITHUB_TOKEN }}
+      GIT_TOKEN: ${{ secrets.GIT_TOKEN || secrets.GITHUB_TOKEN }}
+      BASE_BRANCH: ${{ github.event.repository.default_branch }}
+    steps:
+      - name: Merge eligible existing pull requests
+        env:
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+
+          # Only PRs that are non-draft, cleanly mergeable, not blocked by a
+          # requested change, and whose every check concluded SUCCESS, SKIPPED
+          # or NEUTRAL. A pending check means "not yet", not "merge it".
+          gh pr list \
+            --repo "$REPOSITORY" \
+            --state open \
+            --json number,isDraft,mergeStateStatus,reviewDecision,statusCheckRollup \
+            --jq '.[] | select(.isDraft == false) | select(.mergeStateStatus == "CLEAN") | select((.reviewDecision == "APPROVED") or (.reviewDecision == "")) | select(all(.statusCheckRollup[]?; (.conclusion == "SUCCESS" or .conclusion == "SKIPPED" or .conclusion == "NEUTRAL"))) | .number' \
+          | while read -r pr_number; do
+              echo "Attempting to merge PR #${pr_number}"
+              gh pr merge "$pr_number" \
+                --repo "$REPOSITORY" \
+                --squash \
+                --delete-branch \
+                --auto || echo "Could not merge PR #${pr_number}; it may require review, checks, or conflict resolution."
+            done
+
+      - name: Create pull requests for branches without one
+        env:
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+
+          # No actions/checkout above: this needs every remote branch, and a
+          # normal checkout fetches one. Fetching all refs into a bare-ish
+          # workspace is cheaper than checkout with fetch-depth: 0.
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
+          git init -q "$GITHUB_WORKSPACE"
+          cd "$GITHUB_WORKSPACE"
+          git remote add origin "https://x-access-token:${GIT_TOKEN}@github.com/${REPOSITORY}.git"
+          git fetch --quiet origin '+refs/heads/*:refs/remotes/origin/*'
+
+          base_sha="$(git rev-parse "origin/${BASE_BRANCH}")"
+
+          git for-each-ref --format='%(refname:strip=3)' refs/remotes/origin \
+            | grep -Ev "^(HEAD|${BASE_BRANCH})$" \
+            | while read -r branch; do
+                open_pr="$(gh pr list --repo "$REPOSITORY" --state open --head "$branch" --json number --jq 'length')"
+                # `merged` too: a branch whose PR was merged but which was never
+                # deleted would otherwise get a fresh PR opened on every sweep.
+                merged_pr="$(gh pr list --repo "$REPOSITORY" --state merged --head "$branch" --json number --jq 'length')"
+                branch_sha="$(git rev-parse "origin/${branch}")"
+
+                if [ "$open_pr" -gt 0 ] || [ "$merged_pr" -gt 0 ]; then
+                  echo "Skipping ${branch}: a pull request already exists or was previously merged."
+                  continue
+                fi
+
+                # An ancestor of the base branch has nothing to contribute; a PR
+                # for it would be empty.
+                if git merge-base --is-ancestor "$branch_sha" "$base_sha"; then
+                  echo "Skipping ${branch}: it is already contained in ${BASE_BRANCH}."
+                  continue
+                fi
+
+                echo "Creating PR for ${branch} -> ${BASE_BRANCH}"
+                gh pr create \
+                  --repo "$REPOSITORY" \
+                  --head "$branch" \
+                  --base "$BASE_BRANCH" \
+                  --title "Merge ${branch} into ${BASE_BRANCH}" \
+                  --body "Automated pull request for branch \`${branch}\`."
+              done

package/template/.github/workflows/auto-merge-claude.yml

@@ -0,0 +1,54 @@
+# Merges pull requests opened by an agent (or by the maintainers) as soon as
+# their checks pass, so agent-authored work does not sit waiting for a human to
+# click a button.
+#
+# The actor allowlist is the whole safety model: this must never fire for a PR
+# from an arbitrary contributor. Edit the `if:` below to match the accounts you
+# actually want merged automatically.
+
+name: Auto-merge agent PRs
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  auto-merge:
+    runs-on: ubuntu-latest
+    if: >
+      github.actor == 'claude[bot]' ||
+      github.actor == 'anthropic-claude[bot]' ||
+      github.actor == '{{OWNER}}'
+    steps:
+      - name: Enable auto-merge (or merge directly)
+        env:
+          # A PAT rather than GITHUB_TOKEN: merges pushed with GITHUB_TOKEN do
+          # not trigger further workflow runs, so a publish workflow listening
+          # on the default branch would never fire for the merge commit.
+          GH_TOKEN: ${{ secrets.GIT_TOKEN || secrets.GITHUB_TOKEN }}
+          PR: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+          HEAD_REF: ${{ github.head_ref }}
+        run: |
+          # Never delete long-lived branches after merging them.
+          case "$HEAD_REF" in
+            production|prod|staging|develop) MERGE_OPTS="--squash" ;;
+            *) MERGE_OPTS="--squash --delete-branch" ;;
+          esac
+
+          # Preferred path: let GitHub merge once required checks pass. Needs
+          # "Allow auto-merge" in repo settings plus branch protection with at
+          # least one required status check.
+          if gh pr merge "$PR" --repo "$REPO" $MERGE_OPTS --auto; then
+            echo "Auto-merge enabled for PR #$PR"
+          else
+            # Fallback for unprotected branches (no required checks): merge now
+            # if the PR is mergeable. Without branch protection there is nothing
+            # for --auto to wait on, so GitHub rejects it outright.
+            echo "Auto-merge unavailable, attempting direct merge"
+            gh pr merge "$PR" --repo "$REPO" $MERGE_OPTS
+          fi

package/template/.github/workflows/deploy-test-reports.yml

@@ -0,0 +1,98 @@
+# Publishes the HTML test report to Cloudflare Workers on every push to the
+# default branch, so the "Test Report" badge in the README links to something
+# current rather than to a workflow log.
+#
+# Requires an `apps/test-reports/` (or equivalent) directory with a
+# wrangler.toml whose `assets.directory` is `dist`, and a root `test:report`
+# script that writes the Vitest HTML reporter output there.
+
+name: Test Reports
+
+on:
+  push:
+    branches: [{{DEFAULT_BRANCH}}]
+  workflow_dispatch:
+
+concurrency:
+  group: test-reports
+  cancel-in-progress: true
+
+env:
+  REPORT_DIR: apps/test-reports
+
+jobs:
+  deploy:
+    name: Generate & deploy test reports
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: {{PACKAGE_MANAGER}} install --ignore-scripts
+
+      - name: Build workspace dependencies
+        run: bunx turbo build || echo "No build tasks"
+
+      # A red suite is exactly when the report is worth reading, so the run is
+      # allowed to fail here and still deploy.
+      - name: Run tests with the HTML reporter
+        run: {{PACKAGE_MANAGER}} run test:report
+        continue-on-error: true
+
+      # What the step above must not do is leave dist/ missing: wrangler treats
+      # an absent `assets.directory` as a hard error, so the run would end on a
+      # config error instead of on the test signal. Publish a placeholder rather
+      # than lose the deploy.
+      - name: Ensure a report exists to deploy
+        env:
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          if [ -f "$REPORT_DIR/dist/index.html" ]; then
+            exit 0
+          fi
+          echo "::warning::The test runner wrote no HTML report; deploying a placeholder page."
+          mkdir -p "$REPORT_DIR/dist"
+          cat > "$REPORT_DIR/dist/index.html" <<HTML
+          <!doctype html>
+          <html lang="en">
+          <head>
+          <meta charset="utf-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1">
+          <title>Test report unavailable</title>
+          <style>
+          :root { color-scheme: light dark; }
+          body { margin: 0; min-height: 100vh; display: grid; place-items: center;
+                 font: 16px/1.6 system-ui, sans-serif; padding: 24px; }
+          main { max-width: 34rem; }
+          h1 { font-size: 1.25rem; margin: 0 0 .75rem; }
+          p { margin: 0 0 .75rem; opacity: .85; }
+          </style>
+          </head>
+          <body>
+          <main>
+          <h1>Test report unavailable</h1>
+          <p>The last run of the test suite ended before the HTML reporter could
+          write a report, so there is nothing to show here yet.</p>
+          <p><a href="$RUN_URL">Open the workflow run</a> for the full output.</p>
+          <p>Commit $GITHUB_SHA</p>
+          </main>
+          </body>
+          </html>
+          HTML
+
+      - name: Deploy to Cloudflare Workers
+        working-directory: ${{ env.REPORT_DIR }}
+        run: npx wrangler deploy
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+
+      - name: Upload report artifact
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-reports
+          path: ${{ env.REPORT_DIR }}/dist/
+          if-no-files-found: ignore

package/template/.github/workflows/npm-publish.yml

@@ -0,0 +1,320 @@
+# Publishes every non-private workspace package whose *content* changed, without
+# anyone having to remember to bump a version.
+#
+# The rules this encodes were all learned the hard way:
+#
+#   - Compare npm pack integrity against the registry, not version numbers. A
+#     version bump is not evidence of a change and an unchanged version is not
+#     evidence of no change.
+#   - Check the publish credential before building anything. npm answers an
+#     unauthorized PUT with E404 ("could not be found"), which reads like a
+#     missing package — after every package has already been built, and after
+#     each failed attempt has signed a provenance statement into the public
+#     sigstore transparency log.
+#   - Walk the workspace in dependency order, not alphabetical order. A sibling
+#     that has not been built yet has no dist/, and its package.json `types`
+#     entries point at files that do not exist.
+#   - Never publish the literal "workspace:*" protocol — consumers cannot
+#     resolve it.
+#   - Treat the registry as the source of truth for which version numbers are
+#     spent. It refuses a PUT for any version it has ever seen, including
+#     staged and unpublished ones that the `latest` dist-tag cannot show you.
+#
+# Credentials, in order of preference:
+#
+#   1. Trusted publishing (OIDC) — no secret at all. Leave NPM_TOKEN unset and
+#      name this repo + workflow as the trusted publisher for each package on
+#      npmjs.com. Nothing to rotate, nothing to expire.
+#   2. An NPM_TOKEN secret. Granular access tokens expire after 90 days at
+#      most; classic automation tokens no longer work for direct publishing.
+
+name: Publish to npm
+
+on:
+  push:
+    branches: [{{DEFAULT_BRANCH}}]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  # Required for trusted publishing (OIDC) and for --provenance.
+  id-token: write
+
+concurrency:
+  group: npm-publish
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fetch-depth: 2
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: "https://registry.npmjs.org"
+
+      - uses: oven-sh/setup-bun@v2
+
+      # setup-node writes `always-auth` into the npmrc it generates. npm 10+
+      # does not know the key and warns about it on every single invocation,
+      # which is hundreds of lines of noise across a run. Authentication comes
+      # from the _authToken line, which stays.
+      - name: Drop the deprecated always-auth key from the generated npmrc
+        run: |
+          if [ -n "${NPM_CONFIG_USERCONFIG:-}" ] && [ -f "$NPM_CONFIG_USERCONFIG" ]; then
+            sed -i '/^always-auth[[:space:]]*[= ]/d' "$NPM_CONFIG_USERCONFIG"
+          fi
+
+      # Some published packages ship a broken `prepare: "husky install"` in
+      # their package.json. When npm reconciles bun's linked node_modules store
+      # it runs that hook, which dies with "husky: not found" (exit 127) — and
+      # npm's --ignore-scripts does NOT suppress it for bun-linked packages.
+      # Put a no-op `husky` on PATH so a stray hook becomes harmless.
+      - name: Neutralize unused husky hooks
+        run: |
+          mkdir -p "$RUNNER_TEMP/husky-shim"
+          printf '#!/bin/sh\nexit 0\n' > "$RUNNER_TEMP/husky-shim/husky"
+          chmod +x "$RUNNER_TEMP/husky-shim/husky"
+          echo "$RUNNER_TEMP/husky-shim" >> "$GITHUB_PATH"
+
+      - name: Verify npm publish credentials
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          set -uo pipefail
+
+          if [ -n "${NODE_AUTH_TOKEN:-}" ]; then
+            if whoami=$(npm whoami 2>&1); then
+              echo "🔑 Publishing as npm user '$whoami' (NPM_TOKEN)"
+              exit 0
+            fi
+            echo "$whoami"
+            echo "::error title=npm token rejected::The NPM_TOKEN secret no longer authenticates with registry.npmjs.org — it has expired, been revoked, or was replaced. Granular access tokens last 90 days at most. Mint a new token with write access at npmjs.com/settings/<user>/tokens and update the NPM_TOKEN repository secret, or remove the secret entirely and configure trusted publishing."
+            exit 1
+          fi
+
+          # No secret: trusted publishing. npm >= 11.5.1 trades this job's
+          # id-token for a short-lived publish token on its own.
+          if ! node -e "
+            const need = [11, 5, 1];
+            const have = process.argv[1].split('.').map(Number);
+            for (let i = 0; i < 3; i++) {
+              if ((have[i] || 0) !== need[i]) process.exit((have[i] || 0) > need[i] ? 0 : 1);
+            }
+          " "$(npm --version)"; then
+            echo "⏫ npm $(npm --version) is older than 11.5.1 — upgrading for trusted publishing (OIDC)"
+            npm install -g npm@latest
+          fi
+
+          # A half-configured empty token in the generated npmrc would make npm
+          # try (and fail) to authenticate with it instead of using OIDC.
+          if [ -n "${NPM_CONFIG_USERCONFIG:-}" ] && [ -f "$NPM_CONFIG_USERCONFIG" ]; then
+            sed -i '/_authToken/d' "$NPM_CONFIG_USERCONFIG"
+          fi
+          echo "🔑 No NPM_TOKEN secret — publishing via trusted publishing (OIDC) with npm $(npm --version)"
+
+      # Install the whole workspace once with the repo's package manager, which
+      # understands the "workspace:*" protocol and links local packages. Plain
+      # `npm install` cannot do this inside a bun/pnpm workspace — it dies on
+      # sibling "workspace:*" deps (EUNSUPPORTEDPROTOCOL), which leaves
+      # devDependencies uninstalled and builds failing with "vite: not found".
+      - name: Install workspace dependencies
+        run: {{PACKAGE_MANAGER}} install --ignore-scripts
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Publish packages whose content changed
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          # GitHub runs `run:` steps with `bash -e -o pipefail`, so not writing
+          # `set -e` does not disable errexit. With it on, the first package
+          # whose publish fails kills the step and every later package goes
+          # unreleased. Turn it off explicitly; per-package outcomes are handled
+          # through $rc, and the run still exits non-zero at the end.
+          set -uo pipefail
+          set +e
+
+          repo_root="$PWD"
+          failed_packages=""
+          skipped_builds=""
+          unauthorized_packages=""
+          unattempted_packages=""
+          auth_broken=""
+
+          build_order=$(node scripts/workspace-build-order.mjs)
+          echo "📋 Build order:"
+          echo "$build_order" | sed 's/^/   /'
+
+          for dir in $build_order; do
+            pkg="${dir}package.json"
+            [ -f "$pkg" ] || { echo "⏭ Skipping $dir (no package.json)"; continue; }
+
+            is_private=$(node -p "!!require('./$pkg').private")
+            name=$(node -p "require('./$pkg').name")
+
+            if [ "$is_private" = "true" ]; then
+              echo "⏭ Skipping $name (private)"
+              continue
+            fi
+
+            # One rejected PUT means the credential cannot write, and every
+            # remaining package would fail the same way — after another build
+            # each, and after signing provenance for a version that will never
+            # exist. Stop attempting them; the run still fails at the end.
+            if [ -n "$auth_broken" ]; then
+              echo "⏭ Skipping $name (npm rejected the publish credential — see above)"
+              unattempted_packages="$unattempted_packages $name"
+              continue
+            fi
+
+            echo "📦 Evaluating $name from $dir"
+
+            # Each package runs in a subshell with its own `set -e` so a failing
+            # step propagates to $rc without killing the outer loop.
+            (
+              set -e
+              cd "$dir"
+
+              # npm keeps the literal "workspace:*" in the tarball, which
+              # consumers cannot resolve. Replace it with a real semver range
+              # from the referenced local package; drop deps on local packages
+              # that are not published. Only committed back if the version is
+              # bumped.
+              node "$repo_root/scripts/pin-workspace-deps.mjs"
+
+              # Build before deciding anything: the tarball comparison below
+              # needs real dist output, and a package whose build fails is never
+              # published.
+              if [ "$(node -p "!!(require('./package.json').scripts||{}).build")" = "true" ]; then
+                if ! npm run build; then
+                  echo "⚠ Build failed for $name — not publishing (won't ship a broken tarball)"
+                  exit 42
+                fi
+              fi
+
+              version=$(node -p "require('./package.json').version")
+              latest=$(npm view "$name" version 2>/dev/null || echo "")
+              already=$(npm view "$name@$version" version 2>/dev/null || echo "")
+
+              # If the local version has fallen behind the registry (a bump
+              # commit that never landed back in the repo), publishing fails
+              # with "Cannot implicitly apply the latest tag". Sync first, then
+              # let the content comparison decide whether to release at all.
+              if [ -z "$already" ] && [ -n "$latest" ]; then
+                behind=$(node -e "
+                  const cmp = (x, y) => { const a = x.split('.').map(Number), b = y.split('.').map(Number); for (let i = 0; i < 3; i++) { if ((a[i]||0) !== (b[i]||0)) return (a[i]||0) - (b[i]||0); } return 0; };
+                  console.log(cmp(process.argv[1], process.argv[2]) < 0);
+                " "$version" "$latest")
+                if [ "$behind" = "true" ]; then
+                  echo "⏫ $name local version $version is behind npm latest $latest — syncing"
+                  npm version "$latest" --no-git-tag-version --no-workspaces
+                  version="$latest"
+                  already="$latest"
+                fi
+              fi
+
+              if [ -n "$already" ]; then
+                # This exact version is on npm. Publish anyway only if the
+                # content changed: npm tarballs are reproducible (normalized
+                # mtimes), so pack integrity is a reliable comparison.
+                local_integrity=$(npm pack --dry-run --ignore-scripts --json 2>/dev/null | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s)[0].integrity))")
+                remote_integrity=$(npm view "$name@$version" dist.integrity 2>/dev/null || echo "")
+
+                if [ "$local_integrity" = "$remote_integrity" ]; then
+                  echo "⏭ $name@$version already on npm with identical content — nothing new to release"
+                  exit 0
+                fi
+
+                # Bumping one patch above `latest` is not enough: `latest` lags
+                # any version staged by an interrupted publish, and npm answers
+                # a PUT for one of those with E409 "Cannot publish over
+                # previously staged version".
+                next=$(node "$repo_root/scripts/next-free-version.mjs" "$name" "$version")
+                echo "🔼 $name content changed since $version — bumping to $next"
+                # --no-workspaces stops npm from doing workspace-aware
+                # processing over bun's symlinks, which trips
+                # EUNSUPPORTEDPROTOCOL on workspace:* siblings.
+                npm version "$next" --no-git-tag-version --no-workspaces
+                version="$next"
+              fi
+
+              # Exit 43 for an authorization failure so the loop stops early.
+              # A version the registry reserved between the query above and the
+              # PUT is still possible, so E409 retries at the next free version
+              # rather than failing the package. Five refusals in a row is a
+              # problem no amount of bumping fixes.
+              log="$RUNNER_TEMP/npm-publish.log"
+              attempt=1
+
+              while :; do
+                echo "Publishing $name@$version"
+                if npm publish --provenance --access public --ignore-scripts 2>&1 | tee "$log"; then
+                  exit 0
+                fi
+
+                if grep -qE "npm error code (E401|E404|ENEEDAUTH|EAUTHUNKNOWN|EOTP)" "$log"; then
+                  exit 43
+                fi
+                if grep -q "npm error code E403" "$log" && ! grep -qi "cannot publish over" "$log"; then
+                  exit 43
+                fi
+                if ! grep -qi "cannot publish over" "$log"; then
+                  exit 1
+                fi
+                if [ "$attempt" -ge 5 ]; then
+                  echo "⚠ npm refused $attempt versions in a row for $name — giving up"
+                  exit 1
+                fi
+
+                next=$(node "$repo_root/scripts/next-free-version.mjs" "$name" "$version")
+                echo "↩ npm has $name@$version reserved — retrying as $next"
+                npm version "$next" --no-git-tag-version --no-workspaces
+                version="$next"
+                attempt=$((attempt + 1))
+              done
+            )
+            rc=$?
+
+            case "$rc" in
+              0) ;;
+              42) skipped_builds="$skipped_builds $name" ;;
+              43) unauthorized_packages="$unauthorized_packages $name"; auth_broken="1" ;;
+              *) failed_packages="$failed_packages $name" ;;
+            esac
+          done
+
+          [ -n "$skipped_builds" ] && echo "::warning::Skipped (build failed, not published):$skipped_builds"
+          [ -n "$unattempted_packages" ] && echo "⏭ Not attempted (the credential was already rejected):$unattempted_packages"
+
+          if [ -n "$unauthorized_packages" ]; then
+            echo "❌ Not authorized to publish:$unauthorized_packages"
+            echo "::error title=npm rejected the publish credential::npm answers an unauthorized PUT with E404 ('could not be found or you do not have permission to access it'), so this reads as a missing package — the packages exist, the write was refused. The NPM_TOKEN secret is read-only, scoped to a different set of packages, or expired; or, with trusted publishing, this repo + workflow is not yet named as the trusted publisher for these packages on npmjs.com."
+          fi
+
+          [ -n "$failed_packages" ] && echo "❌ Failed to publish:$failed_packages"
+
+          if [ -n "$failed_packages$unauthorized_packages$unattempted_packages" ]; then
+            exit 1
+          fi
+          exit 0
+
+      - name: Commit version bumps
+        if: success()
+        run: |
+          # Bumps made during publish must land back in the repo so the next run
+          # sees them. The workspace:* pinning done for the tarballs must not —
+          # restore everything except the "version" field.
+          node scripts/restore-pinned-deps.mjs
+          git add '{{PACKAGES_GLOB}}/package.json'
+          git diff --staged --quiet && echo "No version changes to commit" && exit 0
+          git commit -m "chore: bump published package versions [skip ci]"
+          git push

package/template/.github/workflows/tests.yml

@@ -0,0 +1,100 @@
+# Runs every workspace package that has a test suite, and ships both coverage
+# and test results to Codecov.
+#
+# The matrix is discovered rather than hand-maintained: a first job reads the
+# workspace globs out of the root package.json and emits one matrix entry per
+# package that declares a `test:coverage` (or `test`) script. Adding a package
+# to the repo therefore adds it to CI with no edit here — the failure mode of a
+# hand-written matrix is a package that silently stops being tested.
+#
+# Each entry is expected to produce, relative to its own directory:
+#
+#   coverage/lcov.info   coverage, uploaded under a Codecov flag named for the package
+#   junit.xml            test results, ingested by Codecov Test Analytics
+#
+# Neither is required — a package that writes only one still uploads that one.
+
+name: tests
+
+on:
+  push:
+    branches: [{{DEFAULT_BRANCH}}]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  discover:
+    name: Discover packages
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.list.outputs.matrix }}
+      empty: ${{ steps.list.outputs.empty }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - id: list
+        name: List packages with a test script
+        run: node scripts/list-test-packages.mjs >> "$GITHUB_OUTPUT"
+
+  test:
+    name: ${{ matrix.flag }}
+    needs: discover
+    if: needs.discover.outputs.empty != 'true'
+    runs-on: ubuntu-latest
+
+    # A package whose suite is currently red still uploads its results — that
+    # report is the point of Test Analytics — but it does not fail the run.
+    # Set `"ci": { "allowFailure": true }` in the package's package.json to
+    # opt into that, and drop it once the suite is green.
+    continue-on-error: ${{ matrix.allowFailure }}
+
+    strategy:
+      # One package's failure must not cancel the others' uploads.
+      fail-fast: false
+      matrix: ${{ fromJson(needs.discover.outputs.matrix) }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+
+      # --ignore-scripts: a dependency's postinstall has no business running in
+      # CI, and some published packages ship a `prepare: "husky install"` that
+      # dies with exit 127 when husky is not a dependency of this repo.
+      - name: Install dependencies
+        run: {{PACKAGE_MANAGER}} install --ignore-scripts
+
+      # Workspace libraries that siblings consume through their built `dist`
+      # must exist before anything imports them. Turbo resolves the dependency
+      # order; packages with no build script are a no-op.
+      - name: Build workspace dependencies
+        run: bunx turbo build --filter=${{ matrix.name }}^... || echo "No buildable dependencies for ${{ matrix.name }}"
+
+      - name: Run tests
+        working-directory: ${{ matrix.dir }}
+        run: {{PACKAGE_MANAGER}} run ${{ matrix.script }}
+
+      # `!cancelled()` rather than `always()`: a cancelled run has nothing worth
+      # uploading, but a *failed* one is exactly when the report matters most.
+      - name: Upload coverage to Codecov
+        if: ${{ !cancelled() }}
+        uses: codecov/codecov-action@v5
+        with:
+          files: ${{ matrix.dir }}/coverage/lcov.info
+          flags: ${{ matrix.flag }}
+          token: ${{ secrets.CODECOV_TOKEN }}
+          # Codecov being down must not turn a green suite red.
+          fail_ci_if_error: false
+
+      - name: Upload test results to Codecov
+        if: ${{ !cancelled() }}
+        uses: codecov/test-results-action@v1
+        with:
+          files: ${{ matrix.dir }}/junit.xml
+          flags: ${{ matrix.flag }}
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false