tag-release.yml

name: Claude Tag Release

on:
  workflow_call:
    inputs:
      branch_ref:
        description: 'Branch or commit ref to create tag from'
        required: true
        type: string
      product_name:
        description: 'Name used in the release title, e.g. "RoboSystems Service", "RoboLedger App"'
        required: false
        type: string
        default: 'RoboSystems Service'
      product_description:
        description: 'One line saying what this repo is. Given to Claude so the notes describe the right product.'
        required: false
        type: string
        default: ''
      project_kind:
        description: 'Kind of release, used in the prompt, e.g. "software", "Next.js frontend application", "Python SDK"'
        required: false
        type: string
        default: 'software'
      live_url:
        description: 'Public URL for the product; adds a Live link to the release body. Omit for libraries and SDKs.'
        required: false
        type: string
        default: ''
    secrets:
      ANTHROPIC_API_KEY:
        description: 'API key for Claude changelog generation'
        required: true
    outputs:
      tag_name:
        description: 'The created tag name (e.g., v1.2.3)'
        value: ${{ jobs.tag.outputs.tag_name }}
      version:
        description: 'The version number (e.g., 1.2.3)'
        value: ${{ jobs.tag.outputs.version }}
      release_url:
        description: 'The GitHub release URL'
        value: ${{ jobs.tag.outputs.release_url }}

