@joshuafolkken/kit 1.872.0

package/.github/workflows/ci.yml

@@ -0,0 +1,681 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+
+  pull_request:
+    branches: [main]
+
+# A push run is grouped by the commit it carries, so a later push to main never cancels an earlier
+# one. Without the sha every push to main shares one group — `github.ref` is `refs/heads/main` for
+# all of them — and the run that reaches `notify-auto-tag` for the commit that changed the version
+# disappears: no tag, no publish, and nothing reported as failed (joshuafolkken/kit#1481).
+# The sha is added for `push` only: added unconditionally it would also stop a new push to a pull
+# request from cancelling that pull request's older runs, which is the saving this block exists for.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}${{ github.event_name == 'push' && format('-{0}', github.sha) || '' }}
+  cancel-in-progress: true
+
+# Which browsers the plain-runner fallback downloads when the MCR image could not be resolved.
+# chromium is the default because that is the single project this repository's config declares;
+# set the JOSH_PLAYWRIGHT_BROWSERS repository variable to a space-separated list to widen it.
+env:
+  JOSH_PLAYWRIGHT_BROWSERS: ${{ vars.JOSH_PLAYWRIGHT_BROWSERS || 'chromium' }}
+
+jobs:
+  node-26-pnpm:
+    name: Node 26 pnpm
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Resolve pnpm version
+        id: pnpm-version
+        run: |
+          version=$(node -p "const m = require('./package.json'); m.packageManager?.match(/^pnpm@([^+]+)/)?.[1] ?? (m.devEngines?.packageManager?.name === 'pnpm' ? m.devEngines.packageManager.version?.split('+')[0] : 'latest') ?? 'latest'")
+          test -n "$version"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+      - uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
+        with:
+          version: ${{ steps.pnpm-version.outputs.version }}
+          runtime: node@26
+          install: false
+      - run: node --version && pnpm --version
+
+  playwright-image:
+    name: Resolve Playwright image
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    permissions:
+      contents: read
+    outputs:
+      # JSON consumed via fromJSON() as the job-level `container` value: an object
+      # when the image exists, the literal `null` when it does not (= no container).
+      container: ${{ steps.resolve.outputs.container }}
+      # 'true' only when Playwright is a dependency but its image is unavailable, i.e.
+      # exactly when a job must download browsers itself.
+      should_install_browsers: ${{ steps.resolve.outputs.should_install_browsers }}
+      # The browser names the e2e job passes to `playwright install`, sanitized here so one
+      # place decides both the list and what may reach a command line.
+      browsers: ${{ steps.resolve.outputs.browsers }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      # The MCR image lags the npm publish by days, so a version-derived tag is not
+      # guaranteed to exist. Probe it first and fall back to a plain runner instead of
+      # emitting a tag that 404s and kills every dependent job before it starts.
+      - name: Resolve image
+        id: resolve
+        run: |
+          # Whitelist the characters: the value lands in $GITHUB_OUTPUT as JSON, so a
+          # newline or quote smuggled into the lockfile could forge an extra output line.
+          version=$(grep -m1 "'@playwright/test@" pnpm-lock.yaml | sed "s/.*'@playwright\/test@//" | sed "s/':.*//" | tr -cd 'A-Za-z0-9.-')
+
+          # Sanitized once, here, for the install step below: the value comes from repository
+          # settings and is interpolated into its command line, so only letters, dashes and the
+          # spaces between them survive. Uppercase is kept on purpose — a mistyped `Chromium`
+          # then reaches Playwright as an unknown browser and fails at the install step, where
+          # the mistake is, rather than being silently narrowed to chromium.
+          set -- $(printf '%s' "${JOSH_PLAYWRIGHT_BROWSERS}" | tr -cd 'A-Za-z -')
+          # Never empty: `playwright install` with no browser named fetches chromium *and*
+          # firefox *and* webkit plus ffmpeg, roughly 1 GB, which is the download this avoids.
+          [ "$#" -gt 0 ] || set -- chromium
+          browsers="$*"
+          echo "browsers=${browsers}" >> "$GITHUB_OUTPUT"
+
+          if [ -z "${version}" ]; then
+            echo 'container=null' >> "$GITHUB_OUTPUT"
+            echo 'should_install_browsers=false' >> "$GITHUB_OUTPUT"
+            echo 'Playwright is not a dependency; every job runs on the plain runner.'
+            exit 0
+          fi
+
+          tag="v${version}-noble"
+          image="mcr.microsoft.com/playwright:${tag}"
+          status=$(curl -sS -o /dev/null -w '%{http_code}' --max-time 30 --retry 2 \
+            -H 'Accept: application/vnd.docker.distribution.manifest.list.v2+json' \
+            "https://mcr.microsoft.com/v2/playwright/manifests/${tag}" || true)
+
+          if [ "${status}" = '200' ]; then
+            printf 'container={"image":"%s","options":"--user root"}\n' "${image}" >> "$GITHUB_OUTPUT"
+            echo 'should_install_browsers=false' >> "$GITHUB_OUTPUT"
+            echo "Resolved Playwright container image ${image}."
+          else
+            echo 'container=null' >> "$GITHUB_OUTPUT"
+            echo 'should_install_browsers=true' >> "$GITHUB_OUTPUT"
+            echo "::warning::Playwright image ${image} could not be resolved on MCR (HTTP ${status}). Running on the plain runner and installing ${browsers} instead (set the JOSH_PLAYWRIGHT_BROWSERS repository variable to change the list)."
+          fi
+
+  # A merge commit whose tree is identical to the merged pull request's head has already passed the
+  # required Checks context. Prove all three facts before reusing that result: this push came from one
+  # merged pull request, both commits name the same tree, and GitHub reports a successful Checks run on
+  # that exact pull request head. Every API or parsing failure leaves `reuse=false`, so a direct push,
+  # a conflicted merge, or unavailable evidence falls back to running both verification jobs.
+  reuse-pr-checks:
+    name: Reuse PR Checks
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    permissions:
+      actions: read
+      checks: read
+      contents: read
+      pull-requests: read
+    outputs:
+      reuse: ${{ steps.prove.outputs.reuse }}
+    steps:
+      - name: Prove the pushed tree passed PR Checks
+        id: prove
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CURRENT_SHA: ${{ github.sha }}
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          echo 'reuse=false' >> "$GITHUB_OUTPUT"
+
+          if ! pulls=$(gh api "repos/${REPOSITORY}/commits/${CURRENT_SHA}/pulls"); then
+            echo '::notice::Could not identify the pull request; running the verification jobs.'
+            exit 0
+          fi
+          if ! pull=$(printf '%s' "${pulls}" | jq -r --arg sha "${CURRENT_SHA}" \
+            '[.[] | select(.merged_at != null and .merge_commit_sha == $sha and .base.ref == "main")] | if length == 1 then .[0] | [.number, .head.sha, .head.ref, .created_at, .merged_at] | @tsv else empty end'); then
+            echo '::notice::Could not parse the pull request; running the verification jobs.'
+            exit 0
+          fi
+          if [ -z "${pull}" ]; then
+            echo 'No unique merged pull request matched this push; running the verification jobs.'
+            exit 0
+          fi
+          IFS=$'\t' read -r pull_number head_sha head_ref created_at merged_at <<< "${pull}"
+
+          if ! current_tree=$(gh api "repos/${REPOSITORY}/git/commits/${CURRENT_SHA}" --jq '.tree.sha') || \
+            ! pr_tree=$(gh api "repos/${REPOSITORY}/git/commits/${head_sha}" --jq '.tree.sha'); then
+            echo '::notice::Could not compare Git trees; running the verification jobs.'
+            exit 0
+          fi
+          if [ "${current_tree}" != "${pr_tree}" ]; then
+            echo 'The pushed tree differs from the verified pull request; running the verification jobs.'
+            exit 0
+          fi
+
+          if ! check_runs=$(gh api --method GET "repos/${REPOSITORY}/commits/${head_sha}/check-runs" \
+            -f per_page=100); then
+            echo '::notice::Could not read pull request checks; running the verification jobs.'
+            exit 0
+          fi
+          if ! run_ids=$(printf '%s' "${check_runs}" | jq -r \
+            '.check_runs[] | select(.name == "Checks" and .app.slug == "github-actions" and .status == "completed" and .conclusion == "success") | .details_url | select(test("/actions/runs/[0-9]+/job/")) | capture("/actions/runs/(?<id>[0-9]+)/job/").id'); then
+            echo '::notice::Could not parse pull request checks; running the verification jobs.'
+            exit 0
+          fi
+          passed=false
+          for run_id in ${run_ids}; do
+            if ! run=$(gh api "repos/${REPOSITORY}/actions/runs/${run_id}"); then
+              continue
+            fi
+            if printf '%s' "${run}" | jq -e --arg head_sha "${head_sha}" --arg head_ref "${head_ref}" \
+              --arg created_at "${created_at}" --arg merged_at "${merged_at}" \
+              '.event == "pull_request" and .head_sha == $head_sha and .head_branch == $head_ref and .path == ".github/workflows/ci.yml" and .conclusion == "success" and .created_at >= $created_at and .created_at <= $merged_at' >/dev/null; then
+              if artifacts=$(gh api --method GET "repos/${REPOSITORY}/actions/runs/${run_id}/artifacts" \
+                -f per_page=100) && printf '%s' "${artifacts}" | jq -e --arg name "pr-checks-${pull_number}" \
+                '.artifacts | any(.name == $name and .expired == false)' >/dev/null; then
+                passed=true
+                break
+              fi
+            fi
+          done
+          if [ "${passed}" != 'true' ]; then
+            echo 'The pull request has no successful Checks result; running the verification jobs.'
+            exit 0
+          fi
+
+          echo 'reuse=true' >> "$GITHUB_OUTPUT"
+          echo "Reusing successful PR Checks for tree ${current_tree}."
+
+  # joshuafolkken/kit#1226 split the gate's four checks across two runners. The unit suite is the only
+  # one that fans out across every core — 8.5 of them on the machine `scripts/gate/gate-plan.ts` measures —
+  # so on a 4-core GitHub runner it and the other three spent the whole job taking cores off each
+  # other: measured here, 121 seconds for the job with 106 of them inside the one gate step, against
+  # a theoretical floor of the unit suite alone.
+  #
+  # **The required status check did not move, and that is the point of the third job below.** GitHub
+  # matches a required context by the check-run name, which is a job's `name:`, and a required
+  # context that no longer names a job is not enforced — while a job absent from the list can go red
+  # without blocking a merge from the web UI. Splitting into two *named* jobs would therefore have
+  # needed a ruleset edit to stay as strict as it was, and left every merge between the two
+  # unguarded. So the two halves run under new names and `Checks` stays exactly what the ruleset
+  # already requires: a job that is green only when both halves are.
+  static-checks:
+    name: Static Checks
+    needs: reuse-pr-checks
+    if: ${{ always() && needs.reuse-pr-checks.outputs.reuse != 'true' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 8
+    permissions:
+      contents: read
+      packages: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '24'
+          registry-url: 'https://npm.pkg.github.com'
+
+      - name: Resolve pnpm version
+        id: pnpm-version
+        run: |
+          version=$(node -p "const m = require('./package.json'); m.packageManager?.match(/^pnpm@([^+]+)/)?.[1] ?? (m.devEngines?.packageManager?.name === 'pnpm' ? m.devEngines.packageManager.version?.split('+')[0] : 'latest') ?? 'latest'")
+          test -n "$version"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Setup pnpm
+        uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
+        with:
+          version: ${{ steps.pnpm-version.outputs.version }}
+          install: false
+
+      - name: Resolve pnpm store path
+        run: echo "PNPM_STORE_PATH=$(pnpm store path)" >> "$GITHUB_ENV"
+
+      - name: Setup pnpm store cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ${{ env.PNPM_STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Setup ESLint cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        id: eslint-cache
+        with:
+          path: |
+            .eslintcache
+          # joshuafolkken/kit#1347: the config inputs are `.js`, and the glob used to name `.ts` — which
+          # in `eslint/` is only the test files. So a rule edit left the key unchanged while a test edit
+          # busted it, the exact inverse of what invalidates a cache entry. The fingerprint in
+          # `eslint/config-fingerprint.js` now invalidates the entries themselves; this key has to move
+          # with it, or a rule edit would restore a cache whose every entry is stale, lint cold, and
+          # save nothing back under the key it already hit — a cold lint on every later run.
+          # joshuafolkken/kit#2030: `${{ github.sha }}` on the tail makes every run save a fresh entry
+          # under a new key, and the sha-less prefix in `restore-keys` restores the newest previous one
+          # first — so the cache tracks `main` instead of freezing on the first commit that hit the
+          # config-hash key and never re-saving. The config-hash body above still cold-invalidates on a
+          # rule edit exactly as before; the sha only ever adds a save, never suppresses one.
+          key: ${{ runner.os }}-eslint-cache-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('eslint.config.js', 'eslint/**/*.js') }}-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-eslint-cache-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('eslint.config.js', 'eslint/**/*.js') }}-
+            ${{ runner.os }}-eslint-cache-${{ hashFiles('pnpm-lock.yaml') }}-
+            ${{ runner.os }}-eslint-cache-
+
+      # `.tsbuildinfo` and `.cspellcache` were not cached in CI at all, so the type check and spell
+      # check ran cold on every run. Both are content-addressed — `tsc` records its compiler options
+      # inside the build-info file and cspell records a content hash of every config and dictionary it
+      # loaded — so restoring an older entry is never wrong; the tool re-checks only what changed
+      # (`scripts/lane/lane-cache.ts` relies on the same property when it warms a fresh lane). The sha
+      # tail plus a sha-less `restore-keys` prefix is the same save-fresh-every-run shape as the eslint
+      # cache above (joshuafolkken/kit#2030). The gate writes both files to the repo root:
+      # `josh check` runs `tsc --noEmit --incremental --tsBuildInfoFile .tsbuildinfo` and `josh
+      # cspell:dot` runs `cspell . --dot --cache --cache-strategy content --cache-location .cspellcache`.
+      - name: Setup TypeScript build cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        id: tsbuildinfo-cache
+        with:
+          path: |
+            .tsbuildinfo
+          key: ${{ runner.os }}-tsbuildinfo-${{ hashFiles('pnpm-lock.yaml') }}-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-tsbuildinfo-${{ hashFiles('pnpm-lock.yaml') }}-
+            ${{ runner.os }}-tsbuildinfo-
+
+      - name: Setup cspell cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        id: cspell-cache
+        with:
+          path: |
+            .cspellcache
+          key: ${{ runner.os }}-cspell-cache-${{ hashFiles('pnpm-lock.yaml') }}-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-cspell-cache-${{ hashFiles('pnpm-lock.yaml') }}-
+            ${{ runner.os }}-cspell-cache-
+
+      - name: Setup safe-chain
+        run: pnpm dlx @aikidosec/safe-chain@1.5.1 setup-ci
+
+      - name: Install dependencies
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      # One step rather than five, and concurrent rather than serial (joshuafolkken/kit#1216).
+      # `josh gate` is the command a developer runs before committing; it fans out to the same
+      # `josh` sub-commands that define each check — `lint` (prettier and eslint), `check` (the
+      # type check), `cspell:dot`, `test:unit` — so nothing here restates a tool invocation and CI
+      # cannot verify a different set from the local gate. Measured on this repository the five
+      # steps took 78–162 seconds end to end while the longest of them takes a fraction of that;
+      # the serial time was pure waiting, and it sat on the critical path between the pull request
+      # opening and the merge.
+      #
+      # **Every failure is reported in one pass.** The serial form stopped at the first red step,
+      # so a tree with a lint error and a type error cost two full CI runs to discover. The gate
+      # buffers each check and prints them all, failures with their whole output, which is the
+      # property `josh gate` was written for and the reason the five steps are not merely
+      # run in the background here.
+      #
+      # `--verbose` prints every check's body, not only the failing ones. Locally the quiet form is
+      # right — the gate runs many times per issue and the bodies pile up in the conversation — but a
+      # CI log is read once, after the fact, by someone who cannot re-run it, and a check that passed
+      # with warnings is invisible in a quiet log.
+      #
+      # **`--no-unit` selects the three checks, and selecting is not skipping** (joshuafolkken/kit#1226).
+      # The unit suite runs in the `unit` job below, through the same `josh test:unit` this step used
+      # to reach, so the set of checks CI enforces is unchanged — what moved is which runner each one
+      # is on. The flag is also the *only* thing that makes the split safe on the local side:
+      # `scripts/gate/verification-gate.ts` withholds the green-gate record and the in-flight marker on a
+      # `--no-unit` run, so this narrower gate can never let a later full `pnpm josh gate` be skipped,
+      # nor tell `josh review:brief` that a unit suite it did not run has passed.
+      #
+      # Two things are given up. GitHub's per-step timing and log grouping: the run shows one `Run
+      # verification gate` step instead of five named ones, and the gate's own summary names which
+      # check failed, which is what the grouping was being read for. And each check's output is
+      # buffered until it exits, so a check that *hangs* until this job's `timeout-minutes` is
+      # cancelled with nothing printed — where a serial step streamed. That costs one local
+      # `pnpm josh gate` to identify, and it is the price of the all-failures-in-one-pass summary.
+      - name: Run verification gate
+        run: pnpm josh gate --verbose --no-unit
+
+  # The other half of the gate, on a runner of its own. It carries the same setup steps as
+  # `static-checks` rather than sharing them: a GitHub job is its own machine, so every job that
+  # needs Node sets Node up, and this workflow already writes that preamble once per job. The
+  # single-source alternative — a local composite action under `.github/actions/` — is ruled out by
+  # `scripts/ci/ci-yml-action-parity.test.ts`, which pins the set of action names in this file to the
+  # set in `templates/workflows/ci.yml`; a local action cannot appear in a distributed template,
+  # because the template travels to consumers without it.
+  #
+  # No ESLint cache here — nothing in this job lints — and no `--maxWorkers`: `gate-plan.ts` leaves
+  # any machine below its measured 11 cores uncapped, so vitest sizes its own pool from the runner
+  # exactly as it did inside the gate step.
+  unit:
+    name: Unit Tests
+    needs: reuse-pr-checks
+    if: ${{ always() && needs.reuse-pr-checks.outputs.reuse != 'true' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 8
+    permissions:
+      contents: read
+      packages: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '24'
+          registry-url: 'https://npm.pkg.github.com'
+
+      - name: Resolve pnpm version
+        id: pnpm-version
+        run: |
+          version=$(node -p "const m = require('./package.json'); m.packageManager?.match(/^pnpm@([^+]+)/)?.[1] ?? (m.devEngines?.packageManager?.name === 'pnpm' ? m.devEngines.packageManager.version?.split('+')[0] : 'latest') ?? 'latest'")
+          test -n "$version"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Setup pnpm
+        uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
+        with:
+          version: ${{ steps.pnpm-version.outputs.version }}
+          install: false
+
+      - name: Resolve pnpm store path
+        run: echo "PNPM_STORE_PATH=$(pnpm store path)" >> "$GITHUB_ENV"
+
+      - name: Setup pnpm store cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ${{ env.PNPM_STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Setup safe-chain
+        run: pnpm dlx @aikidosec/safe-chain@1.5.1 setup-ci
+
+      - name: Install dependencies
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      # **Through `josh test:unit`, never `vitest run` directly, and that is what makes a job split
+      # safe rather than a hole.** The guard decides between a skip and a failure, and
+      # https://github.com/joshuafolkken/kit/issues/1224 settled which is which: vitest absent is a
+      # project with no unit suite yet, so it skips and the job stays green, while vitest present
+      # with nothing matching the test glob is a broken state and fails the job. Calling vitest here
+      # would give that second half back — a job that ran zero tests and reported success — and the
+      # split would have moved the check into a place that enforces less than the gate step did.
+      # `scripts/ci/ci-yml-unit-job.test.ts` pins the command; the guard itself is
+      # `scripts/test/test-unit-guard.ts`.
+      - name: Run unit tests
+        run: pnpm josh test:unit
+
+  # **The required status check. `Checks` is a name the branch ruleset already requires, and this job
+  # is what keeps that name meaning what it meant** (joshuafolkken/kit#1226) — every check the single
+  # `Checks` job used to run has passed. It runs no checks itself; it reads the two halves' results.
+  #
+  # `if: always()` is load-bearing and not a formality. Without it the job inherits the default "run
+  # only if every dependency succeeded", so a red `unit` would *skip* this job — and GitHub counts a
+  # skipped check as a passing one on the status rollup, which is precisely how a merge once went
+  # through with an E2E suite that never ran (see the `Detect E2E` job below, and
+  # https://github.com/joshuafolkken/kit/issues/991). A skipped aggregator would have reproduced that
+  # defect on the unit suite. Running always and failing explicitly is the only shape that cannot.
+  #
+  # The results are read from the environment rather than interpolated into the script. `needs.*.result`
+  # is a GitHub-controlled enum and not attacker-controlled, but a `${{ }}` expression spliced into a
+  # shell body is the pattern to keep out of a workflow regardless of the value's provenance.
+  checks:
+    name: Checks
+    needs: [reuse-pr-checks, static-checks, unit]
+    if: always()
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    permissions: {}
+    steps:
+      - name: Require both halves of the verification gate
+        env:
+          REUSE_RESULT: ${{ needs.reuse-pr-checks.outputs.reuse }}
+          STATIC_RESULT: ${{ needs.static-checks.result }}
+          UNIT_RESULT: ${{ needs.unit.result }}
+        run: |
+          echo "Reuse PR Checks: ${REUSE_RESULT}"
+          echo "Static Checks: ${STATIC_RESULT}"
+          echo "Unit Tests: ${UNIT_RESULT}"
+          if [ "${STATIC_RESULT}" = 'success' ] && [ "${UNIT_RESULT}" = 'success' ]; then
+            exit 0
+          fi
+          if [ "${REUSE_RESULT}" = 'true' ] && [ "${STATIC_RESULT}" = 'skipped' ] && \
+            [ "${UNIT_RESULT}" = 'skipped' ]; then
+            exit 0
+          fi
+          echo "::error::the verification gate did not pass on both runners"
+          exit 1
+
+      # The artifact binds this successful Checks job to the pull request number. A later main push
+      # reads it from this exact Actions run before reusing the result; the name alone is sufficient
+      # because the run already proves the head SHA, branch, workflow and pull_request event.
+      - name: Write PR Checks evidence
+        if: github.event_name == 'pull_request'
+        env:
+          PULL_REQUEST_NUMBER: ${{ github.event.pull_request.number }}
+        run: printf '%s\n' "${PULL_REQUEST_NUMBER}" > pr-checks-evidence
+
+      - name: Upload PR Checks evidence
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: pr-checks-${{ github.event.pull_request.number }}
+          path: pr-checks-evidence
+          retention-days: 1
+
+  security:
+    name: Security Audit
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Run security audit
+        uses: google/osv-scanner-action/osv-scanner-action@a345acffa64b0eaede81a3d9aae6141214d9c8fc # v2.6.0
+        with:
+          scan-args: --lockfile=pnpm-lock.yaml
+
+  e2e-detect:
+    name: Detect E2E
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    permissions:
+      contents: read
+    outputs:
+      enabled: ${{ steps.check.outputs.enabled }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      # The same rule `scripts/test/test-e2e-guard.ts` applies locally, so a suite that runs under
+      # `pnpm josh test:e2e` is a suite CI runs too. Every `*.e2e.{ts,js}` outside `node_modules`
+      # counts, at any depth; the guard's glob leaves dot-directories out by default, which is what
+      # the second prune term reproduces. The config filename is deliberately not consulted any
+      # more. Playwright accepts `playwright.config.js` as readily as `.ts`, and requiring one
+      # spelling made a project using the other read as "no E2E": the job's `if:` went false,
+      # GitHub recorded it as skipped, the status-check list counted the skip as a pass, and the
+      # merge went through with the suite never run. The same held for a spec kept anywhere but
+      # `tests` or `src/routes` (joshuafolkken/kit#991). The agreement is executed rather than
+      # asserted in prose: `scripts/ci/ci-yml-e2e-detect.test.ts` runs this very script against
+      # fixtures and compares its verdict to the guard's.
+      #
+      # One difference from the guard is deliberate and one-sided. The guard also skips when
+      # `@playwright/test` is not installed, which is what keeps that optional peer optional for
+      # the pre-push hook; here a spec enables the job whatever the manifest says, so a spec that
+      # cannot run ends red instead of silently green. Enabling more than the guard is safe —
+      # enabling less is the defect above, so no condition may be added that narrows this.
+      #
+      # Deliberately not `find ... | grep -q .`: `grep -q` exits on the first match and leaves
+      # `find` to be killed by the closed pipe, which is invisible under the default `bash -e` and
+      # decides the whole question under `bash -eo pipefail` — the shell GitHub selects for a step
+      # that declares `shell: bash`, or for every step once a `defaults: run: shell: bash` block is
+      # added at workflow or job level. The pipeline's status would then be 141, the `else` branch
+      # would be taken, and a repository full of specs would emit `enabled=false`: this defect
+      # again, reintroduced by a shell detail. Command substitution has no pipeline to
+      # fail, and `-print -quit` stops the walk at the first spec instead of enumerating the tree.
+      - name: Detect E2E specs
+        id: check
+        run: |
+          if [ -n "$(find . -mindepth 1 \( -name node_modules -o -name '.*' \) -prune \
+            -o \( -name '*.e2e.ts' -o -name '*.e2e.js' \) -print -quit)" ]; then
+            echo "enabled=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "enabled=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  e2e:
+    name: E2E
+    needs: [playwright-image, e2e-detect]
+    if: needs.e2e-detect.outputs.enabled == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: read
+    container: ${{ fromJSON(needs.playwright-image.outputs.container) }}
+    timeout-minutes: 10
+    # Better Auth rejects any origin its BETTER_AUTH_URL does not name, so this job pins the value
+    # to the preview server the suite talks to rather than letting a production value reach it.
+    # It has to be the port that server listens on. 4173 is correct because `PORT_SEED` — the
+    # personal offset `playwright.config.ts` resolves the preview port from — is not committed (it
+    # lives in a gitignored `.env`) and is not set anywhere in this workflow, so the port resolves
+    # to its base on every CI run. That is the invariant, not a constant in `playwright.config.ts`:
+    # the port there is seed-derived. The one setting that would move the port and leave this URL
+    # behind is an `env` entry for the seed in this file, at workflow or job level. A repository or
+    # organization variable would not: it reaches a step only through an explicit `vars.PORT_SEED`
+    # expression, and nothing here writes one. For a seeded CI job, derive this URL from
+    # `josh port preview` in the same job instead.
+    env:
+      BETTER_AUTH_URL: http://localhost:4173
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '24'
+          registry-url: 'https://npm.pkg.github.com'
+
+      - name: Resolve pnpm version
+        id: pnpm-version
+        run: |
+          version=$(node -p "const m = require('./package.json'); m.packageManager?.match(/^pnpm@([^+]+)/)?.[1] ?? (m.devEngines?.packageManager?.name === 'pnpm' ? m.devEngines.packageManager.version?.split('+')[0] : 'latest') ?? 'latest'")
+          test -n "$version"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Setup pnpm
+        uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
+        with:
+          version: ${{ steps.pnpm-version.outputs.version }}
+          install: false
+
+      - name: Resolve pnpm store path
+        run: echo "PNPM_STORE_PATH=$(pnpm store path)" >> "$GITHUB_ENV"
+
+      - name: Setup pnpm store cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ${{ env.PNPM_STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Setup build cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        id: build-cache
+        with:
+          path: |
+            .svelte-kit
+          key: ${{ runner.os }}-build-cache-e2e-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('svelte.config.js', 'vite.config.ts', 'tsconfig.json', 'src/lib/server/auth.ts') }}
+          restore-keys: |
+            ${{ runner.os }}-build-cache-e2e-${{ hashFiles('pnpm-lock.yaml') }}-
+            ${{ runner.os }}-build-cache-e2e-
+
+      - name: Setup safe-chain
+        run: pnpm dlx @aikidosec/safe-chain@1.5.1 setup-ci
+
+      - name: Install dependencies
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      # Only needed on the fallback path: the container image already ships browsers
+      # matching its own Playwright version. Invoked through the local bin rather than
+      # `pnpm exec` because Sonar's S6505 misreads `pnpm ... install` as a package
+      # install missing --ignore-scripts (this downloads browser binaries, not packages).
+      # Named rather than left to the default, which downloads every browser Playwright ships
+      # (~1 GB) where this config drives one of them. Left unquoted below so a multi-browser list
+      # splits into arguments; the resolve job already whitelisted it, so nothing but browser
+      # names can reach the command line.
+      - name: Install Playwright browsers
+        if: needs.playwright-image.outputs.should_install_browsers == 'true'
+        env:
+          PLAYWRIGHT_BROWSERS: ${{ needs.playwright-image.outputs.browsers }}
+        run: ./node_modules/.bin/playwright install --with-deps ${PLAYWRIGHT_BROWSERS}
+
+      - name: Build application
+        env:
+          E2E_CLEANUP_ENABLED: '1'
+        run: pnpm build
+
+      - name: Run E2E tests
+        run: pnpm test:e2e
+
+      # continue-on-error because the step exists to collect evidence, and collecting evidence must
+      # not be what decides the release: it runs on always(), so a transient artifact-service error
+      # would end the job red on a run whose tests passed, skipping the auto-tag dispatch below and
+      # withholding kit's own release (#809). The step's outcome stays `failure`, so it is still
+      # marked red on the run and a missing report is never silent. This job is skipped while kit
+      # ships no E2E specs; the guard is here so adding one cannot quietly turn the gap live.
+      - name: Upload test results
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: always()
+        continue-on-error: true
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+
+  notify-auto-tag:
+    name: Notify Auto Tag
+    needs: [checks, security, e2e-detect, e2e]
+    if: |
+      always() &&
+      github.event_name == 'push' &&
+      github.ref == 'refs/heads/main' &&
+      needs.checks.result == 'success' &&
+      needs.security.result == 'success' &&
+      needs.e2e-detect.result == 'success' &&
+      (needs.e2e.result == 'success' || needs.e2e.result == 'skipped')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Dispatch auto-tag
+        uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 # v4.0.1
+        with:
+          event-type: ci-passed-on-main
+          client-payload: '{"sha": "${{ github.sha }}"}'