sync-documentation.yml

name: Sync Documentation from SharpMUSH

on:
  schedule:
    # Run daily at 6 AM UTC
    - cron: '0 6 * * *'
  workflow_dispatch:
    # Allow manual triggering
  push:
    branches:
      - main
    paths:
      - '.github/workflows/sync-documentation.yml'
      - '.github/scripts/**'

env:
  UPSTREAM_DOCS: temp-sharpmush/SharpMUSH.Documentation/Helpfiles/SharpMUSH

jobs:
  sync-docs:
    runs-on: ubuntu-latest

    permissions:
      contents: write

    steps:
      - name: Checkout current repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          # Needed so the keepalive step can read the age of the last commit.
          fetch-depth: 0

      - name: Setup Git
        run: |
          git config --global user.name 'github-actions[bot]'
          git config --global user.email '41898282+github-actions[bot]@users.noreply.github.com'

      - name: Clone SharpMUSH repository
        run: |
          # Only the helpfiles are needed; the rest of the tree is a large
          # checkout we would immediately throw away.
          git clone --depth 1 --filter=blob:none --sparse \
            https://github.com/SharpMUSH/SharpMUSH.git temp-sharpmush
          git -C temp-sharpmush sparse-checkout set SharpMUSH.Documentation/Helpfiles

      - name: Verify upstream documentation layout
        run: |
          # Fail loudly rather than "succeeding" with an empty sync: a silent
          # no-op here is indistinguishable from "upstream had no changes", and
          # would hide an upstream path rename for months.
          if [ ! -d "$UPSTREAM_DOCS" ]; then
            echo "::error::Upstream documentation folder not found at $UPSTREAM_DOCS. Did SharpMUSH/SharpMUSH move its helpfiles?"
            exit 1
          fi

          missing=0
          for helpfile in sharpfunc.md sharpcmd.md sharpconf.md; do
            if [ ! -f "$UPSTREAM_DOCS/$helpfile" ]; then
              echo "::error::Expected helpfile '$helpfile' is missing from $UPSTREAM_DOCS"
              missing=1
            fi
          done
          if [ "$missing" -ne 0 ]; then
            echo "Files actually present:"
            ls -la "$UPSTREAM_DOCS"
            exit 1
          fi

          echo "Upstream documentation layout verified."

      - name: Make scripts executable
        run: chmod +x .github/scripts/*.sh

      - name: Process and organize documentation
        id: process_docs
        run: ./.github/scripts/process_documentation.sh "$UPSTREAM_DOCS" "temp-processed"

      - name: Update documentation folders
        run: ./.github/scripts/update_documentation_folders.sh temp-processed

      - name: Clean up temporary files
        if: always()
        run: rm -rf temp-sharpmush temp-processed

      - name: Check for changes
        id: check_changes
        run: |
          git add -A
          if git diff --cached --quiet; then
            echo "changes=false" >> $GITHUB_OUTPUT
            echo "No changes detected"
          else
            echo "changes=true" >> $GITHUB_OUTPUT
            echo "Changes detected"
            git diff --cached --stat
          fi

      - name: Commit and push changes
        # Guarded on main for the same reason as the keepalive step below:
        # workflow_dispatch can run on any branch, actions/checkout takes the
        # triggering ref, and this pushes HEAD to main.
        if: steps.check_changes.outputs.changes == 'true' && github.ref == 'refs/heads/main'
        run: |
          git commit -m "docs: sync documentation from SharpMUSH/SharpMUSH" -m "Updated documentation:
          - Functions: ${{ steps.process_docs.outputs.function_count }} files
          - Commands: ${{ steps.process_docs.outputs.command_count }} files
          - Configuration: ${{ steps.process_docs.outputs.config_count }} files

          Source: SharpMUSH/SharpMUSH repository
          Date: $(date -u '+%Y-%m-%d %H:%M:%S UTC')"

          git push origin HEAD:main

      - name: Keep the schedule alive
        if: steps.check_changes.outputs.changes != 'true' && github.ref == 'refs/heads/main'
        run: |
          # GitHub disables a scheduled workflow after 60 days without repository
          # activity, and a sync commit is the only activity this repo normally
          # gets. Upstream helpfiles went untouched from 2026-03-04 to
          # 2026-06-14 (102 days), which is exactly what silently disabled this
          # workflow. Commit a dated marker before the repo reaches the cutoff.
          last_commit_epoch=$(git log -1 --format=%ct)
          age_days=$(( ( $(date -u +%s) - last_commit_epoch ) / 86400 ))
          echo "Days since last commit: $age_days"

          if [ "$age_days" -lt 45 ]; then
            echo "Below the 45-day keepalive threshold; nothing to do."
            exit 0
          fi

          date -u '+%Y-%m-%dT%H:%M:%SZ' > .github/last-sync-check
          git add .github/last-sync-check
          git commit -m "chore: keepalive commit so the docs sync schedule is not auto-disabled"
          git push origin HEAD:main
          echo "keepalive=true" >> $GITHUB_ENV

      - name: Create summary
        if: always()
        run: |
          {
            echo "## Documentation Sync Summary"
            echo ""
            if [ "${{ job.status }}" != "success" ]; then
              echo "❌ **Sync failed** - see the failing step above"
            elif [ "${{ steps.check_changes.outputs.changes }}" == "true" ]; then
              echo "✅ **Documentation successfully synced**"
              echo ""
              echo "### Entries extracted:"
              echo "- **Functions**: ${{ steps.process_docs.outputs.function_count }} files"
              echo "- **Commands**: ${{ steps.process_docs.outputs.command_count }} files"
              echo "- **Configuration**: ${{ steps.process_docs.outputs.config_count }} files"
            elif [ "${{ steps.check_changes.outputs.changes }}" == "false" ]; then
              echo "✅ **No changes detected** - documentation is already up to date"
              if [ "${keepalive:-}" == "true" ]; then
                echo ""
                echo "A keepalive commit was pushed to stop GitHub auto-disabling this schedule."
              fi
            else
              echo "❌ **Sync failed before the change check** - see the failing step above"
            fi
            echo ""
            echo "📅 **Sync Date**: $(date -u '+%Y-%m-%d %H:%M:%S UTC')"
          } >> $GITHUB_STEP_SUMMARY