release.yml

name: Release

on:
  push:
    tags:
      - 'v*.*.*'
      - 'v*.*.*-*'
      - 'extensions/*/v*.*.*'
      - 'extensions/*/v*.*.*-*'
  workflow_dispatch:
    inputs:
      module:
        description: 'Module to release'
        required: true
        type: choice
        options:
          - forge
          - forge-library
          - cli
          - all
          - auth
          - cache
          - consensus
          - conduit
          - discovery
          - events
          - features
          - graphql
          - grpc
          - hls
          - kafka
          - mcp
          - mqtt
          - orpc
          - queue
          - search
          - security
          - streaming
          - webrtc
      version:
        description: 'Semantic version to release (e.g. 1.2.3 or 1.0.0-beta.1)'
        required: true
        type: string
      source_commit:
        description: 'Pinned source for library/extension releases. Empty uses the selected workflow ref.'
        required: false
        type: string
        default: ''
      dry_run:
        description: 'Dry run — validate everything but do not publish'
        required: false
        type: boolean
        default: false
      skip_tests:
        description: 'Skip tests (use for hotfixes when tests already passed)'
        required: false
        type: boolean
        default: false
      prerelease:
        description: 'Mark as a pre-release'
        required: false
        type: boolean
        default: false

permissions:
  contents: write
  packages: write
  id-token: write

defaults:
  run:
    shell: bash

env:
  # Every extension "all" mode tags. Removed extensions are not listed: ai,
  # cron, database, gateway and storage are migration notes now, with no
  # go.mod to tag. The version-reuse guard and the tag step both read this, so
  # the guard checks exactly the tags the step would create.
  RELEASE_EXTENSIONS: >-
    auth cache consensus conduit discovery events features graphql grpc hls kafka
    mcp mqtt orpc queue search security streaming webrtc

