sync-docs.yml

name: Sync Documentation

on:
  push:
    branches: [ main, develop ]
    paths:
      - 'docs/**'
      - 'README.md'
      - '.github/workflows/sync-docs.yml'
  workflow_dispatch:
    inputs:
      force_sync:
        description: 'Force sync even if no changes detected'
        required: false
        default: false
        type: boolean

permissions:
  contents: read
  actions: read

jobs:
  sync-docs:
    runs-on: ubuntu-latest
    if: github.repository == 'altus4/website'

    steps:
      - name: Checkout source repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.GH_TOKEN }}

      - name: Configure Git
        run: |
          git config --global user.name "docs-sync-bot"
          git config --global user.email "bot@altus4.dev"

      - name: Validate token access
        env:
          GH_TOKEN: ${{ secrets.GH_TOKEN }}
        run: |
          if [ -z "$GH_TOKEN" ]; then
            echo "ERROR: GH_TOKEN is not set or is empty"
            exit 1
          else
            echo "SUCCESS: GH_TOKEN is set"
            # Test token by making a simple API call
            curl -s -H "Authorization: token $GH_TOKEN" \
                 -H "Accept: application/vnd.github.v3+json" \
                 https://api.github.com/user | jq -r '.login // "Token validation failed"'
          fi

      - name: Check for docs changes
        id: check_changes
        run: |
          if [ "${{ github.event.inputs.force_sync }}" = "true" ]; then
            echo "has_changes=true" >> $GITHUB_OUTPUT
            echo "Force sync requested"
          elif git diff --quiet HEAD~1 HEAD -- docs/ README.md; then
            echo "has_changes=false" >> $GITHUB_OUTPUT
            echo "No changes in docs directory"
          else
            echo "has_changes=true" >> $GITHUB_OUTPUT
            echo "Changes detected in docs directory"
          fi

      - name: Get commit info
        id: commit_info
        if: steps.check_changes.outputs.has_changes == 'true'
        run: |
          COMMIT_SHA="${{ github.sha }}"
          COMMIT_MSG=$(git log -1 --pretty=format:"%s" $COMMIT_SHA)
          COMMIT_AUTHOR=$(git log -1 --pretty=format:"%an" $COMMIT_SHA)
          COMMIT_DATE=$(git log -1 --pretty=format:"%ci" $COMMIT_SHA)

          echo "sha=${COMMIT_SHA:0:7}" >> $GITHUB_OUTPUT
          echo "message=$COMMIT_MSG" >> $GITHUB_OUTPUT
          echo "author=$COMMIT_AUTHOR" >> $GITHUB_OUTPUT
          echo "date=$COMMIT_DATE" >> $GITHUB_OUTPUT

      - name: Sync to docs repository
        if: steps.check_changes.outputs.has_changes == 'true'
        env:
          DOCS_REPO_TOKEN: ${{ secrets.GH_TOKEN }}
        run: |
          # Configuration
          DOCS_REPO_URL="https://x-access-token:${DOCS_REPO_TOKEN}@github.com/altus4/docs.git"
          TEMP_DIR="/tmp/altus4-docs-sync"
          COMMIT_MESSAGE="docs: sync from ${{ steps.commit_info.outputs.sha }} - ${{ steps.commit_info.outputs.message }}"

          echo "Starting documentation sync..."
          echo "Commit: ${{ steps.commit_info.outputs.message }}"
          echo "Author: ${{ steps.commit_info.outputs.author }}"
          echo "Date: ${{ steps.commit_info.outputs.date }}"

          # Clean up any existing temp directory
          rm -rf "$TEMP_DIR"
          mkdir -p "$TEMP_DIR"
          cd "$TEMP_DIR"

          # Clone the docs repository
          echo "Cloning altus4/docs repository..."
          git clone "$DOCS_REPO_URL" .

          # Remove all existing files except .git
          echo "Clearing existing content..."
          find . -mindepth 1 -maxdepth 1 ! -name '.git' -exec rm -rf {} +

          # Copy docs directory contents
          echo "Copying documentation files..."
          cp -r "$GITHUB_WORKSPACE/docs/"* .

          # Copy README from main repository
          if [ -f "$GITHUB_WORKSPACE/README.md" ]; then
            cp "$GITHUB_WORKSPACE/README.md" ./MAIN_README.md
          fi

          # Get current date for README
          CURRENT_DATE=$(date '+%Y-%m-%d')
          CURRENT_DATETIME=$(date '+%Y-%m-%d %H:%M:%S UTC')

          # Create docs-specific README
          cat > README.md << EOF
          # Altus 4 Documentation

          ![Documentation Status](https://img.shields.io/badge/docs-auto--synced-brightgreen)
          ![Last Sync](https://img.shields.io/badge/last%20sync-${CURRENT_DATE}-blue)

          This repository contains the documentation for **Altus 4** - AI-Enhanced MySQL Full-Text Search Engine.

          ## View Documentation

          **Live Documentation**: [https://altus4.thavarshan.com/docs](https://altus4.thavarshan.com/docs)

          ## Auto-Synchronization

          This repository is automatically synchronized from the main [altus4/core](https://github.com/altus4/core) repository.

          - **Source**: \`docs/\` directory in the main repository
          - **Sync Trigger**: Any push to \`main\` or \`develop\` branch that modifies documentation
          - **Last Sync**: ${CURRENT_DATETIME}
          - **Source Commit**: [${{ steps.commit_info.outputs.sha }}](https://github.com/altus4/core/commit/${{ github.sha }})

          ## Contributing

          **Do not make direct changes to this repository!**

          To contribute to the documentation:

          1. Fork the [main repository](https://github.com/altus4/core)
          2. Make changes to the \`docs/\` directory
          3. Submit a pull request to the main repository
          4. Changes will be automatically synced here upon merge

          ## Local Development

          To work with the documentation locally:

          \`\`\`bash
          # Clone the main repository
          git clone https://github.com/altus4/core.git
          cd altus4/docs

          # Install dependencies
          npm install

          # Start development server
          npm run docs:dev

          # Build for production
          npm run docs:build
          \`\`\`

          ## Documentation Structure

          - **[Setup Guide](./setup/)** - Installation and deployment
          - **[API Reference](./api/)** - Complete API documentation
          - **[Architecture](./architecture/)** - System design and patterns
          - **[Services](./services/)** - Service layer documentation
          - **[Examples](./examples/)** - Code examples and tutorials
          - **[Development](./development/)** - Contributing guidelines
          - **[Testing](./testing/)** - Testing strategies and examples

          ## Automation Details

          This repository uses GitHub Actions for:
          - **Auto-sync** from main repository
          - **Auto-build** documentation site
          - **Auto-deploy** to GitHub Pages

          ## License

          This documentation is part of the Altus 4 project. See the [main repository](https://github.com/altus4/core) for license information.
          EOF

          # Create package.json
          cat > package.json << 'EOF'
          {
            "name": "@altus4/docs",
            "version": "1.0.0",
            "description": "Documentation for Altus 4 - AI-Enhanced MySQL Full-Text Search Engine",
            "scripts": {
              "docs:dev": "vitepress dev . --port 5174",
              "docs:build": "vitepress build .",
              "docs:preview": "vitepress preview ."
            },
            "keywords": [
              "altus4",
              "documentation",
              "mysql",
              "search",
              "ai",
              "vitepress"
            ],
            "repository": {
              "type": "git",
              "url": "https://github.com/altus4/docs.git"
            },
            "homepage": "https://altus4.thavarshan.com/docs",
            "devDependencies": {
              "vitepress": "^2.0.0-alpha.12"
            }
          }
          EOF

          # Create .gitignore
          cat > .gitignore << 'EOF'
          # Dependencies
          node_modules/
          npm-debug.log*
          yarn-debug.log*
          yarn-error.log*

          # VitePress
          .vitepress/cache/
          .vitepress/dist/

          # OS generated files
          .DS_Store
          .DS_Store?
          ._*
          .Spotlight-V100
          .Trashes
          ehthumbs.db
          Thumbs.db

          # IDE files
          .vscode/
          .idea/
          *.swp
          *.swo
          *~

          # Logs
          logs/
          *.log

          # Runtime data
          pids/
          *.pid
          *.seed
          *.pid.lock

          # Coverage directory used by tools like istanbul
          coverage/

          # Temporary folders
          tmp/
          temp/
          EOF

          # Create GitHub Pages workflow
          mkdir -p .github/workflows
          cat > .github/workflows/deploy.yml << 'EOF'
          name: Deploy Documentation to GitHub Pages

          on:
            push:
              branches: [ main ]
            workflow_dispatch:

          permissions:
            contents: read
            pages: write
            id-token: write

          concurrency:
            group: pages
            cancel-in-progress: false

          jobs:
            build:
              runs-on: ubuntu-latest
              steps:
                - name: Checkout
                  uses: actions/checkout@v4
                  with:
                    fetch-depth: 0

                - name: Setup Node.js
                  uses: actions/setup-node@v4
                  with:
                    node-version: 20
                    cache: npm

                - name: Install dependencies
                  run: npm ci

                - name: Build documentation
                  run: npm run docs:build

                - name: Setup Pages
                  uses: actions/configure-pages@v4

                - name: Upload artifact
                  uses: actions/upload-pages-artifact@v3
                  with:
                    path: .vitepress/dist

            deploy:
              environment:
                name: github-pages
                url: ${{ steps.deployment.outputs.page_url }}
              needs: build
              runs-on: ubuntu-latest
              steps:
                - name: Deploy to GitHub Pages
                  id: deployment
                  uses: actions/deploy-pages@v4
          EOF

          # Check if there are any changes
          if git diff --quiet && git diff --cached --quiet; then
            echo "WARNING: No changes to sync"
          else
            echo "SUCCESS: Changes detected, committing and pushing..."

            # Stage all changes
            git add .

            # Commit changes
            git commit -m "$COMMIT_MESSAGE"

            # Push to remote
            echo "Pushing changes to altus4/docs repository..."
            git push origin main

            echo "SUCCESS: Documentation sync completed successfully!"
          fi

      - name: Create sync summary
        if: steps.check_changes.outputs.has_changes == 'true'
        run: |
          echo "## Documentation Sync Summary" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "**Status**: Successfully synced to [altus4/docs](https://github.com/altus4/docs)" >> $GITHUB_STEP_SUMMARY
          echo "**Source Commit**: [${{ steps.commit_info.outputs.sha }}](https://github.com/${{ github.repository }}/commit/${{ github.sha }})" >> $GITHUB_STEP_SUMMARY
          echo "**Commit Message**: ${{ steps.commit_info.outputs.message }}" >> $GITHUB_STEP_SUMMARY
          echo "**Author**: ${{ steps.commit_info.outputs.author }}" >> $GITHUB_STEP_SUMMARY
          echo "**Documentation Site**: [https://altus4.thavarshan.com/docs](https://altus4.thavarshan.com/docs)" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "The documentation will be automatically deployed to GitHub Pages within a few minutes." >> $GITHUB_STEP_SUMMARY

      - name: No changes summary
        if: steps.check_changes.outputs.has_changes == 'false'
        run: |
          echo "## Documentation Sync Summary" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "**Status**: No changes detected in documentation" >> $GITHUB_STEP_SUMMARY
          echo "**Checked Paths**: \`docs/\`, \`README.md\`" >> $GITHUB_STEP_SUMMARY
          echo "**Current Documentation**: [https://altus4.thavarshan.com/docs](https://altus4.thavarshan.com/docs)" >> $GITHUB_STEP_SUMMARY