code-npm_node-release-core.yml

# SPDX-FileCopyrightText: 2026 INDUSTRIA DE DISEÑO TEXTIL S.A. (INDITEX S.A.)
# SPDX-License-Identifier: Apache-2.0

name: code-npm-node-release-core

on:
  workflow_call:
    inputs:
      release_type:
        description: Optional release type supplied by the fixed release workflow.
        required: false
        type: string
        default: ''
    outputs:
      release_commit:
        description: Immutable commit used to build the release artifacts.
        value: ${{ jobs.prepare-release.outputs.release_commit }}
      releases:
        description: JSON array of release tags, versions, package lists, and next-dev versions.
        value: ${{ jobs.prepare-release.outputs.releases }}

permissions:
  contents: read

env:
  PROJECT_TYPE: ${{ vars.PROJECT_TYPE }}
  WORKING_DIRECTORY: ${{ vars.WORKING_DIRECTORY }}
  PACKAGE_MANAGER: ${{ vars.PACKAGE_MANAGER }}
  ASDF_BRANCH_VERSION: '0.18.0'

jobs:
  prepare-release:
    name: Prepare Release
    if: >-
      (
        github.event_name == 'workflow_dispatch' &&
        (
          (vars.DEVELOPMENT_FLOW == 'trunk-based-development' && (github.ref_name == 'main' || startsWith(github.ref_name, 'main-'))) ||
          (vars.DEVELOPMENT_FLOW == 'git-flow' && (github.ref_name == 'main' || startsWith(github.ref_name, 'main-')))
        )
      ) ||
      (
        github.event_name == 'pull_request' &&
        github.event.pull_request.merged &&
        !contains(join(github.event.pull_request.labels.*.name, ','), 'skip-release') &&
        (
          (vars.DEVELOPMENT_FLOW == 'trunk-based-development' && (github.event.pull_request.base.ref == 'main' || startsWith(github.event.pull_request.base.ref, 'main-'))) ||
          (vars.DEVELOPMENT_FLOW == 'git-flow' && (github.event.pull_request.base.ref == 'main' || startsWith(github.event.pull_request.base.ref, 'main-')))
        ) &&
        (
          contains(join(github.event.pull_request.labels.*.name, ','), 'release-type') ||
          vars.DEVELOPMENT_FLOW == 'trunk-based-development'
        )
      )
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    outputs:
      release_commit: ${{ steps.release-metadata.outputs.release_commit }}
      releases: ${{ steps.release-metadata.outputs.releases }}
    steps:
      - name: Resolve release context
        id: release-context
        env:
          EVENT_SHA: ${{ github.sha }}
          PR_BASE_BRANCH: ${{ github.event.pull_request.base.ref }}
          PR_LABELS: ${{ join(github.event.pull_request.labels.*.name, ',') }}
          PR_MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}
          REQUESTED_RELEASE_TYPE: ${{ inputs.release_type }}
        shell: bash
        run: |
          set -euo pipefail

          if [[ "$GITHUB_EVENT_NAME" == "workflow_dispatch" ]]; then
            baseline_branch="$GITHUB_REF_NAME"
            release_labels="$REQUESTED_RELEASE_TYPE"
            release_ref="$EVENT_SHA"
          else
            baseline_branch="$PR_BASE_BRANCH"
            release_labels="$PR_LABELS"
            release_ref="$PR_MERGE_SHA"
          fi

          if [[ -z "$baseline_branch" || ! "$release_ref" =~ ^[0-9a-f]{40}$ ]]; then
            echo "::error title=Invalid release context::A baseline branch and immutable release commit are required."
            exit 1
          fi

          {
            echo "baseline_branch=$baseline_branch"
            echo "release_labels=$release_labels"
            echo "release_ref=$release_ref"
          } >> "$GITHUB_OUTPUT"

      - name: Create GitHub App token
        id: app-token
        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
        with:
          client-id: ${{ vars.APP_CLIENT_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
          permission-contents: write
          permission-pull-requests: write

      - name: Check out immutable release source
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false
          ref: ${{ steps.release-context.outputs.release_ref }}
          token: ${{ steps.app-token.outputs.token }}

      - name: Read governed tool versions
        id: tool-versions
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          if grep -Evq '^[a-zA-Z0-9_-]+ [a-zA-Z0-9._+-]+$' .tool-versions; then
            echo "::error title=Invalid tool-versions::${WORKING_DIRECTORY}/.tool-versions is malformed."
            exit 1
          fi
          {
            echo "tool_versions<<EOF"
            cat .tool-versions
            echo
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Set up asdf-managed Node
        uses: asdf-vm/actions/install@b7bcd026f18772e44fe1026d729e1611cc435d47 # v4.0.0
        with:
          tool_versions: ${{ steps.tool-versions.outputs.tool_versions }}
          asdf_version: ${{ env.ASDF_BRANCH_VERSION }}

      - name: Verify release candidate
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          case "$PROJECT_TYPE" in
            single|workspaces) : ;;
            *)
              echo "::error title=Invalid project type::PROJECT_TYPE must be single or workspaces."
              exit 1
              ;;
          esac
          case "${PACKAGE_MANAGER:-npm}" in
            npm)
              npm ci
              npm run verify
              ;;
            pnpm)
              corepack enable
              pnpm install --frozen-lockfile
              pnpm run verify
              ;;
            *)
              echo "::error title=Invalid package manager::PACKAGE_MANAGER must be npm or pnpm."
              exit 1
              ;;
          esac

      - name: Plan release metadata
        id: release-plan
        if: vars.RELEASE_LIFECYCLE != 'delegated'
        env:
          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
          BASELINE_BRANCH: ${{ steps.release-context.outputs.baseline_branch }}
          DEVELOPMENT_FLOW: ${{ vars.DEVELOPMENT_FLOW }}
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          RELEASE_LABELS: ${{ steps.release-context.outputs.release_labels }}
          RELEASE_REF: ${{ steps.release-context.outputs.release_ref }}
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail

          gh auth setup-git

          descriptor="$GITHUB_WORKSPACE/.github/inditextech-ci-node.json"
          records_file="$RUNNER_TEMP/node-release-records.jsonl"
          members_file="$RUNNER_TEMP/node-release-members.txt"
          source_commit="$(git rev-parse "$RELEASE_REF^{commit}")"
          expected_ref="refs/heads/$BASELINE_BRANCH"
          remote_line="$(git ls-remote --exit-code origin "$expected_ref")"
          read -r remote_commit remote_ref extra <<< "$remote_line"

          if [[ "$remote_ref" != "$expected_ref" || -n "${extra:-}" ]]; then
            echo "::error title=Release branch verification failed::Could not resolve exactly one destination branch."
            exit 1
          fi

          resume="false"
          release_commit=""
          if [[ "$remote_commit" != "$source_commit" ]]; then
            git fetch --no-tags origin "$remote_commit"
            release_commit="$(git rev-list --ancestry-path --reverse "${source_commit}..${remote_commit}" | head -1)"
            if [[ -z "$release_commit" ]] \
              || [[ "$(git rev-parse "${release_commit}^")" != "$source_commit" ]] \
              || [[ "$(git show -s --format=%s "$release_commit")" != "[node-release] Prepare release" ]]; then
              echo "::error title=Release branch advanced::The destination branch moved after the release source commit."
              exit 1
            fi
            git checkout --detach "$release_commit"
            resume="true"
          fi

          case ",$RELEASE_LABELS," in
            *",release-type/major,"*) release_bump="major" ;;
            *",release-type/minor,"*) release_bump="minor" ;;
            *",release-type/hotfix,"*|*",release-type/multi-hotfix,"*|*",release-type/patch,"*)
              release_bump="patch"
              ;;
            *)
              if [[ "$DEVELOPMENT_FLOW" == "trunk-based-development" ]]; then
                release_bump="minor"
              else
                echo "::error title=Missing release type::git-flow releases require a release-type label."
                exit 1
              fi
              ;;
          esac

          member_dir() {
            printf '%s' "${1##*/}" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//'
          }
          strip_snapshot() { printf '%s' "${1%-SNAPSHOT}"; }
          read_version() {
            if [[ -n "$1" ]]; then
              jq -r '.version' "packages/$1/package.json"
            else
              jq -r '.version' package.json
            fi
          }
          bump_semver() {  # <X.Y.Z> <major|minor|patch>
            local major minor patch
            IFS=. read -r major minor patch <<< "$1"
            case "$2" in
              major) major=$((major + 1)); minor=0; patch=0 ;;
              minor) minor=$((minor + 1)); patch=0 ;;
              patch) patch=$((patch + 1)) ;;
            esac
            printf '%s.%s.%s' "$major" "$minor" "$patch"
          }
          set_version() {
            if [[ -n "$2" ]]; then
              npm pkg set "version=$1" --workspace "packages/$2"
            else
              npm pkg set "version=$1"
            fi
          }

          if [[ "$PROJECT_TYPE" == "single" ]]; then
            release_strategy=single
            printf '%s\n' "$(jq -r '.name' package.json)" > "$members_file"
          elif [[ "$PROJECT_TYPE" == "workspaces" ]]; then
            release_strategy="$(jq -er '.release.strategy' "$descriptor")"
            : > "$members_file"
            while IFS= read -r package; do
              printf '%s\n' "$(member_dir "$package")" >> "$members_file"
            done < <(jq -er '.release.packages[]' "$descriptor")
          else
            echo "::error title=Invalid project type::PROJECT_TYPE must be single or workspaces."
            exit 1
          fi

          write_records() {
            : > "$records_file"
            if [[ "$release_strategy" == "single" ]]; then
              package_name="$(<"$members_file")"
              version="$(strip_snapshot "$(read_version "")")"
              next_dev="$(bump_semver "$version" "$release_bump")-SNAPSHOT"
              jq -cn \
                --arg package "$package_name" \
                --arg version "$version" \
                --arg tag "$version" \
                --arg next_dev "$next_dev" \
                '{packages: [$package], version: $version, tag: $tag, next_dev: $next_dev}' >> "$records_file"
              return
            fi

            if [[ "$release_strategy" == "locked-step" ]]; then
              members=()
              while IFS= read -r member; do
                members+=("$member")
              done < "$members_file"
              versions=()
              for member in "${members[@]}"; do
                versions+=("$(strip_snapshot "$(read_version "$member")")")
              done
              if [[ "$(printf '%s\n' "${versions[@]}" | sort -u | wc -l | tr -d ' ')" -ne 1 ]]; then
                echo "::error title=Invalid locked-step reactor::All release members must share the same version."
                exit 1
              fi
              version="${versions[0]}"
              next_dev="$(bump_semver "$version" "$release_bump")-SNAPSHOT"
              members_json="$(printf '%s\n' "${members[@]}" | jq -R . | jq -sc .)"
              jq -cn \
                --argjson packages "$members_json" \
                --arg version "$version" \
                --arg tag "$version" \
                --arg next_dev "$next_dev" \
                '{packages: $packages, version: $version, tag: $tag, next_dev: $next_dev}' >> "$records_file"
              return
            fi

            while IFS= read -r member; do
              version="$(strip_snapshot "$(read_version "$member")")"
              next_dev="$(bump_semver "$version" "$release_bump")-SNAPSHOT"
              jq -cn \
                --arg member "$member" \
                --arg version "$version" \
                --arg tag "${member}-${version}" \
                --arg next_dev "$next_dev" \
                '{packages: [$member], version: $version, tag: $tag, next_dev: $next_dev}' >> "$records_file"
            done < "$members_file"
          }

          if [[ "$resume" == "false" ]]; then
            write_records
            releases="$(jq -cs . "$records_file")"

            if [[ "$release_strategy" == "independent" ]]; then
              while IFS= read -r record; do
                member="$(jq -r '.packages[0]' <<< "$record")"
                version="$(jq -r '.version' <<< "$record")"
                set_version "$version" "$member"
              done < <(jq -c '.[]' <<< "$releases")
            elif [[ "$release_strategy" == "locked-step" ]]; then
              version="$(jq -r '.[0].version' <<< "$releases")"
              while IFS= read -r member; do
                set_version "$version" "$member"
              done < "$members_file"
            else
              set_version "$(jq -r '.[0].version' <<< "$releases")" ""
            fi

            # Reconcile workspace cross-dependency specs to each bumped sibling's released version and regenerate the lockfile so published metadata resolves the bumped siblings, not the pre-release -SNAPSHOT specs (needs bash>=4 declare -A; ubuntu runner).
            if [[ "$PROJECT_TYPE" == "workspaces" ]]; then
              declare -A member_version=()
              while IFS= read -r record; do
                rv="$(jq -r '.version' <<< "$record")"
                while IFS= read -r mdir; do
                  mname="$(jq -r '.name' "packages/$mdir/package.json")"
                  member_version["$mname"]="$rv"
                done < <(jq -r '.packages[]' <<< "$record")
              done < <(jq -c '.[]' <<< "$releases")

              while IFS= read -r member; do
                pj="packages/$member/package.json"
                for field in dependencies devDependencies peerDependencies optionalDependencies; do
                  while IFS= read -r dep; do
                    new="${member_version[$dep]:-}"
                    [[ -n "$new" ]] || continue
                    cur="$(jq -r --arg f "$field" --arg d "$dep" '.[$f][$d]' "$pj")"
                    [[ "$cur" =~ [0-9] ]] || continue
                    pre="$(printf '%s' "$cur" | sed -E 's/^([^0-9]*).*/\1/')"
                    tmp="$(mktemp)"
                    jq --arg f "$field" --arg d "$dep" --arg v "${pre}${new}" \
                       '.[$f][$d] = $v' "$pj" > "$tmp" && mv "$tmp" "$pj"
                  done < <(jq -r --arg f "$field" '(.[$f] // {}) | keys[]' "$pj")
                done
              done < "$members_file"

              npm install --package-lock-only --ignore-scripts
            fi

            while IFS= read -r tag; do
              if git show-ref --tags --verify --quiet "refs/tags/$tag"; then
                echo "::error title=Tag conflict::$tag already exists."
                exit 1
              fi
            done < <(jq -r '.[].tag' <<< "$releases")

            git -C "$GITHUB_WORKSPACE" add --update -- "$WORKING_DIRECTORY"
            if git diff --cached --quiet; then
              echo "::error title=Missing release metadata::Versioning did not produce changes to commit."
              exit 1
            fi

            primary_version="$(jq -r '.[0].version' <<< "$releases")"
            echo "RELEASE_VERSION=$primary_version" >> "$GITHUB_ENV"
            echo "RELEASE_BUMP=$release_bump" >> "$GITHUB_ENV"
          else
            write_records
            releases="$(jq -cs . "$records_file")"
            head_commit="$(git rev-parse HEAD)"
            while IFS= read -r tag; do
              if [[ "$(git rev-list -n 1 "$tag")" != "$head_commit" ]]; then
                echo "::error title=Incomplete release resume::$tag does not point to the release commit."
                exit 1
              fi
            done < <(jq -r '.[].tag' <<< "$releases")
          fi

          {
            echo "resume=$resume"
            echo "expected_ref=$expected_ref"
            echo "releases_intermediate<<EOF"
            printf '%s\n' "$releases"
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Bump CHANGELOG for release
        if: vars.RELEASE_LIFECYCLE != 'delegated' && steps.release-plan.outputs.resume != 'true'
        uses: release-flow/keep-a-changelog-action@74931dec7ecdbfc8e38ac9ae7e8dd84c08db2f32 # v3.0.0
        with:
          command: bump
          version: ${{ env.RELEASE_BUMP }}
          changelog: ${{ env.WORKING_DIRECTORY }}/CHANGELOG.md
          fail-on-empty-release-notes: false
          keep-unreleased-section: true
          tag-prefix: ""

      - name: Reconcile CHANGELOG version with release
        if: vars.RELEASE_LIFECYCLE != 'delegated' && steps.release-plan.outputs.resume != 'true'
        env:
          RELEASE_VERSION: ${{ env.RELEASE_VERSION }}
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          cl="CHANGELOG.md"
          cl_ver="$(grep -m1 -E '^## \[[0-9]' "$cl" | sed -E 's/^## \[([^]]+)\].*/\1/')"
          if [[ -z "$cl_ver" ]]; then
            echo "::error title=CHANGELOG has no release entry::Expected a '## [X.Y.Z]' heading after the bump step."
            exit 1
          fi
          if [[ "$cl_ver" != "$RELEASE_VERSION" ]]; then
            echo "::notice title=CHANGELOG version reconciled::keep-a-changelog wrote ${cl_ver}; re-anchoring to release ${RELEASE_VERSION}."
            cl_ver_re="${cl_ver//./\\.}"
            tmp="$(mktemp)"
            sed -E \
              -e "s@^## \[${cl_ver_re}\]( - )@## [${RELEASE_VERSION}]\1@" \
              -e "s@^(\[Unreleased\]: .*/compare/)${cl_ver_re}(\.\.\.HEAD)@\1${RELEASE_VERSION}\2@" \
              -e "s@^\[${cl_ver_re}\]: (.*/)(compare/[^ ]*\.\.\.|releases/tag/)${cl_ver_re}@[${RELEASE_VERSION}]: \1\2${RELEASE_VERSION}@" \
              "$cl" > "$tmp"
            cat "$tmp" > "$cl"
            rm -f "$tmp"
          fi

      - name: Commit, tag and push release
        if: vars.RELEASE_LIFECYCLE != 'delegated' && steps.release-plan.outputs.resume != 'true'
        id: release-commit
        env:
          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          RELEASES: ${{ steps.release-plan.outputs.releases_intermediate }}
          EXPECTED_REF: ${{ steps.release-plan.outputs.expected_ref }}
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          git -C "$GITHUB_WORKSPACE" add -- "$WORKING_DIRECTORY/CHANGELOG.md"
          git -C "$GITHUB_WORKSPACE" add --update -- "$WORKING_DIRECTORY"
          if git diff --cached --quiet; then
            echo "::error title=Missing release metadata::Versioning did not produce changes to commit."
            exit 1
          fi
          git config user.name "${APP_SLUG}[bot]"
          git config user.email "${APP_SLUG}[bot]@users.noreply.github.com"
          git commit -m "[node-release] Prepare release"

          tag_refs=()
          while IFS= read -r record; do
            tag="$(jq -r '.tag' <<< "$record")"
            version="$(jq -r '.version' <<< "$record")"
            git check-ref-format --allow-onelevel "refs/tags/$tag"
            git tag -a "$tag" -m "Release $version"
            tag_refs+=("refs/tags/$tag")
          done < <(jq -c '.[]' <<< "$RELEASES")

          git push --atomic origin "HEAD:$EXPECTED_REF" "${tag_refs[@]}"

      - name: Cut delegated release
        id: delegated-plan
        if: vars.RELEASE_LIFECYCLE == 'delegated'
        env:
          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
          BASELINE_BRANCH: ${{ steps.release-context.outputs.baseline_branch }}
          DEVELOPMENT_FLOW: ${{ vars.DEVELOPMENT_FLOW }}
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          RELEASE_LABELS: ${{ steps.release-context.outputs.release_labels }}
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail

          gh auth setup-git
          git config user.name "${APP_SLUG}[bot]"
          git config user.email "${APP_SLUG}[bot]@users.noreply.github.com"

          case ",$RELEASE_LABELS," in
            *",release-type/major,"*) release_bump="major" ;;
            *",release-type/minor,"*) release_bump="minor" ;;
            *",release-type/hotfix,"*|*",release-type/multi-hotfix,"*|*",release-type/patch,"*)
              release_bump="patch"
              ;;
            *)
              if [[ "$DEVELOPMENT_FLOW" == "trunk-based-development" ]]; then
                release_bump="minor"
              else
                echo "::error title=Missing release type::git-flow releases require a release-type label."
                exit 1
              fi
              ;;
          esac
          export RELEASE_BUMP="$release_bump"

          git tag | sort > "$RUNNER_TEMP/tags-before.txt"

          case "${PACKAGE_MANAGER:-npm}" in
            npm)  npm run release:prepare ;;
            pnpm) corepack enable; pnpm run release:prepare ;;
            *)    echo "::error title=Invalid package manager::PACKAGE_MANAGER must be npm or pnpm."; exit 1 ;;
          esac

          git tag | sort > "$RUNNER_TEMP/tags-after.txt"
          mapfile -t new_tags < <(comm -13 "$RUNNER_TEMP/tags-before.txt" "$RUNNER_TEMP/tags-after.txt")
          if [[ ${#new_tags[@]} -eq 0 ]]; then
            echo "::error title=No release cut::release:prepare produced no new tags."
            exit 1
          fi

          records_file="$RUNNER_TEMP/node-release-records.jsonl"
          : > "$records_file"
          for tag in "${new_tags[@]}"; do
            if [[ "$tag" =~ ([0-9]+\.[0-9]+\.[0-9]+([-+.][0-9A-Za-z.-]+)?)$ ]]; then
              version="${BASH_REMATCH[1]}"
            else
              version="$tag"
            fi
            jq -cn \
              --arg tag "$tag" \
              --arg version "$version" \
              --arg bump "$release_bump" \
              '{packages: [], version: $version, tag: $tag, next_dev: "", release_bump: $bump}' \
              >> "$records_file"
          done
          releases="$(jq -cs . "$records_file")"
          primary_version="$(jq -r '.[0].version' <<< "$releases")"

          changelog_pending="false"
          if [[ -f CHANGELOG.md ]] \
            && awk '/^## \[?[Uu]nreleased\]?/{f=1;next} /^## /{f=0} f && NF {print; exit}' CHANGELOG.md | grep -q .; then
            changelog_pending="true"
          fi

          echo "RELEASE_BUMP=$release_bump" >> "$GITHUB_ENV"
          echo "RELEASE_VERSION=$primary_version" >> "$GITHUB_ENV"

          {
            echo "expected_ref=refs/heads/$BASELINE_BRANCH"
            echo "primary_version=$primary_version"
            echo "changelog_pending=$changelog_pending"
            echo "releases_intermediate<<EOF"
            printf '%s\n' "$releases"
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Bump CHANGELOG for delegated release
        if: vars.RELEASE_LIFECYCLE == 'delegated' && steps.delegated-plan.outputs.changelog_pending == 'true'
        uses: release-flow/keep-a-changelog-action@74931dec7ecdbfc8e38ac9ae7e8dd84c08db2f32 # v3.0.0
        with:
          command: bump
          version: ${{ env.RELEASE_BUMP }}
          changelog: ${{ env.WORKING_DIRECTORY }}/CHANGELOG.md
          fail-on-empty-release-notes: false
          keep-unreleased-section: true
          tag-prefix: ""

      - name: Reconcile CHANGELOG version with delegated release
        if: vars.RELEASE_LIFECYCLE == 'delegated' && steps.delegated-plan.outputs.changelog_pending == 'true'
        env:
          RELEASE_VERSION: ${{ env.RELEASE_VERSION }}
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          cl="CHANGELOG.md"
          cl_ver="$(grep -m1 -E '^## \[[0-9]' "$cl" | sed -E 's/^## \[([^]]+)\].*/\1/')"
          if [[ -z "$cl_ver" ]]; then
            echo "::error title=CHANGELOG has no release entry::Expected a '## [X.Y.Z]' heading after the bump step."
            exit 1
          fi
          if [[ "$cl_ver" != "$RELEASE_VERSION" ]]; then
            echo "::notice title=CHANGELOG version reconciled::keep-a-changelog wrote ${cl_ver}; re-anchoring to release ${RELEASE_VERSION}."
            cl_ver_re="${cl_ver//./\\.}"
            tmp="$(mktemp)"
            sed -E \
              -e "s@^## \[${cl_ver_re}\]( - )@## [${RELEASE_VERSION}]\1@" \
              -e "s@^(\[Unreleased\]: .*/compare/)${cl_ver_re}(\.\.\.HEAD)@\1${RELEASE_VERSION}\2@" \
              -e "s@^\[${cl_ver_re}\]: (.*/)(compare/[^ ]*\.\.\.|releases/tag/)${cl_ver_re}@[${RELEASE_VERSION}]: \1\2${RELEASE_VERSION}@" \
              "$cl" > "$tmp"
            cat "$tmp" > "$cl"
            rm -f "$tmp"
          fi

      - name: Push delegated release
        id: delegated-push
        if: vars.RELEASE_LIFECYCLE == 'delegated'
        env:
          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          RELEASES: ${{ steps.delegated-plan.outputs.releases_intermediate }}
          EXPECTED_REF: ${{ steps.delegated-plan.outputs.expected_ref }}
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          git config user.name "${APP_SLUG}[bot]"
          git config user.email "${APP_SLUG}[bot]@users.noreply.github.com"

          remote_tags="$(git ls-remote --tags origin \
            | awk '{print $2}' | sed 's#refs/tags/##; s#\^{}##' | sort -u)"
          missing=0
          while IFS= read -r tag; do
            grep -qxF "$tag" <<< "$remote_tags" || missing=1
          done < <(jq -r '.[].tag' <<< "$RELEASES")
          if [[ "$missing" -eq 0 ]]; then
            echo "::notice title=Delegated release already pushed::All cut tags already exist on the remote."
            exit 0
          fi

          git -C "$GITHUB_WORKSPACE" add -- "$WORKING_DIRECTORY/CHANGELOG.md"
          if ! git diff --cached --quiet; then
            git commit -m "[node-release] Update changelog"
          fi

          tag_refs=()
          while IFS= read -r tag; do
            git check-ref-format --allow-onelevel "refs/tags/$tag"
            tag_refs+=("refs/tags/$tag")
          done < <(jq -r '.[].tag' <<< "$RELEASES")
          git push --atomic origin "HEAD:$EXPECTED_REF" "${tag_refs[@]}"

      - name: Publish release metadata
        id: release-metadata
        env:
          RELEASES: ${{ steps.release-plan.outputs.releases_intermediate || steps.delegated-plan.outputs.releases_intermediate }}
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          {
            echo "release_commit=$(git -C "$GITHUB_WORKSPACE" rev-parse HEAD)"
            echo "releases<<EOF"
            printf '%s\n' "$RELEASES"
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

  build-distributions:
    name: Build ${{ matrix.release.tag }}
    needs: prepare-release
    if: vars.RELEASE_LIFECYCLE != 'delegated'
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    strategy:
      fail-fast: false
      matrix:
        release: ${{ fromJSON(needs.prepare-release.outputs.releases) }}
    steps:
      - name: Check out release commit
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
          ref: ${{ needs.prepare-release.outputs.release_commit }}

      - name: Read governed tool versions
        id: tool-versions
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          if grep -Evq '^[a-zA-Z0-9_-]+ [a-zA-Z0-9._+-]+$' .tool-versions; then
            echo "::error title=Invalid tool-versions::${WORKING_DIRECTORY}/.tool-versions is malformed."
            exit 1
          fi
          {
            echo "tool_versions<<EOF"
            cat .tool-versions
            echo
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Set up asdf-managed Node
        uses: asdf-vm/actions/install@b7bcd026f18772e44fe1026d729e1611cc435d47 # v4.0.0
        with:
          tool_versions: ${{ steps.tool-versions.outputs.tool_versions }}
          asdf_version: ${{ env.ASDF_BRANCH_VERSION }}

      - name: Build and pack declared distributions
        env:
          RELEASE: ${{ toJSON(matrix.release) }}
          DIST_DIR: ${{ runner.temp }}/dist
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          rm -rf "$DIST_DIR"
          mkdir -p "$DIST_DIR"
          case "${PACKAGE_MANAGER:-npm}" in
            npm)
              npm ci
              npm run build
              case "$PROJECT_TYPE" in
                single)
                  npm pack --pack-destination "$DIST_DIR"
                  ;;
                workspaces)
                  while IFS= read -r member; do
                    npm pack --workspace "packages/$member" --pack-destination "$DIST_DIR"
                  done < <(jq -r '.packages[]' <<< "$RELEASE")
                  ;;
                *)
                  echo "::error title=Invalid project type::PROJECT_TYPE must be single or workspaces."
                  exit 1
                  ;;
              esac
              ;;
            pnpm)
              corepack enable
              pnpm install --frozen-lockfile
              pnpm run build
              case "$PROJECT_TYPE" in
                single)
                  pnpm pack --pack-destination "$DIST_DIR"
                  ;;
                workspaces)
                  while IFS= read -r member; do
                    ( cd "packages/$member" && pnpm pack --pack-destination "$DIST_DIR" )
                  done < <(jq -r '.packages[]' <<< "$RELEASE")
                  ;;
                *)
                  echo "::error title=Invalid project type::PROJECT_TYPE must be single or workspaces."
                  exit 1
                  ;;
              esac
              ;;
            *)
              echo "::error title=Invalid package manager::PACKAGE_MANAGER must be npm or pnpm."
              exit 1
              ;;
          esac

          if ! ls "$DIST_DIR"/*.tgz > /dev/null 2>&1; then
            echo "::error title=Missing artifacts::No tarballs were produced for ${RELEASE}."
            exit 1
          fi

      - name: Upload release distributions
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: npm-distributions-${{ matrix.release.tag }}
          path: ${{ runner.temp }}/dist/*.tgz
          if-no-files-found: error
          retention-days: 14

  finalize-release:
    name: Finalize release (next dev + sync PR)
    needs: [prepare-release, build-distributions]
    if: >-
      !cancelled() &&
      needs.prepare-release.result == 'success' &&
      (needs.build-distributions.result == 'success' || needs.build-distributions.result == 'skipped')
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    permissions:
      contents: read
    steps:
      - name: Create GitHub App token
        id: app-token
        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
        with:
          client-id: ${{ vars.APP_CLIENT_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
          permission-contents: write
          permission-pull-requests: write

      - name: Check out release branch
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false
          ref: ${{ github.event.pull_request.base.ref || github.ref_name }}
          token: ${{ steps.app-token.outputs.token }}

      - name: Read governed tool versions
        id: tool-versions
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          if grep -Evq '^[a-zA-Z0-9_-]+ [a-zA-Z0-9._+-]+$' .tool-versions; then
            echo "::error title=Invalid tool-versions::${WORKING_DIRECTORY}/.tool-versions is malformed."
            exit 1
          fi
          {
            echo "tool_versions<<EOF"
            cat .tool-versions
            echo
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Set up asdf-managed Node
        uses: asdf-vm/actions/install@b7bcd026f18772e44fe1026d729e1611cc435d47 # v4.0.0
        with:
          tool_versions: ${{ steps.tool-versions.outputs.tool_versions }}
          asdf_version: ${{ env.ASDF_BRANCH_VERSION }}

      - name: Next development iteration and sync PR
        env:
          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
          BASELINE_BRANCH: ${{ github.event.pull_request.base.ref || github.ref_name }}
          DEVELOPMENT_FLOW: ${{ vars.DEVELOPMENT_FLOW }}
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          RELEASES: ${{ needs.prepare-release.outputs.releases }}
          RELEASE_COMMIT: ${{ needs.prepare-release.outputs.release_commit }}
          RELEASE_LIFECYCLE: ${{ vars.RELEASE_LIFECYCLE }}
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          gh auth setup-git
          git config user.name "${APP_SLUG}[bot]"
          git config user.email "${APP_SLUG}[bot]@users.noreply.github.com"

          descriptor="$GITHUB_WORKSPACE/.github/inditextech-ci-node.json"

          member_dir() {
            printf '%s' "${1##*/}" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//'
          }

          if [[ "$(git rev-parse HEAD)" != "$RELEASE_COMMIT" ]]; then
            echo "::notice title=Next-dev skipped::Branch already advanced past the release commit."
          else
            if [[ "$RELEASE_LIFECYCLE" == "delegated" ]]; then
              release_bump="$(jq -r '.[0].release_bump // ""' <<< "$RELEASES")"
              case "${PACKAGE_MANAGER:-npm}" in
                npm)  RELEASE_BUMP="$release_bump" npm run version:development ;;
                pnpm) corepack enable; RELEASE_BUMP="$release_bump" pnpm run version:development ;;
                *)    echo "::error title=Invalid package manager::PACKAGE_MANAGER must be npm or pnpm."; exit 1 ;;
              esac
              git -C "$GITHUB_WORKSPACE" add --update -- "$WORKING_DIRECTORY"
              if ! git diff --cached --quiet; then
                git commit -m "[node-release] prepare for next development iteration"
              fi
            else
              if [[ "$PROJECT_TYPE" == "single" ]]; then
                next_dev="$(jq -r '.[0].next_dev' <<< "$RELEASES")"
                npm pkg set "version=$next_dev"
              elif [[ "$(jq -er '.release.strategy' "$descriptor")" == "locked-step" ]]; then
                next_dev="$(jq -r '.[0].next_dev' <<< "$RELEASES")"
                while IFS= read -r package; do
                  member="$(member_dir "$package")"
                  npm pkg set "version=$next_dev" --workspace "packages/$member"
                done < <(jq -er '.release.packages[]' "$descriptor")
              else
                while IFS= read -r record; do
                  member="$(jq -r '.packages[0]' <<< "$record")"
                  next_dev="$(jq -r '.next_dev' <<< "$record")"
                  npm pkg set "version=$next_dev" --workspace "packages/$member"
                done < <(jq -c '.[]' <<< "$RELEASES")
              fi

              # Same cross-dependency reconciliation as the release strip, on the next-dev bump: point each sibling spec at the bumped member's next_dev and regenerate the lockfile, or main keeps cross-deps at the released version with a stale lockfile and `npm ci` fails (needs bash>=4).
              if [[ "$PROJECT_TYPE" == "workspaces" ]]; then
                declare -A member_version=()
                while IFS= read -r record; do
                  rv="$(jq -r '.next_dev' <<< "$record")"
                  while IFS= read -r mdir; do
                    mname="$(jq -r '.name' "packages/$mdir/package.json")"
                    member_version["$mname"]="$rv"
                  done < <(jq -r '.packages[]' <<< "$record")
                done < <(jq -c '.[]' <<< "$RELEASES")

                while IFS= read -r mdir; do
                  pj="packages/$mdir/package.json"
                  for field in dependencies devDependencies peerDependencies optionalDependencies; do
                    while IFS= read -r dep; do
                      new="${member_version[$dep]:-}"
                      [[ -n "$new" ]] || continue
                      cur="$(jq -r --arg f "$field" --arg d "$dep" '.[$f][$d]' "$pj")"
                      [[ "$cur" =~ [0-9] ]] || continue
                      pre="$(printf '%s' "$cur" | sed -E 's/^([^0-9]*).*/\1/')"
                      tmp="$(mktemp)"
                      jq --arg f "$field" --arg d "$dep" --arg v "${pre}${new}" \
                         '.[$f][$d] = $v' "$pj" > "$tmp" && mv "$tmp" "$pj"
                    done < <(jq -r --arg f "$field" '(.[$f] // {}) | keys[]' "$pj")
                  done
                done < <(jq -r '.[].packages[]' <<< "$RELEASES")

                npm install --package-lock-only --ignore-scripts
              fi

              git -C "$GITHUB_WORKSPACE" add --update -- "$WORKING_DIRECTORY"
              git commit -m "[node-release] prepare for next development iteration"
            fi
            git push origin "HEAD:refs/heads/$BASELINE_BRANCH"
          fi

          if [[ "$DEVELOPMENT_FLOW" != "git-flow" ]]; then
            echo "::notice title=Sync skipped::Sync-to-develop applies only to git-flow."
            exit 0
          fi

          version="$(jq -r '.[0].version' <<< "$RELEASES")"
          develop_branch="${BASELINE_BRANCH/main/develop}"
          if [[ -z "$(git ls-remote --heads origin "$develop_branch")" ]]; then
            echo "::notice title=Sync skipped::$develop_branch does not exist."
            exit 0
          fi
          sync_branch="automated/sync-release-${version}-to-${develop_branch}"
          git switch --force-create "$sync_branch" "origin/$BASELINE_BRANCH"
          git push --force-with-lease --set-upstream origin "$sync_branch"

          if [[ -z "$(gh pr list --repo "$GITHUB_REPOSITORY" --head "$sync_branch" --base "$develop_branch" --state open --json number --jq '.[0].number // empty')" ]]; then
            gh pr create --repo "$GITHUB_REPOSITORY" \
              --base "$develop_branch" --head "$sync_branch" \
              --title "Sync release $version to $develop_branch" \
              --body "**Automated pull request** syncing the release cut on \`$BASELINE_BRANCH\` back into \`$develop_branch\`."
          fi