# -------------------------------------------------------------------
# Job: detect
# Normalises inputs from both tag-push and workflow_dispatch triggers
# into a single set of outputs consumed by downstream jobs.
# -------------------------------------------------------------------
jobs:
  detect:
    name: Detect release parameters
    runs-on: ubuntu-latest
    outputs:
      module_type: ${{ steps.resolve.outputs.module_type }}
      module_name: ${{ steps.resolve.outputs.module_name }}
      module_path: ${{ steps.resolve.outputs.module_path }}
      module_import: ${{ steps.resolve.outputs.module_import }}
      version: ${{ steps.resolve.outputs.version }}
      tag: ${{ steps.resolve.outputs.tag }}
      is_prerelease: ${{ steps.resolve.outputs.is_prerelease }}
      dry_run: ${{ steps.resolve.outputs.dry_run }}
      skip_tests: ${{ steps.resolve.outputs.skip_tests }}
      is_all: ${{ steps.resolve.outputs.is_all }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v7
        with:
          fetch-depth: 0
          ref: ${{ inputs.source_commit || github.ref }}

      - name: Resolve release parameters
        id: resolve
        env:
          SOURCE_COMMIT: ${{ inputs.source_commit }}
        run: |
          DRY_RUN="false"
          SKIP_TESTS="false"
          IS_ALL="false"

          # ---- workflow_dispatch path ----
          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
            MODULE="${{ inputs.module }}"
            VERSION="${{ inputs.version }}"
            DRY_RUN="${{ inputs.dry_run }}"
            SKIP_TESTS="${{ inputs.skip_tests }}"
            IS_PRERELEASE="${{ inputs.prerelease }}"

            # Validate semver
            if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then
              echo "::error::Invalid semantic version: $VERSION (expected N.N.N or N.N.N-pre)"
              exit 1
            fi

            if [ -n "$SOURCE_COMMIT" ] && [[ "$MODULE" =~ ^(forge|cli|all)$ ]]; then
              echo "::error::Pinned sources are supported for library and extension releases only."
              exit 1
            fi

            if [ "$MODULE" = "all" ]; then
              # "all" releases the main module + CLI + every extension at the same version
              IS_ALL="true"
              MODULE_TYPE="main"
              MODULE_NAME="forge"
              MODULE_PATH="."
              MODULE_IMPORT="github.com/xraph/forge"
              TAG="v${VERSION}"
            elif [ "$MODULE" = "forge" ]; then
              MODULE_TYPE="main"
              MODULE_NAME="forge"
              MODULE_PATH="."
              MODULE_IMPORT="github.com/xraph/forge"
              TAG="v${VERSION}"
            elif [ "$MODULE" = "forge-library" ]; then
              MODULE_TYPE="library"
              MODULE_NAME="forge"
              MODULE_PATH="."
              MODULE_IMPORT="github.com/xraph/forge"
              TAG="v${VERSION}"
            elif [ "$MODULE" = "cli" ]; then
              # "cli" releases only the CLI binary (GoReleaser) — no Go module publish
              MODULE_TYPE="cli"
              MODULE_NAME="forge-cli"
              MODULE_PATH="cmd/forge"
              MODULE_IMPORT="github.com/xraph/forge/cmd/forge"
              TAG="v${VERSION}"
            else
              MODULE_TYPE="extension"
              MODULE_NAME="$MODULE"
              MODULE_PATH="extensions/$MODULE"
              MODULE_IMPORT="github.com/xraph/forge/extensions/$MODULE"
              TAG="extensions/${MODULE}/v${VERSION}"
            fi

            # Auto-detect prerelease from version string
            if [[ "$VERSION" == *"-"* ]]; then
              IS_PRERELEASE="true"
            fi

          # ---- tag push path ----
          else
            TAG="${GITHUB_REF#refs/tags/}"

            if [[ "$TAG" =~ ^extensions/([^/]+)/v(.+)$ ]]; then
              MODULE_TYPE="extension"
              MODULE_NAME="${BASH_REMATCH[1]}"
              VERSION="${BASH_REMATCH[2]}"
              MODULE_PATH="extensions/$MODULE_NAME"
              MODULE_IMPORT="github.com/xraph/forge/extensions/$MODULE_NAME"
            elif [[ "$TAG" =~ ^v(.+)$ ]]; then
              MODULE_TYPE="main"
              MODULE_NAME="forge"
              VERSION="${BASH_REMATCH[1]}"
              MODULE_PATH="."
              MODULE_IMPORT="github.com/xraph/forge"
            else
              echo "::error::Unrecognised tag format: $TAG"
              exit 1
            fi

            if [[ "$VERSION" == *"-"* ]]; then
              IS_PRERELEASE="true"
            else
              IS_PRERELEASE="false"
            fi
          fi

          # Verify module directory exists
          if [ ! -f "$MODULE_PATH/go.mod" ]; then
            echo "::error::go.mod not found at $MODULE_PATH"
            exit 1
          fi

          # Emit outputs
          {
            echo "module_type=$MODULE_TYPE"
            echo "module_name=$MODULE_NAME"
            echo "module_path=$MODULE_PATH"
            echo "module_import=$MODULE_IMPORT"
            echo "version=$VERSION"
            echo "tag=$TAG"
            echo "is_prerelease=$IS_PRERELEASE"
            echo "dry_run=$DRY_RUN"
            echo "skip_tests=$SKIP_TESTS"
            echo "is_all=$IS_ALL"
          } >> "$GITHUB_OUTPUT"

          {
            echo "### Release Parameters"
            echo "| Key | Value |"
            echo "|-----|-------|"
            echo "| Module | \`$MODULE_NAME\` ($MODULE_TYPE) |"
            echo "| Version | \`$VERSION\` |"
            echo "| Tag | \`$TAG\` |"
            echo "| Import | \`$MODULE_IMPORT\` |"
            echo "| Pre-release | $IS_PRERELEASE |"
            echo "| Dry run | $DRY_RUN |"
            echo "| Skip tests | $SKIP_TESTS |"
            echo "| Release all | $IS_ALL |"
          } >> "$GITHUB_STEP_SUMMARY"

      # A version is used once. On 2026-10-08 a dispatch of 1.12.1, a version
      # whose tag already existed at an older commit, skipped the main tag,
      # tagged all 18 extensions at that day's main instead of the release
      # commit, and pushed them. The proxy serves those now and they cannot be
      # taken back. GoReleaser then found only extension tags on HEAD and
      # failed on "extensions/webrtc/v1.12.1" as a version.
      #
      # So before anything is tagged: every tag this run would create must be
      # absent, or already point at the checked-out commit. The second case is
      # a re-run of the same release and stays allowed, since it creates
      # nothing new. To redo a release whose tag exists, run this workflow on
      # the tag itself ("Use workflow from" the tag), not on a branch.
      #
      # It runs on dry runs too, so a rehearsal catches a taken version. The
      # tags come from the checkout above, whose fetch-depth: 0 fetches them all.
      # .github/scripts/test_release_workflow.py runs this shell against a
      # scratch repository.
      - name: Guard against version reuse
        if: github.event_name == 'workflow_dispatch'
        env:
          TAG: ${{ steps.resolve.outputs.tag }}
          VERSION: ${{ steps.resolve.outputs.version }}
          IS_ALL: ${{ steps.resolve.outputs.is_all }}
        run: |
          set -euo pipefail

          HEAD_SHA=$(git rev-parse HEAD)
          WANTED=("$TAG")
          if [ "$IS_ALL" = "true" ]; then
            read -ra EXTENSIONS <<< "$RELEASE_EXTENSIONS"
            for ext in "${EXTENSIONS[@]}"; do
              WANTED+=("extensions/${ext}/v${VERSION}")
            done
          fi

          TAKEN=0
          for t in "${WANTED[@]}"; do
            if sha=$(git rev-parse -q --verify "refs/tags/${t}^{commit}"); then
              if [ "$sha" = "$HEAD_SHA" ]; then
                echo "Tag $t already points at HEAD ($HEAD_SHA); this is a re-run of the same release."
              else
                echo "::error::Tag $t already exists at $sha, not at the checked-out commit $HEAD_SHA."
                TAKEN=$((TAKEN + 1))
              fi
            fi
          done

          if [ "$TAKEN" -gt 0 ]; then
            echo "::error::Version $VERSION is already taken by $TAKEN tag(s) at another commit, so nothing was tagged or pushed. Release a new version, or run this workflow on $TAG itself to repeat that release."
            exit 1
          fi
          echo "No tag for $VERSION points anywhere but HEAD ($HEAD_SHA)."

      # Creates the main tag at HEAD, and in "all" mode every extension tag at
      # that same commit, then pushes only the tags it created, in one atomic
      # push. The guard above has already refused any tag at another commit.
      - name: Create tags (manual dispatch)
        if: github.event_name == 'workflow_dispatch' && steps.resolve.outputs.dry_run == 'false'
        env:
          TAG: ${{ steps.resolve.outputs.tag }}
          VERSION: ${{ steps.resolve.outputs.version }}
          IS_ALL: ${{ steps.resolve.outputs.is_all }}
        run: |
          set -euo pipefail

          HEAD_SHA=$(git rev-parse HEAD)
          NEW=()

          if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
            echo "Tag $TAG already exists at HEAD; not creating it again."
          else
            git tag "$TAG" "$HEAD_SHA"
            NEW+=("refs/tags/$TAG")
          fi

          # Every extension tag goes on the main tag's commit. Checked again
          # here so a later edit to the guard cannot quietly tag elsewhere.
          TARGET=$(git rev-parse "refs/tags/${TAG}^{commit}")
          if [ "$TARGET" != "$HEAD_SHA" ]; then
            echo "::error::$TAG points at $TARGET, not HEAD $HEAD_SHA. Refusing to tag."
            exit 1
          fi

          if [ "$IS_ALL" = "true" ]; then
            read -ra EXTENSIONS <<< "$RELEASE_EXTENSIONS"
            for ext in "${EXTENSIONS[@]}"; do
              EXT_TAG="extensions/${ext}/v${VERSION}"
              if git rev-parse -q --verify "refs/tags/$EXT_TAG" >/dev/null; then
                echo "Tag $EXT_TAG already exists at HEAD; not creating it again."
              else
                git tag "$EXT_TAG" "$TARGET"
                NEW+=("refs/tags/$EXT_TAG")
              fi
            done
          fi

          if [ "${#NEW[@]}" -eq 0 ]; then
            echo "Every tag already exists at HEAD; nothing to push."
          else
            # Named refs only. `git push --tags` would also push any stray
            # local tag the runner happens to hold.
            git push --atomic origin "${NEW[@]}"
            printf 'Pushed %s\n' "${NEW[@]}"
          fi

  # -------------------------------------------------------------------
  # Job: test
  # Runs tests for the module being released (skippable).
  # -------------------------------------------------------------------
  test:
    name: Test (${{ matrix.os }})
    needs: detect
    if: needs.detect.outputs.skip_tests == 'false'
    runs-on: ${{ matrix.os }}
    timeout-minutes: 30
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest]
    steps:
      - name: Checkout code
        uses: actions/checkout@v7
        with:
          ref: ${{ inputs.source_commit || github.ref }}

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version-file: ${{ needs.detect.outputs.module_path }}/go.mod
          check-latest: true

      - name: Cache Go modules
        uses: actions/cache@v4
        with:
          path: |
            ~/go/pkg/mod
            ~/.cache/go-build
          key: ${{ runner.os }}-go-${{ needs.detect.outputs.module_name }}-${{ hashFiles(format('{0}/go.sum', needs.detect.outputs.module_path)) }}
          restore-keys: |
            ${{ runner.os }}-go-${{ needs.detect.outputs.module_name }}-

      # The TypeScript generator tests shell out to tsc and esbuild. ubuntu
      # images happen to ship tsc globally; macOS images do not, and the
      # helper's `npx --no-install tsc` fallback then resolves the unrelated
      # `tsc` npm package and fails every type-check test. Pin the same
      # toolchain go.yml provisions so both legs run the same gate.
      - name: Set up Node
        uses: actions/setup-node@v7
        with:
          node-version: '24'

      - name: Install TypeScript toolchain
        run: npm install -g typescript@5.8.2 esbuild@0.28.1

      - name: Run tests
        run: |
          cd ${{ needs.detect.outputs.module_path }}
          go mod download
          go list ./... | grep -v '/bk/' > "$RUNNER_TEMP/release-packages.txt"
          packages=()
          while IFS= read -r package; do
            packages+=("$package")
          done < "$RUNNER_TEMP/release-packages.txt"
          go test -v -race -timeout=15m "${packages[@]}"

  # -------------------------------------------------------------------
  # Job: release-cli
  # Runs GoReleaser for main module releases (CLI binaries + Docker).
  # Uses the existing .goreleaser.yml without modifications.
  # -------------------------------------------------------------------
  release-cli:
    name: Release CLI (GoReleaser)
    needs: [detect, test]
    if: |
      always() &&
      (needs.detect.outputs.module_type == 'main' || needs.detect.outputs.module_type == 'cli') &&
      needs.detect.outputs.dry_run == 'false' &&
      needs.detect.result == 'success' &&
      (needs.test.result == 'success' || needs.test.result == 'skipped')
    permissions:
      contents: write
      packages: write
    uses: xraph/workflows/.github/workflows/go-binary-release.yml@v1
    with:
      # Read the version from go.mod rather than duplicating it here.
      go-version-file: go.mod
      # TEMPORARY: container images are skipped, so the CLI release can ship.
      #
      # go-binary-release.yml's `goreleaser` job declares `permissions: contents:
      # write` and nothing else, and once a permissions block exists everything
      # unlisted is `none` -- so its GITHUB_TOKEN has `packages: none`. The
      # called workflow's block is the authoritative one for its own jobs, so the
      # `packages: write` this job declares below cannot widen it. The push then
      # fails with
      #
      #   denied: installation not allowed to Write organization package
      #
      # after a full six-minute build. Granting the repo write access on the
      # GHCR package does not help either: the token has no packages scope to
      # exercise in the first place.
      #
      # `docker: false` alone would make it worse, not better -- that input only
      # skips QEMU, Buildx and the registry *login*, while .goreleaser.yml still
      # has dockers/docker_manifests, so GoReleaser would build the images and
      # push them unauthenticated. The pipe has to be skipped in GoReleaser
      # itself, and then the setup steps are simply unnecessary.
      #
      # Revert both lines once xraph/workflows grants `packages: write` and its
      # v1 tag moves: https://github.com/xraph/workflows/pull/1
      docker: false
      registry: ghcr.io
      goreleaser-version: '~> v2'
      goreleaser-args: 'release --clean --skip=docker'
    secrets:
      GORELEASER_TOKEN: ${{ secrets.GORELEASER_TOKEN }}
      FURY_TOKEN: ${{ secrets.FURY_TOKEN }}
      AUR_KEY: ${{ secrets.AUR_KEY }}

  # -------------------------------------------------------------------
  # Job: release-module
  # Creates a GitHub release and notifies the Go proxy.
  # Runs for ALL release types (main & extension).
  # For main, this runs in addition to release-cli.
  # For extensions, this is the only release step.
  # -------------------------------------------------------------------
  release-module:
    name: Publish Go module
    needs: [detect, test]
    if: |
      always() &&
      needs.detect.outputs.module_type != 'cli' &&
      needs.detect.outputs.dry_run == 'false' &&
      needs.detect.result == 'success' &&
      (needs.test.result == 'success' || needs.test.result == 'skipped')
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v7
        with:
          ref: ${{ inputs.source_commit || github.ref }}

      # Library and extension releases publish Go modules; GoReleaser handles the CLI.
      - name: Create GitHub Release (extensions)
        if: needs.detect.outputs.module_type == 'extension' || needs.detect.outputs.module_type == 'library'
        uses: softprops/action-gh-release@v2
        with:
          tag_name: ${{ needs.detect.outputs.tag }}
          name: "${{ needs.detect.outputs.module_name }} v${{ needs.detect.outputs.version }}"
          body: |
            ## ${{ needs.detect.outputs.module_name }} v${{ needs.detect.outputs.version }}

            **Module**: `${{ needs.detect.outputs.module_import }}`

            ### Installation

            ```bash
            go get ${{ needs.detect.outputs.module_import }}@v${{ needs.detect.outputs.version }}
            ```

            ### Documentation

            - [pkg.go.dev](https://pkg.go.dev/${{ needs.detect.outputs.module_import }}@v${{ needs.detect.outputs.version }})
          draft: false
          make_latest: ${{ needs.detect.outputs.module_type == 'library' && 'false' || 'legacy' }}
          prerelease: ${{ needs.detect.outputs.is_prerelease == 'true' }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Notify Go proxy
        run: |
          MODULE="${{ needs.detect.outputs.module_import }}"
          TAG="v${{ needs.detect.outputs.version }}"
          echo "Requesting Go proxy to cache $MODULE@$TAG"
          sleep 5
          curl -sf "https://proxy.golang.org/${MODULE}/@v/${TAG}.info" || \
            echo "Go proxy notification failed (normal for private repos)"

  # -------------------------------------------------------------------
  # Job: trigger-publish
  # Starts npm-publish.yml and dart-publish.yml for a dispatched release.
  #
  # A tag a human pushes starts both of them by itself. The tag this
  # workflow's detect job pushes does not: it is pushed with GITHUB_TOKEN, and
  # GitHub starts no workflow from a GITHUB_TOKEN push. workflow_dispatch is
  # the exception to that rule, so this job dispatches both on the release
  # tag, which is exactly the run a tag push would have produced (dart-publish
  # accepts a real publish from a dispatch only on refs/tags/vX.Y.Z).
  #
  # Why not push the tag with a PAT (secrets.GORELEASER_TOKEN, which GoReleaser
  # already uses for the tap and bucket) so the push itself triggers them? A
  # PAT push also starts this very workflow's `push: tags` trigger, so every
  # dispatched release would run a second, competing release from the tag, and
  # in "all" mode 18 more for the extension tags. It would also make
  # publishing depend on a secret nobody can read to confirm its scope.
  # Dispatching needs only `actions: write` on GITHUB_TOKEN.
  #
  # pub.dev: a dispatch-started upload is refused unless "Enable publishing
  # from workflow_dispatch events" is ticked on each package's automated
  # publishing settings, next to the tag pattern.
  #
  # Both publish workflows are safe to start twice for the same tag: dart
  # skips versions already on pub.dev, npm skips a tag whose packages are all
  # on npm, and each queues behind an earlier run for the same ref.
  # Prereleases are left alone, as the tag triggers ignore them too.
  # -------------------------------------------------------------------
  trigger-publish:
    name: Start npm and pub.dev publishing
    needs: [detect, test]
    if: |
      always() &&
      github.event_name == 'workflow_dispatch' &&
      needs.detect.outputs.module_type == 'main' &&
      needs.detect.outputs.dry_run == 'false' &&
      needs.detect.result == 'success' &&
      (needs.test.result == 'success' || needs.test.result == 'skipped')
    runs-on: ubuntu-latest
    permissions:
      actions: write
    steps:
      - name: Dispatch the publish workflows on the release tag
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GH_REPO: ${{ github.repository }}
          TAG: ${{ needs.detect.outputs.tag }}
          VERSION: ${{ needs.detect.outputs.version }}
        run: |
          set -euo pipefail

          if [[ "$VERSION" == *[-+]* ]]; then
            echo "::notice::$VERSION is a prerelease; npm and pub.dev publish stable tags only. Nothing dispatched."
            exit 0
          fi

          for wf in npm-publish.yml dart-publish.yml; do
            gh workflow run "$wf" --ref "$TAG" -f dry-run=false -f version="$VERSION"
            echo "Started $wf on $TAG at version $VERSION." | tee -a "$GITHUB_STEP_SUMMARY"
          done

  # -------------------------------------------------------------------
  # Job: dry-run
  # Validates the release pipeline without publishing anything.
  # -------------------------------------------------------------------
  dry-run:
    name: Dry run
    needs: [detect, test]
    if: |
      always() &&
      needs.detect.outputs.dry_run == 'true' &&
      needs.detect.result == 'success' &&
      (needs.test.result == 'success' || needs.test.result == 'skipped')
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v7
        with:
          fetch-depth: 0
          ref: ${{ inputs.source_commit || github.ref }}

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version-file: ${{ needs.detect.outputs.module_path }}/go.mod

      - name: Validate module builds
        run: |
          set -euo pipefail

          MODULE_PATH="${{ needs.detect.outputs.module_path }}"

          # cmd/forge pins the last PUBLISHED github.com/xraph/forge, because its
          # go.mod has to stay free of replace directives for
          # `go install ...@latest` to accept it. Built standalone it therefore
          # compiles against the released root module rather than this tree, and
          # any root API this tag adds but has not published yet fails here as
          # "undefined" -- a dry run reporting a break the real release does not
          # have, since .goreleaser.yml's first before-hook sets up the same
          # workspace for the build itself. Every other module carries its own
          # replace directive and resolves the root locally without help.
          #
          # The workfile lives OUTSIDE the repo on purpose: a go.work at the root
          # would apply to every module, and the ones it does not list would fail
          # with "directory prefix ... does not contain modules listed in
          # go.work". Everything else is built with GOWORK=off so each module is
          # still checked standalone.
          case "$MODULE_PATH" in
            cmd/forge)
              WORKFILE="${RUNNER_TEMP:-/tmp}/forge-release.work"
              rm -f "$WORKFILE"
              GOWORK="$WORKFILE" go work init \
                "$GITHUB_WORKSPACE" \
                "$GITHUB_WORKSPACE/cmd/forge"
              cd "$MODULE_PATH"
              GOWORK="$WORKFILE" go build ./...
              ;;
            *)
              cd "$MODULE_PATH"
              GOWORK=off go build ./...
              ;;
          esac

      - name: GoReleaser dry run (main/cli only)
        if: needs.detect.outputs.module_type == 'main' || needs.detect.outputs.module_type == 'cli'
        uses: goreleaser/goreleaser-action@v6
        with:
          distribution: goreleaser
          version: '~> v2'
          args: release --snapshot --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Dry run summary
        run: |
          {
            echo "### Dry Run Complete"
            echo ""
            echo "Module **${{ needs.detect.outputs.module_name }}** v${{ needs.detect.outputs.version }} validated successfully."
            echo "No artifacts were published."
          } >> "$GITHUB_STEP_SUMMARY"

  # -------------------------------------------------------------------
  # Job: summary
  # Provides a unified release summary.
  # -------------------------------------------------------------------
  summary:
    name: Release summary
    needs: [detect, test, release-cli, release-module, trigger-publish, dry-run]
    if: always()
    runs-on: ubuntu-latest
    steps:
      - name: Generate summary
        run: |
          MODULE="${{ needs.detect.outputs.module_name }}"
          VERSION="${{ needs.detect.outputs.version }}"
          TAG="${{ needs.detect.outputs.tag }}"
          TYPE="${{ needs.detect.outputs.module_type }}"
          IMPORT="${{ needs.detect.outputs.module_import }}"
          DRY="${{ needs.detect.outputs.dry_run }}"

          {
            echo "# Release Summary"
            echo ""

            if [ "$DRY" = "true" ]; then
              echo "> **Dry run** — nothing was published."
              echo ""
            fi

            echo "| Key | Value |"
            echo "|-----|-------|"
            echo "| Module | \`$MODULE\` ($TYPE) |"
            echo "| Version | \`$VERSION\` |"
            echo "| Tag | \`$TAG\` |"

            if [ "$DRY" != "true" ]; then
              echo ""
              echo "## Installation"
              echo ""
              if [ "$TYPE" = "main" ] || [ "$TYPE" = "cli" ]; then
                echo '```bash'
                echo "go install github.com/xraph/forge/cmd/forge@${TAG}"
                echo '```'
              else
                echo '```bash'
                echo "go get ${IMPORT}@${TAG}"
                echo '```'
              fi
            fi

            echo ""
            echo "## Job Results"
            echo ""
            echo "| Job | Status |"
            echo "|-----|--------|"
            echo "| Detect | ${{ needs.detect.result }} |"
            echo "| Test | ${{ needs.test.result }} |"
            echo "| CLI Release | ${{ needs.release-cli.result }} |"
            echo "| Module Release | ${{ needs.release-module.result }} |"
            echo "| Publish Dispatch | ${{ needs.trigger-publish.result }} |"
            echo "| Dry Run | ${{ needs.dry-run.result }} |"
          } >> "$GITHUB_STEP_SUMMARY"

  # -------------------------------------------------------------------
  # Job: update-changelog
  # Generates changelog from git log and commits to main branch.
  # Only runs for main module releases (not extensions or dry runs).
  # -------------------------------------------------------------------
  update-changelog:
    name: Update CHANGELOG.md
    needs: [detect, test, release-cli, release-module]
    if: |
      always() &&
      needs.detect.outputs.module_type == 'main' &&
      needs.detect.outputs.dry_run == 'false' &&
      needs.detect.result == 'success' &&
      (needs.release-cli.result == 'success' || needs.release-cli.result == 'skipped') &&
      (needs.release-module.result == 'success' || needs.release-module.result == 'skipped')
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v7
        with:
          fetch-depth: 0
          ref: main
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Generate changelog entry
        run: |
          VERSION="${{ needs.detect.outputs.version }}"
          TAG="${{ needs.detect.outputs.tag }}"
          DATE=$(date -u +%Y-%m-%d)

          # Find previous tag for this module
          PREV_TAG=$(git tag --sort=-v:refname | grep -E '^v[0-9]' | awk -v t="$TAG" 'found{print;exit} $0==t{found=1}')

          if [ -z "$PREV_TAG" ]; then
            echo "No previous tag found — skipping changelog generation"
            echo "SKIP_CHANGELOG=true" >> "$GITHUB_ENV"
            exit 0
          fi

          echo "Generating changelog for $TAG (since $PREV_TAG)"

          # Collect commits between tags (exclude extensions/ and docs/ directories)
          COMMITS=$(git log --oneline --no-merges "$PREV_TAG..$TAG" -- . ':!extensions' ':!docs' 2>/dev/null || true)

          if [ -z "$COMMITS" ]; then
            echo "No commits found — creating minimal entry"
            COMMITS="* Minor updates and improvements"
          fi

          # Categorise commits by conventional commit type
          FEATURES=""
          FIXES=""
          REFACTORS=""
          BREAKING=""
          MAINTENANCE=""

          while IFS= read -r line; do
            [ -z "$line" ] && continue
            HASH=$(echo "$line" | awk '{print $1}')
            MSG=$(echo "$line" | cut -d' ' -f2-)

            case "$MSG" in
              feat*)
                SCOPE=$(echo "$MSG" | sed -n 's/^feat(\([^)]*\)).*/\1/p')
                DESC=$(echo "$MSG" | sed 's/^feat([^)]*): //' | sed 's/^feat: //')
                if [ -n "$SCOPE" ]; then
                  FEATURES="${FEATURES}* **${SCOPE}:** ${DESC} ([${HASH}](https://github.com/xraph/forge/commit/${HASH}))\n"
                else
                  FEATURES="${FEATURES}* ${DESC} ([${HASH}](https://github.com/xraph/forge/commit/${HASH}))\n"
                fi
                ;;
              fix*)
                SCOPE=$(echo "$MSG" | sed -n 's/^fix(\([^)]*\)).*/\1/p')
                DESC=$(echo "$MSG" | sed 's/^fix([^)]*): //' | sed 's/^fix: //')
                if [ -n "$SCOPE" ]; then
                  FIXES="${FIXES}* **${SCOPE}:** ${DESC} ([${HASH}](https://github.com/xraph/forge/commit/${HASH}))\n"
                else
                  FIXES="${FIXES}* ${DESC} ([${HASH}](https://github.com/xraph/forge/commit/${HASH}))\n"
                fi
                ;;
              refactor*)
                SCOPE=$(echo "$MSG" | sed -n 's/^refactor(\([^)]*\)).*/\1/p')
                DESC=$(echo "$MSG" | sed 's/^refactor([^)]*): //' | sed 's/^refactor: //')
                if [ -n "$SCOPE" ]; then
                  REFACTORS="${REFACTORS}* **${SCOPE}:** ${DESC} ([${HASH}](https://github.com/xraph/forge/commit/${HASH}))\n"
                else
                  REFACTORS="${REFACTORS}* ${DESC} ([${HASH}](https://github.com/xraph/forge/commit/${HASH}))\n"
                fi
                ;;
              *"BREAKING"*|*"breaking"*)
                BREAKING="${BREAKING}* ${MSG}\n"
                ;;
              *)
                SCOPE=$(echo "$MSG" | sed -n 's/^[a-z]*(\([^)]*\)).*/\1/p')
                DESC=$(echo "$MSG" | sed 's/^[a-z]*([^)]*): //' | sed 's/^[a-z]*: //')
                if [ -n "$SCOPE" ]; then
                  MAINTENANCE="${MAINTENANCE}* **${SCOPE}:** ${DESC} ([${HASH}](https://github.com/xraph/forge/commit/${HASH}))\n"
                else
                  MAINTENANCE="${MAINTENANCE}* ${DESC} ([${HASH}](https://github.com/xraph/forge/commit/${HASH}))\n"
                fi
                ;;
            esac
          done <<< "$COMMITS"

          # Build the changelog entry
          ENTRY="## [${VERSION}](https://github.com/xraph/forge/compare/${PREV_TAG}...v${VERSION}) (${DATE})\n"

          if [ -n "$BREAKING" ]; then
            ENTRY="${ENTRY}\n\n### ⚠ BREAKING CHANGES\n\n${BREAKING}"
          fi
          if [ -n "$FEATURES" ]; then
            ENTRY="${ENTRY}\n\n### Features\n\n${FEATURES}"
          fi
          if [ -n "$FIXES" ]; then
            ENTRY="${ENTRY}\n\n### Bug Fixes\n\n${FIXES}"
          fi
          if [ -n "$REFACTORS" ]; then
            ENTRY="${ENTRY}\n\n### Refactoring\n\n${REFACTORS}"
          fi
          if [ -n "$MAINTENANCE" ]; then
            ENTRY="${ENTRY}\n\n### Maintenance\n\n${MAINTENANCE}"
          fi

          # Check if this version already exists in the changelog
          if grep -q "## \[${VERSION}\]" CHANGELOG.md; then
            echo "Version ${VERSION} already in CHANGELOG.md — skipping"
            echo "SKIP_CHANGELOG=true" >> "$GITHUB_ENV"
            exit 0
          fi

          # Prepend to CHANGELOG.md (after the # Changelog header)
          TMPFILE=$(mktemp)
          {
            printf '# Changelog\n\n'
            printf '%b\n' "$ENTRY"
            tail -n +3 CHANGELOG.md
          } > "$TMPFILE"
          mv "$TMPFILE" CHANGELOG.md

          echo "SKIP_CHANGELOG=false" >> "$GITHUB_ENV"
          echo "Changelog entry generated for v${VERSION}"

      - name: Commit and push changelog
        if: env.SKIP_CHANGELOG != 'true'
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add CHANGELOG.md
          git commit -m "docs(changelog): update CHANGELOG.md for v${{ needs.detect.outputs.version }}"
          git push origin main