book-build.yml

name: Build & Release Book PDF

on:
  push:
    branches: [master, main]
    paths:
      - 'docs/book/**'
    tags:
      - 'v*'
  pull_request:
    paths:
      - 'docs/book/**'
  release:
    types: [published, created]
  workflow_dispatch:

concurrency:
  group: book-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: write

env:
  PANDOC_VERSION: "3.1.11"

jobs:
  # ═══════════════════════════════════════════════════
  # 1. VALIDATE BOOK SOURCE
  # ═══════════════════════════════════════════════════
  validate:
    name: Validate Book Source
    runs-on: ubuntu-latest
    outputs:
      lines: ${{ steps.check.outputs.lines }}
      has_book: ${{ steps.check.outputs.has_book }}
    steps:
      - uses: actions/checkout@v4

      - name: Check book source
        id: check
        run: |
          if [ ! -f docs/book/book.md ]; then
            echo "has_book=false" >> $GITHUB_OUTPUT
            echo "lines=0" >> $GITHUB_OUTPUT
            echo "WARNING: docs/book/book.md not found — skipping PDF build"
            exit 0
          fi
          echo "has_book=true" >> $GITHUB_OUTPUT
          LINES=$(wc -l < docs/book/book.md)
          echo "lines=$LINES" >> $GITHUB_OUTPUT
          echo "Book source: $LINES lines"

      - name: Strip control characters
        if: steps.check.outputs.has_book == 'true'
        run: |
          sed -i 's/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]//g' docs/book/book.md
          echo "Control characters cleaned"

      - name: Validate structure
        if: steps.check.outputs.has_book == 'true'
        run: |
          CHAPTERS=$(grep -c "^## " docs/book/book.md || echo 0)
          echo "Chapters: $CHAPTERS"
          if grep -qi "Srikanth Patchava" docs/book/book.md; then
            echo "Author: verified"
          fi
          TABLES=$(grep -c "^|" docs/book/book.md || echo 0)
          CODE_BLOCKS=$(grep -c '```' docs/book/book.md || echo 0)
          echo "Tables: $TABLES lines"
          echo "Code blocks: $((CODE_BLOCKS / 2))"

  # ═══════════════════════════════════════════════════
  # 2. BUILD PDF
  # ═══════════════════════════════════════════════════
  build-pdf:
    name: Build PDF
    runs-on: ubuntu-latest
    needs: validate
    if: needs.validate.outputs.has_book == 'true'
    outputs:
      pdf_name: ${{ steps.meta.outputs.pdf_name }}
      pdf_size: ${{ steps.verify.outputs.pdf_size }}
    steps:
      - uses: actions/checkout@v4

      - name: Install pandoc & LaTeX
        run: |
          sudo apt-get update
          sudo apt-get install -y pandoc texlive-xetex texlive-fonts-recommended texlive-fonts-extra

      - name: Clean source
        run: sed -i 's/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]//g' docs/book/book.md

      - name: Extract metadata
        id: meta
        run: |
          REPO_NAME="${GITHUB_REPOSITORY#*/}"
          echo "repo_name=$REPO_NAME" >> $GITHUB_OUTPUT
          echo "pdf_name=${REPO_NAME}-guide.pdf" >> $GITHUB_OUTPUT
          TITLE=$(head -5 docs/book/book.md | grep "^# " | head -1 | sed 's/^# //')
          if [ -z "$TITLE" ]; then TITLE="$REPO_NAME — Official Guide"; fi
          echo "title=$TITLE" >> $GITHUB_OUTPUT
          # Version from tag or commit SHA
          if [[ "$GITHUB_REF" == refs/tags/* ]]; then
            VERSION="${GITHUB_REF#refs/tags/}"
          else
            VERSION="dev-$(echo $GITHUB_SHA | cut -c1-7)"
          fi
          echo "version=$VERSION" >> $GITHUB_OUTPUT
          echo "Building: $TITLE ($VERSION)"

      - name: Generate PDF
        run: |
          pandoc \
            docs/book/book.md \
            -o "docs/book/${{ steps.meta.outputs.pdf_name }}" \
            --pdf-engine=xelatex \
            --from=markdown+smart \
            -V geometry:margin=1in \
            -V fontsize=11pt \
            -V documentclass=report \
            -V "title=${{ steps.meta.outputs.title }}" \
            -V "subtitle=Version ${{ steps.meta.outputs.version }}" \
            -V "author=Srikanth Patchava \\& EmbeddedOS Contributors" \
            -V "date=$(date +'%B %Y')" \
            -V toc=true \
            -V toc-depth=3 \
            -V colorlinks=true \
            -V linkcolor=blue \
            -V urlcolor=blue \
            -V "header-includes=\\usepackage{fancyhdr}\\pagestyle{fancy}\\fancyhead[R]{\\small ${{ steps.meta.outputs.version }}}" \
            --highlight-style=tango \
            --number-sections

      - name: Verify PDF
        id: verify
        run: |
          PDF="docs/book/${{ steps.meta.outputs.pdf_name }}"
          if [ ! -f "$PDF" ]; then
            echo "ERROR: PDF not generated"
            exit 1
          fi
          SIZE=$(du -h "$PDF" | cut -f1)
          BYTES=$(wc -c < "$PDF")
          echo "pdf_size=$SIZE" >> $GITHUB_OUTPUT
          echo "PDF: $PDF ($SIZE, $BYTES bytes)"
          if [ "$BYTES" -lt 1000 ]; then
            echo "ERROR: PDF too small — likely corrupted"
            exit 1
          fi

      - name: Upload PDF artifact
        uses: actions/upload-artifact@v4
        with:
          name: ${{ steps.meta.outputs.pdf_name }}
          path: docs/book/${{ steps.meta.outputs.pdf_name }}
          retention-days: 90

  # ═══════════════════════════════════════════════════
  # 3. ATTACH TO RELEASE (any release or tag)
  # ═══════════════════════════════════════════════════
  attach-to-release:
    name: Attach PDF to Release
    runs-on: ubuntu-latest
    needs: [validate, build-pdf]
    if: github.event_name == 'release' || startsWith(github.ref, 'refs/tags/')
    steps:
      - name: Download PDF artifact
        uses: actions/download-artifact@v4
        with:
          name: ${{ needs.build-pdf.outputs.pdf_name }}
          path: ./pdf-output

      - name: Determine release tag
        id: tag
        run: |
          if [ "${{ github.event_name }}" = "release" ]; then
            echo "tag=${{ github.event.release.tag_name }}" >> $GITHUB_OUTPUT
          else
            echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
          fi

      - name: Create or update release with PDF
        uses: softprops/action-gh-release@v2
        with:
          files: ./pdf-output/${{ needs.build-pdf.outputs.pdf_name }}
          tag_name: ${{ steps.tag.outputs.tag }}
          fail_on_unmatched_files: false
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Summary
        run: |
          echo "## Book PDF Attached to Release"
          echo ""
          echo "- **Tag:** ${{ steps.tag.outputs.tag }}"
          echo "- **PDF:** ${{ needs.build-pdf.outputs.pdf_name }} (${{ needs.build-pdf.outputs.pdf_size }})"
          echo "- **Source:** ${{ needs.validate.outputs.lines }} lines"

  # ═══════════════════════════════════════════════════
  # 4. NIGHTLY DEV BUILD (latest from master)
  # ═══════════════════════════════════════════════════
  dev-release:
    name: Update Dev PDF
    runs-on: ubuntu-latest
    needs: build-pdf
    if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main')
    steps:
      - name: Download PDF artifact
        uses: actions/download-artifact@v4
        with:
          name: ${{ needs.build-pdf.outputs.pdf_name }}
          path: ./pdf-output

      - name: Update dev release
        uses: softprops/action-gh-release@v2
        with:
          tag_name: dev-latest
          name: "Development Build (Latest)"
          prerelease: true
          files: ./pdf-output/${{ needs.build-pdf.outputs.pdf_name }}
          body: |
            ## Development Book PDF — Latest from `master`

            Auto-generated from the latest `docs/book/book.md` on every push.

            - **Commit:** ${{ github.sha }}
            - **Date:** ${{ github.event.head_commit.timestamp }}
            - **PDF:** ${{ needs.build-pdf.outputs.pdf_name }} (${{ needs.build-pdf.outputs.pdf_size }})

            > This is a development build. For stable releases, see the latest tagged release.
          make_latest: false
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  # ═══════════════════════════════════════════════════
  # SUMMARY
  # ═══════════════════════════════════════════════════
  summary:
    name: Build Summary
    runs-on: ubuntu-latest
    needs: [validate, build-pdf]
    if: always()
    steps:
      - name: Report
        run: |
          echo "## Book Build Report — ${GITHUB_REPOSITORY}"
          echo ""
          echo "| Step | Status |"
          echo "|------|--------|"
          echo "| Source validation | ${{ needs.validate.result }} |"
          echo "| PDF generation | ${{ needs.build-pdf.result }} |"
          echo ""
          echo "- Source: ${{ needs.validate.outputs.lines }} lines"
          echo "- Trigger: ${{ github.event_name }}"
          echo "- Ref: ${{ github.ref }}"