jobs:
  tag:
    runs-on: ubuntu-latest # Use GitHub-hosted runners for memory-intensive git/Claude operations
    timeout-minutes: 15
    permissions:
      contents: write
    outputs:
      tag_name: ${{ steps.set-outputs.outputs.tag_name }}
      version: ${{ steps.set-outputs.outputs.version }}
      release_url: ${{ steps.set-outputs.outputs.release_url }}
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          repository: ${{ github.repository }}
          ref: ${{ inputs.branch_ref }}
          # ACTIONS_TOKEN required to push tags to protected repo
          token: ${{ secrets.ACTIONS_TOKEN || github.token }}
          fetch-depth: 0

      - name: Get version
        id: get-version
        run: |
          # Shared by every RoboFinSystems repo: read pyproject.toml or package.json,
          # and refuse an empty version so a tag named "v" can never be cut.
          VERSION=""
          SOURCE=""
          if [ -f pyproject.toml ]; then
            VERSION=$(grep "^version = " pyproject.toml | sed 's/version = "\(.*\)"/\1/')
            SOURCE="pyproject.toml"
          elif [ -f package.json ]; then
            VERSION=$(jq -r '.version // empty' package.json)
            SOURCE="package.json"
          fi
          if [ -z "$VERSION" ]; then
            echo "::error::No version found in pyproject.toml or package.json at ${{ inputs.branch_ref }}; refusing to tag."
            exit 1
          fi
          echo "version=$VERSION" >> $GITHUB_OUTPUT
          echo "Found version $VERSION in $SOURCE"

      - name: Check If Tag Exists
        id: check-tag
        env:
          VERSION: ${{ steps.get-version.outputs.version }}
        run: |
          if [ -n "$(git tag -l "v${VERSION}")" ]; then
            echo "tag_exists=true" >> $GITHUB_OUTPUT
            echo "Tag v${VERSION} already exists"
          else
            echo "tag_exists=false" >> $GITHUB_OUTPUT
            echo "Tag v${VERSION} does not exist yet"
          fi

      - name: Check for curated release notes
        if: steps.check-tag.outputs.tag_exists == 'false'
        id: curated-notes
        env:
          VERSION: ${{ steps.get-version.outputs.version }}
        run: |
          # Milestone releases ship hand-written notes committed at
          # .github/release-notes/v<version>.md; when present they replace
          # the generated delta changelog below.
          NOTES_FILE=".github/release-notes/v${VERSION}.md"
          if [ -f "$NOTES_FILE" ]; then
            echo "found=true" >> $GITHUB_OUTPUT
            echo "path=$NOTES_FILE" >> $GITHUB_OUTPUT
            echo "📝 Curated release notes found: $NOTES_FILE"
          else
            echo "found=false" >> $GITHUB_OUTPUT
            echo "No curated notes at $NOTES_FILE — generating changelog from changes since last tag"
          fi

      - name: Analyze changes since last release
        if: steps.check-tag.outputs.tag_exists == 'false'
        id: analyze-changes
        run: |
          # Get the last release tag. The pattern is anchored at both ends so only
          # a strict vMAJOR.MINOR.PATCH tag can be selected: LAST_TAG flows into
          # later git commands and prompt text, so it must not carry trailing text.
          LAST_TAG=$(git tag --sort=-version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1)

          if [ -z "$LAST_TAG" ]; then
            echo "No previous release found, analyzing all commits"
            LAST_TAG="initial"
            # For initial release, use different commands that don't require a range
            FILES_CHANGED=$(git ls-files | wc -l)
            COMMITS_COUNT=$(git rev-list --count HEAD)
            # Get stats by diffing empty tree against HEAD
            EMPTY_TREE=$(git hash-object -t tree /dev/null)
            ADDITIONS=$(git diff --shortstat "$EMPTY_TREE" HEAD | grep -oE '[0-9]+ insertions?' | grep -oE '[0-9]+' || echo "0")
            DELETIONS=$(git diff --shortstat "$EMPTY_TREE" HEAD | grep -oE '[0-9]+ deletions?' | grep -oE '[0-9]+' || echo "0")
            COMMIT_MESSAGES=$(git log --oneline --no-color HEAD | head -30)
            DETAILED_CHANGES=$(git diff --name-status --no-color "$EMPTY_TREE" HEAD | head -50)
            PR_REFS=$(git log --oneline --no-color HEAD | grep -oE '#[0-9]+' | sort -u | head -10 || echo "")
          else
            echo "Analyzing changes since last release: $LAST_TAG"
            # Use explicit two-commit diff syntax instead of range syntax
            FILES_CHANGED=$(git diff --name-only "$LAST_TAG" HEAD | wc -l)
            COMMITS_COUNT=$(git rev-list --count "$LAST_TAG"..HEAD)
            ADDITIONS=$(git diff --shortstat "$LAST_TAG" HEAD | grep -oE '[0-9]+ insertions?' | grep -oE '[0-9]+' || echo "0")
            DELETIONS=$(git diff --shortstat "$LAST_TAG" HEAD | grep -oE '[0-9]+ deletions?' | grep -oE '[0-9]+' || echo "0")
            COMMIT_MESSAGES=$(git log --oneline --no-color "$LAST_TAG"..HEAD | head -30)
            DETAILED_CHANGES=$(git diff --name-status --no-color "$LAST_TAG" HEAD | head -50)
            PR_REFS=$(git log --oneline --no-color "$LAST_TAG"..HEAD | grep -oE '#[0-9]+' | sort -u | head -10 || echo "")
          fi

          # Save outputs
          echo "last_tag=$LAST_TAG" >> $GITHUB_OUTPUT
          echo "files_changed=$FILES_CHANGED" >> $GITHUB_OUTPUT
          echo "commits_count=$COMMITS_COUNT" >> $GITHUB_OUTPUT
          echo "additions=$ADDITIONS" >> $GITHUB_OUTPUT
          echo "deletions=$DELETIONS" >> $GITHUB_OUTPUT

          # Save multiline outputs using unique delimiters to avoid conflicts with content
          DELIMITER_1="GHOUTPUT_$(date +%s)_COMMIT"
          DELIMITER_2="GHOUTPUT_$(date +%s)_CHANGES"
          DELIMITER_3="GHOUTPUT_$(date +%s)_PRREFS"

          {
            echo "commit_messages<<$DELIMITER_1"
            echo "$COMMIT_MESSAGES"
            echo "$DELIMITER_1"
          } >> $GITHUB_OUTPUT

          {
            echo "detailed_changes<<$DELIMITER_2"
            echo "$DETAILED_CHANGES"
            echo "$DELIMITER_2"
          } >> $GITHUB_OUTPUT

          {
            echo "pr_refs<<$DELIMITER_3"
            echo "$PR_REFS"
            echo "$DELIMITER_3"
          } >> $GITHUB_OUTPUT

      - name: Generate changelog with Claude
        if: steps.check-tag.outputs.tag_exists == 'false' && steps.curated-notes.outputs.found != 'true'
        id: generate-changelog
        # Untrusted inputs (commit messages, changed filenames) reach the shell
        # only through env vars, never ${{ }} interpolation. In the unquoted
        # heredoc a `$VAR` expands, but the expanded value is not re-scanned, so a
        # `$(...)`/backtick planted in a commit message stays literal text.
        env:
          VERSION: ${{ steps.get-version.outputs.version }}
          LAST_TAG: ${{ steps.analyze-changes.outputs.last_tag }}
          FILES_CHANGED: ${{ steps.analyze-changes.outputs.files_changed }}
          COMMITS_COUNT: ${{ steps.analyze-changes.outputs.commits_count }}
          ADDITIONS: ${{ steps.analyze-changes.outputs.additions }}
          DELETIONS: ${{ steps.analyze-changes.outputs.deletions }}
          COMMIT_MESSAGES: ${{ steps.analyze-changes.outputs.commit_messages }}
          DETAILED_CHANGES: ${{ steps.analyze-changes.outputs.detailed_changes }}
          PR_REFS: ${{ steps.analyze-changes.outputs.pr_refs }}
          PRODUCT_NAME: ${{ inputs.product_name }}
          PRODUCT_DESCRIPTION: ${{ inputs.product_description }}
          PROJECT_KIND: ${{ inputs.project_kind }}
        run: |
          # Identity line is built before the heredoc so the description stays optional.
          if [ -n "$PRODUCT_DESCRIPTION" ]; then
            PRODUCT_LINE="- Product: $PRODUCT_NAME ($PRODUCT_DESCRIPTION)"
          else
            PRODUCT_LINE="- Product: $PRODUCT_NAME"
          fi

          # Create analysis prompt for Claude
          cat > /tmp/changelog_prompt.txt << PROMPT_EOF
          I need you to generate a concise but informative changelog for a $PROJECT_KIND release.

          **Release Info:**
          $PRODUCT_LINE
          - Version: $VERSION
          - Previous Version: $LAST_TAG
          - Files Changed: $FILES_CHANGED
          - Commits: $COMMITS_COUNT
          - Lines Added: $ADDITIONS
          - Lines Deleted: $DELETIONS

          **Recent Commits:**
          $COMMIT_MESSAGES

          **File Changes:**
          $DETAILED_CHANGES

          **PR References:**
          $PR_REFS

          Please generate a changelog that includes:
          1. A brief 1-2 sentence summary of this release
          2. Key features/improvements (bullet points)
          3. Breaking changes (if any) - clearly marked with ⚠️
          4. Notable technical changes worth mentioning
          5. Bug fixes (if any)

          Keep it concise but informative. Focus on what users and developers need to know.
          Use markdown formatting. Don't include a version header as that will be added separately.
          If there are security improvements, highlight them.
          If this appears to be a maintenance/infrastructure release, emphasize that.

          Format your response as clean markdown without any prefix text.
          PROMPT_EOF

          echo "✅ Changelog prompt created"

      - name: Call Claude API for changelog
        if: steps.check-tag.outputs.tag_exists == 'false' && steps.curated-notes.outputs.found != 'true'
        id: claude-changelog
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          CLAUDE_MODEL: ${{ vars.CLAUDE_MODEL || 'claude-sonnet-4-6' }}
        run: |
          # Check if ANTHROPIC_API_KEY is available
          if [ -z "$ANTHROPIC_API_KEY" ]; then
            echo "::notice::ANTHROPIC_API_KEY not set - using basic changelog"
            CHANGELOG="## What's Changed"$'\n\n'
            CHANGELOG="${CHANGELOG}- ${{ steps.analyze-changes.outputs.commits_count }} commits with ${{ steps.analyze-changes.outputs.files_changed }} files changed"$'\n'
            CHANGELOG="${CHANGELOG}- ${{ steps.analyze-changes.outputs.additions }} additions and ${{ steps.analyze-changes.outputs.deletions }} deletions"$'\n\n'
            CHANGELOG="${CHANGELOG}See commit history for detailed changes."$'\n\n'
            CHANGELOG="${CHANGELOG}---"$'\n'"*To enable AI-generated changelogs, set ANTHROPIC_API_KEY secret.*"

            {
              echo "changelog<<EOF"
              echo -e "$CHANGELOG"
              echo "EOF"
            } >> $GITHUB_OUTPUT

            exit 0
          fi

          # Call Claude API with the analysis prompt
          PROMPT=$(cat /tmp/changelog_prompt.txt)

          # Create a proper JSON payload using jq to handle escaping
          PAYLOAD=$(jq -n \
            --arg model "$CLAUDE_MODEL" \
            --arg content "$PROMPT" \
            '{
              "model": $model,
              "max_tokens": 8000,
              "messages": [
                {
                  "role": "user",
                  "content": $content
                }
              ]
            }')

            # The key goes to curl as a config file on stdin, not -H, so it never
            # appears in a process argv (printf is a builtin).
          RESPONSE=$(printf 'header = "x-api-key: %s"\n' "$ANTHROPIC_API_KEY" \
            | curl -s --config - --max-time 180 --retry 3 --retry-delay 10 -X POST "https://api.anthropic.com/v1/messages" \
              -H "Content-Type: application/json" \
              -H "anthropic-version: 2023-06-01" \
              -d "$PAYLOAD")

          # Check for API errors
          if echo "$RESPONSE" | jq -e '.error' > /dev/null; then
            ERROR_MSG=$(echo "$RESPONSE" | jq -r '.error.message // "Unknown error"')
            ERROR_TYPE=$(echo "$RESPONSE" | jq -r '.error.type // "unknown"')
            echo "::error::Claude API error [$ERROR_TYPE]: $ERROR_MSG - falling back to commit stats"
            echo "Full response: $RESPONSE" >&2  # Log to stderr for debugging
            echo "Using fallback changelog"
            CHANGELOG="## What's Changed\n\n- ${{ steps.analyze-changes.outputs.commits_count }} commits with ${{ steps.analyze-changes.outputs.files_changed }} files changed\n- ${{ steps.analyze-changes.outputs.additions }} additions and ${{ steps.analyze-changes.outputs.deletions }} deletions\n\nSee commit history for detailed changes."
          else
            # Concatenate every text block: the first block may be a thinking block.
            CHANGELOG=$(echo "$RESPONSE" | jq -r '[.content[]? | select(.type == "text") | .text] | join("")')
            STOP_REASON=$(echo "$RESPONSE" | jq -r '.stop_reason // "unknown"')

            # Validate that Claude returned meaningful content
            if [ -z "$CHANGELOG" ] || [ "$CHANGELOG" = "null" ]; then
              echo "::error::Claude returned no text block (stop_reason=$STOP_REASON, blocks=$(echo "$RESPONSE" | jq -c '[.content[]?.type]')) - falling back to commit stats"
              CHANGELOG="## What's Changed\n\n- ${{ steps.analyze-changes.outputs.commits_count }} commits with ${{ steps.analyze-changes.outputs.files_changed }} files changed\n- ${{ steps.analyze-changes.outputs.additions }} additions and ${{ steps.analyze-changes.outputs.deletions }} deletions\n\nSee commit history for detailed changes."
            else
              if [ "$STOP_REASON" = "max_tokens" ]; then
                echo "::warning::Changelog hit max_tokens and may be truncated"
              fi
              echo "✅ Claude changelog generated successfully"
            fi
          fi

          # Save changelog to output
          {
            echo "changelog<<EOF"
            echo -e "$CHANGELOG"
            echo "EOF"
          } >> $GITHUB_OUTPUT

      - name: Compose release body
        if: steps.check-tag.outputs.tag_exists == 'false'
        # The changelog (Claude-generated or curated) is untrusted relative to
        # the shell — emit it with printf/cat from env vars and files, never by
        # splicing ${{ ... }} into the script.
        env:
          VERSION: ${{ steps.get-version.outputs.version }}
          CURATED_FOUND: ${{ steps.curated-notes.outputs.found }}
          CURATED_PATH: ${{ steps.curated-notes.outputs.path }}
          CHANGELOG: ${{ steps.claude-changelog.outputs.changelog }}
          LAST_TAG: ${{ steps.analyze-changes.outputs.last_tag }}
          COMMITS_COUNT: ${{ steps.analyze-changes.outputs.commits_count }}
          FILES_CHANGED: ${{ steps.analyze-changes.outputs.files_changed }}
          ADDITIONS: ${{ steps.analyze-changes.outputs.additions }}
          DELETIONS: ${{ steps.analyze-changes.outputs.deletions }}
          PRODUCT_NAME: ${{ inputs.product_name }}
          LIVE_URL: ${{ inputs.live_url }}
        run: |
          if [ "$CURATED_FOUND" = "true" ]; then
            cp "$CURATED_PATH" /tmp/release_changelog.md
          else
            printf '%s\n' "$CHANGELOG" > /tmp/release_changelog.md
          fi

          {
            echo "# ${PRODUCT_NAME} v${VERSION}"
            echo ""
            cat /tmp/release_changelog.md
            echo ""
            echo "---"
            echo ""
            if [ "$CURATED_FOUND" != "true" ]; then
              echo "## 📊 Release Statistics"
              echo ""
              echo "- **Commits:** ${COMMITS_COUNT}"
              echo "- **Files Changed:** ${FILES_CHANGED}"
              echo "- **Lines Added:** ${ADDITIONS}"
              echo "- **Lines Deleted:** ${DELETIONS}"
              echo "- **Previous Release:** ${LAST_TAG}"
              echo ""
            fi
            echo "## 🔗 Links"
            echo ""
            echo "- **Full Changelog:** [${LAST_TAG}...v${VERSION}](https://github.com/${{ github.repository }}/compare/${LAST_TAG}...v${VERSION})"
            echo "- **All Releases:** [View all releases](https://github.com/${{ github.repository }}/releases)"
            if [ -n "$LIVE_URL" ]; then
              echo "- **Live App:** [${LIVE_URL#https://}](${LIVE_URL})"
            fi
            if [ "$CURATED_FOUND" != "true" ]; then
              echo ""
              echo "---"
              echo "🤖 Generated with [Claude Code](https://claude.ai/code)"
            fi
          } > /tmp/release_body.md

          echo "✅ Release body composed ($([ "$CURATED_FOUND" = "true" ] && echo "curated notes" || echo "generated changelog"))"

      - name: Create Release Tag
        if: steps.check-tag.outputs.tag_exists == 'false'
        env:
          VERSION: ${{ steps.get-version.outputs.version }}
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "github-actions[bot]@users.noreply.github.com"
          git tag -a "v${VERSION}" -m "Release v${VERSION}"
          git push origin "v${VERSION}"

      - name: Create GitHub Release
        if: steps.check-tag.outputs.tag_exists == 'false'
        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3
        with:
          tag_name: v${{ steps.get-version.outputs.version }}
          name: Release v${{ steps.get-version.outputs.version }}
          body_path: /tmp/release_body.md
          draft: false
          prerelease: false
        env:
          # ACTIONS_TOKEN preferred for release creation
          GITHUB_TOKEN: ${{ secrets.ACTIONS_TOKEN || github.token }}

      - name: Create release summary
        if: steps.check-tag.outputs.tag_exists == 'false'
        # The changelog (Claude-generated or curated) is untrusted, so it is read
        # from the file written by the compose step — its markdown must not break
        # out into the shell (same reason the prompt inputs use env above).
        env:
          VERSION: ${{ steps.get-version.outputs.version }}
          LAST_TAG: ${{ steps.analyze-changes.outputs.last_tag }}
        run: |
          echo "## 🚀 Release v$VERSION Created" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "**Release URL:** [v$VERSION](https://github.com/${{ github.repository }}/releases/tag/v$VERSION)" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "### 📊 Statistics" >> $GITHUB_STEP_SUMMARY
          echo "- **Commits:** ${{ steps.analyze-changes.outputs.commits_count }}" >> $GITHUB_STEP_SUMMARY
          echo "- **Files Changed:** ${{ steps.analyze-changes.outputs.files_changed }}" >> $GITHUB_STEP_SUMMARY
          echo "- **Lines Added:** ${{ steps.analyze-changes.outputs.additions }}" >> $GITHUB_STEP_SUMMARY
          echo "- **Lines Deleted:** ${{ steps.analyze-changes.outputs.deletions }}" >> $GITHUB_STEP_SUMMARY
          echo "- **Previous Release:** ${LAST_TAG}" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "### 📝 Changelog" >> $GITHUB_STEP_SUMMARY
          cat /tmp/release_changelog.md >> $GITHUB_STEP_SUMMARY

      - name: Set outputs
        id: set-outputs
        if: steps.check-tag.outputs.tag_exists == 'false'
        env:
          VERSION: ${{ steps.get-version.outputs.version }}
        run: |
          TAG_NAME="v$VERSION"
          RELEASE_URL="https://github.com/${{ github.repository }}/releases/tag/$TAG_NAME"

          echo "tag_name=$TAG_NAME" >> $GITHUB_OUTPUT
          echo "version=$VERSION" >> $GITHUB_OUTPUT
          echo "release_url=$RELEASE_URL" >> $GITHUB_OUTPUT

          echo "✅ Outputs set: tag=$TAG_NAME, version=$VERSION"