static.yml

# Verify the repository, and deploy docs/ to Pages from development.
#
# TWO BEHAVIOURS, ONE FILE. On development it does what it always did: verify,
# rebuild the storybook when it can, build, publish. On chore/* it does every
# one of those things EXCEPT publish — the deploy job carries the ref check.
# Branches were unverified until 2026-08-26, so a pull request showed no checks
# and the first run against a change happened after it had already merged.
#
# The guard is on the DEPLOY job rather than on the trigger, deliberately: a
# branch that cannot build is a branch worth failing, and gating the trigger
# instead would have told us nothing until merge. It also catches
# workflow_dispatch from a branch, which used to publish that branch.
#
# The storybook's compiled/*.js and tw-bridge.css are generated from
# src/components/ and src/captured/ using this repository's own toolchain, and
# they are GITIGNORED -- produced here on every run, like packages/brand/dist/
# and dist/ itself. Nothing about them is committed, so nothing can be stale.
#
# That is new as of 2026-08-27, and it removed a step rather than adding one.
# They used to be tracked and guarded by check-tw-bridge.mjs, which compared a
# sha256 of both component roots against a digest recorded in the tw-bridge.css
# header. The arrangement made sense only while the generator needed a
# codecave.pro checkout and therefore could not run everywhere -- a node-only
# checker stood in for a build nobody could perform. The decoupling on
# 2026-08-26 ended that, and left the check doing something worse than nothing:
# this job ALREADY rebuilt the storybook and published the fresh output, so a
# red check was failing the build over files the same run then discarded. It
# cost the 2.4.1 release and a red development branch before it went.
#
# So the whole job is four steps, in dependency order:
#
#   1. npm ci.
#   2. `npm run build:storybook`, which chains the package build -- together
#      they produce everything `npm run check` reads and a checkout does not
#      carry.
#   3. `npm run check` -- the SCRIPT, not its seven checks restated as seven
#      steps, which is what stood here until 2026-08-27. Restating the chain
#      meant a check added to package.json was a check CI silently skipped.
#   4. The site built over the result.
#
# Step 3 losing the old "run the node-only checks before the install" property
# is deliberate. It bought early feedback on three prose checks when npm ci
# broke, and it cost the guarantee that CI runs what `npm run check` runs --
# and check:importmap now reads build output anyway, so the property was
# already half gone.
#
# No codecave.pro checkout is needed anywhere in this file. CODECAVE_PRO_TOKEN
# is unused by this repository and can be deleted.
name: Verify, and deploy Pages from development

on:
  # development is the branch that DEPLOYS. chore/* runs everything except the
  # deploy — see the `if` on that job — so a branch gets the full nine checks
  # and a real build before anyone merges it. Nothing here ran on a branch
  # before, which meant a pull request showed no checks at all and the first
  # time a change was verified was after it was already on the default branch.
  push:
    branches: ["development", "chore/*"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Keyed on the ref, so a branch run can never queue behind or delay a
# production deploy. Every development run still shares one group and is never
# cancelled — that is the original property: one concurrent deployment, allowed
# to finish. Branch runs get a group each and DO cancel, because a superseded
# check of a branch is worth nothing.
concurrency:
  group: pages-${{ github.ref }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/development' }}

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '24'

      - name: Install the brand toolchain
        run: npm ci

      # Produces BOTH things `npm run check` reads that a checkout does not
      # have: packages/brand/dist/, and the compiled storybook bundles that
      # check:importmap resolves against the vendored runtime map. Neither is
      # committed -- the storybook output stopped being tracked on 2026-08-27.
      # `build:storybook` chains the package build itself, since it compiles
      # each specimen out of packages/brand/dist/src.
      #
      # It also has to precede the site build, which copies docs/storybook/
      # through to dist/.
      - name: Build the package and the storybook
        run: npm run build:storybook

      # ---- verify ----------------------------------------------------------
      # One step running `npm run check`, rather than its seven checks written
      # out as seven steps, which is what stood here. Those steps ran the same
      # chain RESTATED -- so a check added to package.json was a check CI
      # silently did not run, and nothing but care kept the two equal. The
      # script is the list now.
      #
      # What it covers, and why none of it is optional:
      #
      #   check (workspace)  the package is a pure derivative of src/: every
      #                      copied file byte-identical to its origin,
      #                      theme.css agreeing with the tokens, the README's
      #                      quoted values matching the compiled module.
      #   check:ports        an adapter that has drifted from the interface its
      #                      component imports compiles perfectly and fails as
      #                      an undefined in a reader's browser -- the one
      #                      place a specimen must not fail.
      #   check:collisions   a token that would silently redefine a Tailwind
      #                      default in every consumer's app. Invisible to both
      #                      the docs build and the package build.
      #   check:importmap    an import map that has stopped resolving what the
      #                      bundles import takes every specimen down with no
      #                      error anyone sees: the page renders, it is simply
      #                      empty where the component was.
      #   check:findings     three files quote how many findings the story
      #                      pages carry, all hand-typed. The split has drifted
      #                      before without the total moving, which is
      #                      invisible to a reader and to every other check.
      #   check:examples     the six files under docs/examples/raw/ are
      #                      standalone documents Astro never renders. Moving
      #                      them one directory deeper broke the wordmark in
      #                      four of the six and every check stayed green --
      #                      an <iframe> reports nothing about what is inside it.
      #   check:links        collapsing five documentation surfaces into two
      #                      moved most of this site's URLs, and the places
      #                      that cite them are prose. A dead markdown link
      #                      fails nowhere at all except for a reader.
      - name: Check
        run: npm run check

      - name: Build the docs site
        run: npm run build

      # ---- publish ---------------------------------------------------------
      # Guarded on the same ref as the deploy job. A branch run has just proved
      # the thing worth proving — every check passes and the site builds — and
      # a Pages-shaped tarball no branch can deploy is not worth uploading on
      # every push. Note this is the LAST thing skipped: `npm run build` above
      # runs everywhere, so a branch that cannot build still fails.
      - name: Setup Pages
        if: github.ref == 'refs/heads/development'
        uses: actions/configure-pages@v5
      - name: Upload artifact
        if: github.ref == 'refs/heads/development'
        uses: actions/upload-pages-artifact@v3
        with:
          # dist/, not docs/ — CCWEB2-317. docs/ is now sources plus payload
          # and can no longer be served as-is: a ported page exists there only
          # as .astro. dist/ is docs/ passed through with the pages rendered
          # over the top.
          path: './dist'

  deploy:
    needs: build
    # ONLY development publishes. Without this line adding chore/* above would
    # put whatever is on a work-in-progress branch onto brand.codecave.pro, and
    # the last branch pushed would be the live site until someone pushed
    # development again. The build job above still runs in full on a branch —
    # what is skipped is the publish, not the verification.
    if: github.ref == 'refs/heads/development'
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5