ci.yml

name: CI

on:
  push:
    branches: [main]
    paths-ignore:
      # skip verify/test only for NON-shipped docs — a SHIPPED markdown artifact (skills/**/SKILL.md, commands/*.md) MUST run CI (verify checks dist-sync)
      - 'README.md'
      - 'CHANGELOG.md'
      - 'CONTRIBUTING.md'
      - 'PRIVACY.md'
      - 'SECURITY.md'
      - 'LICENSE'
  pull_request:
    branches: [main]
    paths-ignore:
      # skip verify/test only for NON-shipped docs — a SHIPPED markdown artifact (skills/**/SKILL.md, commands/*.md) MUST run CI (verify checks dist-sync)
      - 'README.md'
      - 'CHANGELOG.md'
      - 'CONTRIBUTING.md'
      - 'PRIVACY.md'
      - 'SECURITY.md'
      - 'LICENSE'

permissions:
  contents: read

jobs:
  gate:
    name: gate (${{ matrix.os }} · node ${{ matrix.node }})
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node: [22, 24]  # supported LTS only (24 Active, 22 Maintenance); 18/20 are EOL — bump as the Node LTS schedule moves
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          # 0 = all history for ALL branches AND tags (action.yml @ this pinned tag: "0
          # indicates all history for all branches and tags") — without this, git's
          # shallow default leaves no tag reachable, so task #38's dist-changelog gate
          # (scripts/lib/dist-changelog.mjs) SKIPs on every CI run. fetch-tags is NOT
          # needed alongside this: its own description scopes it to "even if
          # fetch-depth > 0" — the shallow case — which fetch-depth: 0 isn't.
          fetch-depth: 0
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: ${{ matrix.node }}
      # Zero-dependency: no install step. Run the same fail-loud gate as a local pre-push,
      # cross-platform — verify (dist-sync + repo consistency checks) then the test suite.
      # No build step here: rebuilding the dist in CI would mask a stale COMMITTED
      # plugin/ — the exact drift verify exists to catch.
      #
      # GATED ON scripts/verify.mjs EXISTING — a bare "Use this template" click produces
      # a repo with no scripts/ yet (this skeleton ships docs + CI only; the room's own
      # scripts are built after scaffolding), and a hard `node scripts/verify.mjs` on that
      # bare repo is a permanent, self-inflicted red CI run with no fix available to the
      # user who clicked the button. hashFiles() returns '' when the path matches nothing,
      # so the step is cleanly SKIPPED (not silently passed) until the real script lands.
      - name: Verify (skips cleanly until scripts/verify.mjs exists)
        if: hashFiles('scripts/verify.mjs') != ''
        run: node scripts/verify.mjs
      - name: Test (skips cleanly until scripts/test.mjs exists)
        if: hashFiles('scripts/test.mjs') != ''
        run: node scripts/test.mjs
      # PowerShell parity tests (the PS twins of the Node hooks) — pwsh ships on the GitHub
      # runners; skip gracefully if it is ever absent so the node gate above still gates.
      - name: PowerShell parity tests
        shell: bash
        run: |
          if [ ! -f scripts/lib/ps-config.test.ps1 ]; then
            echo "scripts/lib/ps-config.test.ps1 not present yet — skipping PS parity tests"
          elif command -v pwsh >/dev/null 2>&1; then
            pwsh -NoProfile -File scripts/lib/ps-config.test.ps1
            pwsh -NoProfile -File scripts/lib/ps-hooks.test.ps1
          else
            echo "pwsh not found — skipping PS parity tests"
          fi


  # A single STABLE required-check context (the matrix names drift; this does not).
  # Succeeds iff every matrix gate passed or was legitimately skipped; fails if any
  # gate failed. Rulesets require `all-green`, never the per-matrix names.
  all-green:
    name: all-green
    needs: gate
    if: always()
    runs-on: ubuntu-latest
    steps:
      - name: gate result
        run: |
          case "${{ needs.gate.result }}" in
            success|skipped) echo "gate ${{ needs.gate.result }}"; exit 0 ;;
            *) echo "gate ${{ needs.gate.result }}"; exit 1 ;;
          esac