deploy-docs.yml

name: Build & Deploy Docs (Pages)

on:
  push:
    branches: [main] # deploy when aggregator changes
  workflow_dispatch:
    inputs:
      # optional per-repo overrides (branch/ref/SHA); leave empty to use defaults
      miden_base_ref:
        description: "Ref for 0xMiden/miden-base"
        required: false
      miden_tutorials_ref:
        description: "Ref for 0xMiden/miden-tutorials"
        required: false
      miden_client_ref:
        description: "Ref for 0xMiden/miden-client"
        required: false
      miden_node_ref:
        description: "Ref for 0xMiden/miden-node"
        required: false
      miden_vm_ref:
        description: "Ref for 0xMiden/miden-vm"
        required: false
      compiler_ref:
        description: "Ref for 0xMiden/compiler"
        required: false
  repository_dispatch:
    types: [rebuild]

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

concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      DEFAULT_REF: next
      DEFAULT_TUTORIALS_REF: main
    steps:
      - name: Checkout docs site
        uses: actions/checkout@v4

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

      # Resolve refs per repo (inputs override DEFAULT_REF)
      - name: Resolve refs
        id: refs
        run: |
          set -e
          def="${DEFAULT_REF}"
          tutorials_def="${DEFAULT_TUTORIALS_REF}"

          # For each input: use it if set, else fallback to default ref
          base_ref='${{ inputs.miden_base_ref }}'
          [ -z "$base_ref" ] && base_ref="$def"
          echo "MIDEN_BASE_REF=$base_ref" >> $GITHUB_OUTPUT

          tutorials_ref='${{ inputs.miden_tutorials_ref }}'
          [ -z "$tutorials_ref" ] && tutorials_ref="$tutorials_def"
          echo "MIDEN_TUTORIALS_REF=$tutorials_ref" >> $GITHUB_OUTPUT

          client_ref='${{ inputs.miden_client_ref }}'
          [ -z "$client_ref" ] && client_ref="$def"
          echo "MIDEN_CLIENT_REF=$client_ref" >> $GITHUB_OUTPUT

          node_ref='${{ inputs.miden_node_ref }}'
          [ -z "$node_ref" ] && node_ref="$def"
          echo "MIDEN_NODE_REF=$node_ref" >> $GITHUB_OUTPUT

          vm_ref='${{ inputs.miden_vm_ref }}'
          [ -z "$vm_ref" ] && vm_ref="$def"
          echo "MIDEN_VM_REF=$vm_ref" >> $GITHUB_OUTPUT

          compiler_ref='${{ inputs.compiler_ref }}'
          [ -z "$compiler_ref" ] && compiler_ref="$def"
          echo "COMPILER_REF=$compiler_ref" >> $GITHUB_OUTPUT

          echo "Resolved refs:"
          echo "  miden-base:       $base_ref"
          echo "  miden-tutorials:  $tutorials_ref"
          echo "  miden-client:     $client_ref"
          echo "  miden-node:       $node_ref"
          echo "  miden-vm:         $vm_ref"
          echo "  compiler:         $compiler_ref"

      # Check out each source repo into vendor/*
      - name: Checkout 0xMiden/miden-base
        uses: actions/checkout@v4
        with:
          repository: 0xMiden/miden-base
          ref: ${{ steps.refs.outputs.MIDEN_BASE_REF }}
          path: vendor/miden-base

      - name: Checkout 0xMiden/miden-tutorials
        uses: actions/checkout@v4
        with:
          repository: 0xMiden/miden-tutorials
          ref: ${{ steps.refs.outputs.MIDEN_TUTORIALS_REF }}
          path: vendor/miden-tutorials

      - name: Checkout 0xMiden/miden-client
        uses: actions/checkout@v4
        with:
          repository: 0xMiden/miden-client
          ref: ${{ steps.refs.outputs.MIDEN_CLIENT_REF }}
          path: vendor/miden-client

      - name: Checkout 0xMiden/miden-node
        uses: actions/checkout@v4
        with:
          repository: 0xMiden/miden-node
          ref: ${{ steps.refs.outputs.MIDEN_NODE_REF }}
          path: vendor/miden-node

      - name: Checkout 0xMiden/miden-vm
        uses: actions/checkout@v4
        with:
          repository: 0xMiden/miden-vm
          ref: ${{ steps.refs.outputs.MIDEN_VM_REF }}
          path: vendor/miden-vm

      - name: Checkout 0xMiden/compiler
        uses: actions/checkout@v4
        with:
          repository: 0xMiden/compiler
          ref: ${{ steps.refs.outputs.COMPILER_REF }}
          path: vendor/compiler

      # ============================================================
      # v0.4 IA: Aggregate into nested structure
      #   - Design docs (miden-base, miden-vm, compiler, miden-node) → docs/design/
      #   - Builder docs (miden-tutorials, miden-client) → docs/builder/
      # ============================================================
      - name: Aggregate docs into single docs tree
        run: |
          echo "Aggregating vendor docs into v0.4 IA structure..."

          # Clean directories that will be re-synced (v0.4 nested paths)
          rm -rf docs/design/miden-base docs/design/miden-vm docs/design/miden-node docs/design/compiler
          rm -rf docs/builder/tools/client
          # Note: docs/builder/develop/tutorials is NOT fully cleaned to preserve local tutorials (e.g. miden-bank)

          # Design docs → docs/design/*
          if [ -d "vendor/miden-base/docs/src" ]; then
            mkdir -p docs/design/miden-base
            cp -r vendor/miden-base/docs/src/* docs/design/miden-base/
            echo "Synced miden-base → docs/design/miden-base"
          fi

          if [ -d "vendor/miden-vm/docs/src" ]; then
            mkdir -p docs/design/miden-vm
            cp -r vendor/miden-vm/docs/src/* docs/design/miden-vm/
            echo "Synced miden-vm → docs/design/miden-vm"
          fi

          if [ -d "vendor/miden-node/docs/external/src" ]; then
            mkdir -p docs/design/miden-node
            cp -r vendor/miden-node/docs/external/src/* docs/design/miden-node/
            echo "Synced miden-node → docs/design/miden-node"
          fi

          if [ -d "vendor/compiler/docs/external/src" ]; then
            mkdir -p docs/design/compiler
            cp -r vendor/compiler/docs/external/src/* docs/design/compiler/
            echo "Synced compiler → docs/design/compiler"
          fi

          # Builder docs → docs/builder/*
          # Sync miden-tutorials into develop/tutorials (local tutorials are preserved)
          if [ -d "vendor/miden-tutorials/docs/src" ]; then
            mkdir -p docs/builder/develop/tutorials
            cp -r vendor/miden-tutorials/docs/src/* docs/builder/develop/tutorials/
            echo "Synced miden-tutorials → docs/builder/develop/tutorials"
          fi

          if [ -d "vendor/miden-client/docs/external/src" ]; then
            mkdir -p docs/builder/tools/client
            cp -r vendor/miden-client/docs/external/src/* docs/builder/tools/client/
            echo "Synced miden-client → docs/builder/tools/client"
          fi

          echo "Content aggregation complete. Final docs structure:"
          ls -la docs/
          echo "Design subdirs:"
          ls -la docs/design/ || true
          echo "Builder subdirs:"
          ls -la docs/builder/ || true
          echo "Tutorials subdirs:"
          ls -la docs/builder/develop/tutorials/ || true

      - name: Install deps
        run: npm install --frozen-lockfile

      - name: Build site
        env:
          NODE_OPTIONS: "--max-old-space-size=6144" # 6GB
        run: |
          echo "Building Docusaurus site"
          npm run build

      - name: Add CNAME
        run: echo docs.miden.xyz > build/CNAME

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: build

      - name: Deploy to GitHub Pages
        uses: actions/deploy-pages@v4