static.yml

# Deploy docs/ to GitHub Pages, rebuilding the storybook first when it can.
#
# The storybook's compiled/*.js and tw-bridge.css are generated from
# docs/source_examples/, but the generator needs the codecave.pro repo's
# toolchain (vue/compiler-sfc, esbuild, tailwindcss) — the SAME versions the
# website builds with, which is the whole point. That means the rebuild can
# only run where this workflow can reach that repo.
#
# So the job is in two halves, and the order matters:
#
#   1. A verification that ALWAYS runs. check-tw-bridge.mjs needs nothing but
#      node, and it proves the committed storybook is in step with the sources
#      beside it. This is the real guarantee — a stale bridge compiles and
#      loads and silently documents an older site, so nothing else catches it.
#
#   1b. A typecheck of storybook/ports/ against the interfaces in ports.d.ts.
#      Needs typescript, so it follows step 1 rather than joining it — step 1
#      keeps its "nothing but node" property.
#
#   2. A rebuild that runs when the toolchain is reachable, and is skipped
#      without failing when it is not. Pages must keep deploying either way:
#      losing the site because another repo is unreachable would be a far worse
#      outcome than publishing the committed output, which step 1 just proved
#      honest.
#
# If the rebuild produces something different from what is committed, the FRESH
# output is what deploys — it is strictly the more correct artifact — and the
# difference is reported in the job summary rather than failing the run.
#
# Rebuild prerequisites: CodeCavePro/codecave.pro must be readable. If it is
# private, add a repo-scoped PAT as the CODECAVE_PRO_TOKEN secret; the default
# GITHUB_TOKEN cannot read another repository.
name: Deploy static content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["development"]

  # 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

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

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

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

      # Runs unconditionally and depends on nothing. If this fails, the
      # committed storybook does not match docs/source_examples/ and whatever
      # we publish would be documenting the wrong site.
      - name: Verify the storybook matches its sources
        run: node docs/tools/check-tw-bridge.mjs

      # The ports typecheck needs typescript, so it cannot go in the
      # dependency-free check above — it goes after it. An adapter that has
      # drifted from the interface its component imports compiles perfectly and
      # fails as an undefined in a reader's browser, which is the one place a
      # specimen must not fail. That is the whole reason ports are typechecked
      # rather than left as stubs, and leaving the check off CI would give the
      # rot back.
      - name: Install the brand toolchain
        run: npm ci

      - name: Typecheck the storybook ports
        run: npm run check:ports

      # Both inputs are in this checkout — source_examples/ is committed, and
      # Tailwind's default theme comes from a devDependency pinned to the
      # version the site resolves — so unlike check:captures this one needs no
      # site checkout and belongs in CI. It catches a token that would silently
      # redefine a Tailwind default in every consumer's app, which nothing
      # about the docs build or the package build would ever notice.
      - name: Check the token layer against Tailwind
        run: npm run check:collisions

      # ---- optional rebuild ------------------------------------------------
      # continue-on-error so an unreachable or private codecave.pro downgrades
      # this workflow to "publish the verified committed output" instead of
      # taking the site down.
      # Which of the two skip reasons applies is otherwise unknowable from
      # outside. `secrets.CODECAVE_PRO_TOKEN || github.token` falls back
      # silently, and continue-on-error rewrites the checkout's conclusion to
      # `success`, so the jobs API shows a green step followed by four skipped
      # ones and no way to tell "no secret configured" from "secret configured
      # but it cannot read the repo". Both also take ~30s, because checkout
      # retries auth failures — so duration does not separate them either.
      #
      # This reads the length of the secret and nothing else. The value never
      # reaches a log: it is bound to an env var, tested with -n, and only the
      # boolean is written to the step output.
      - name: Is a site token configured
        id: sitetoken
        env:
          TOKEN: ${{ secrets.CODECAVE_PRO_TOKEN }}
        run: |
          if [ -n "$TOKEN" ]; then
            echo "configured=true" >> "$GITHUB_OUTPUT"
          else
            echo "configured=false" >> "$GITHUB_OUTPUT"
          fi

      - name: Check out the codecave.pro toolchain
        id: toolchain
        continue-on-error: true
        uses: actions/checkout@v4
        with:
          repository: CodeCavePro/codecave.pro
          path: _toolchain
          token: ${{ secrets.CODECAVE_PRO_TOKEN || github.token }}
          persist-credentials: false

      - name: Setup pnpm
        if: steps.toolchain.outcome == 'success'
        uses: pnpm/action-setup@v4
        with:
          version: 10

      # node-linker=hoisted gives a flat, npm-shaped node_modules. The
      # generator resolves esbuild from the top level, and esbuild is only a
      # transitive dependency there — under pnpm's default layout it would sit
      # in .pnpm/ and not resolve at all.
      - name: Install the site toolchain
        if: steps.toolchain.outcome == 'success'
        working-directory: _toolchain
        run: pnpm install --frozen-lockfile --config.node-linker=hoisted --ignore-scripts=false

      - name: Rebuild the storybook
        if: steps.toolchain.outcome == 'success'
        run: node docs/tools/build-storybook.mjs _toolchain

      # The generator pins esbuild's absWorkingDir, so unchanged sources
      # reproduce byte-identical output regardless of where it ran. Anything
      # reported here is a real difference between the committed storybook and
      # a fresh build with the site's current toolchain.
      - name: Report any rebuild drift
        if: steps.toolchain.outcome == 'success'
        run: |
          if git diff --quiet -- docs/storybook; then
            echo "Rebuilt storybook is identical to the committed output." >> "$GITHUB_STEP_SUMMARY"
          else
            {
              echo "### Storybook rebuild differs from the committed output"
              echo ""
              echo "The freshly built files are what this run publishes. Regenerate and commit to clear this:"
              echo ""
              echo '```'
              echo "node docs/tools/build-storybook.mjs ../codecave.pro"
              echo '```'
              echo ""
              echo '```diff'
              git diff --stat -- docs/storybook
              echo '```'
            } >> "$GITHUB_STEP_SUMMARY"
          fi

      - name: Note a skipped rebuild
        if: steps.toolchain.outcome != 'success'
        env:
          CONFIGURED: ${{ steps.sitetoken.outputs.configured }}
        run: |
          # Also as an annotation. The step summary above is the readable
          # version, but it takes repo access and a browser to see; an
          # annotation hangs off the commit and is served by the public REST
          # API, so the state is checkable from anywhere — including from a
          # machine that is trying to work out why the secret it just added
          # changed nothing.
          echo "::notice title=Storybook rebuild skipped::CODECAVE_PRO_TOKEN configured=$CONFIGURED; the codecave.pro checkout was refused. See the run summary for what to check."
          {
            echo "### Storybook rebuild skipped"
            echo ""
            echo "\`CodeCavePro/codecave.pro\` could not be checked out, so the storybook was not"
            echo "rebuilt. The committed output was verified against \`docs/source_examples/\` and"
            echo "published as-is. **This is a downgrade, not a failure** — the deploy is unaffected."
            echo ""
            if [ "$CONFIGURED" = "true" ]; then
              echo "\`CODECAVE_PRO_TOKEN\` **is set**, so the token itself was refused. Check, in"
              echo "the order these actually go wrong:"
              echo ""
              echo "1. **Org approval.** A fine-grained PAT against an organisation repo starts"
              echo "   life pending and reads nothing until an owner approves it."
              echo "2. **Repository access** lists \`CodeCavePro/codecave.pro\`. \"All repositories\""
              echo "   under the wrong resource owner is the common near-miss — the owner must be"
              echo "   **CodeCavePro**, not the personal account."
              echo "3. **Permissions** include \`Contents: Read-only\`. Nothing else is needed."
              echo "4. **Expiry.** A lapsed PAT lands here and looks exactly like this."
              echo ""
              echo "A classic PAT with the \`repo\` scope also works and skips 1–3, at the cost of"
              echo "being far broader than this needs."
            else
              echo "\`CODECAVE_PRO_TOKEN\` **is not set** on this repository, so the checkout fell"
              echo "back to \`github.token\`, which is scoped to \`CodeCavePro/brand\` alone and"
              echo "cannot read a different private repo."
              echo ""
              echo "Add it under Settings -> Secrets and variables -> Actions as a **repository"
              echo "secret** (not a variable, and not an environment secret — this job declares no"
              echo "environment, so an environment-scoped secret arrives empty and lands here)."
            fi
          } >> "$GITHUB_STEP_SUMMARY"

      # ---- build the site --------------------------------------------------
      # LAST, deliberately. The storybook rebuild above writes into
      # docs/storybook/, so building before it would publish the previous run's
      # output. Everything this step needs is in this checkout — see
      # astro.config.mjs — so an unreachable codecave.pro cannot reach it, and
      # the safety property in this file's header survives the migration: a
      # neighbouring repo going private must never take this site down.
      #
      # The build fails if dist/ is not a superset of docs/. That matters more
      # than usual while the migration is half-done, because most pages reach
      # the site by being COPIED and only a few by being rendered — so a
      # passthrough that silently stopped would deploy a site missing almost
      # every page, with a green tick. See docs/tools/astro-passthrough.mjs.
      - name: Build the docs site
        run: npm run docs:build

      # ---- publish ---------------------------------------------------------
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload artifact
        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
    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