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/protocol"
        required: false
      miden_tutorials_ref:
        description: "Ref for 0xMiden/tutorials"
        required: false
      miden_client_ref:
        description: "Ref for 0xMiden/miden-client"
        required: false
      miden_node_ref:
        description: "Ref for 0xMiden/node"
        required: false
      note_transport_ref:
        description: "Ref for 0xMiden/note-transport-service"
        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
      DEFAULT_NOTE_TRANSPORT_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}"
          note_transport_def="${DEFAULT_NOTE_TRANSPORT_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

          note_transport_ref='${{ inputs.note_transport_ref }}'
          [ -z "$note_transport_ref" ] && note_transport_ref="$note_transport_def"
          echo "NOTE_TRANSPORT_REF=$note_transport_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 "  protocol:         $base_ref"
          echo "  tutorials:        $tutorials_ref"
          echo "  miden-client:     $client_ref"
          echo "  node:             $node_ref"
          echo "  note-transport:   $note_transport_ref"
          echo "  miden-vm:         $vm_ref"
          echo "  compiler:         $compiler_ref"

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

      - name: Checkout 0xMiden/tutorials
        uses: actions/checkout@v4
        with:
          repository: 0xMiden/tutorials
          ref: ${{ steps.refs.outputs.MIDEN_TUTORIALS_REF }}
          path: vendor/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/node
        uses: actions/checkout@v4
        with:
          repository: 0xMiden/node
          ref: ${{ steps.refs.outputs.MIDEN_NODE_REF }}
          path: vendor/node

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

      - 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
      #   - Reference docs (protocol, miden-vm, compiler, node) → docs/reference/
      #   - Builder docs (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/reference/protocol docs/reference/miden-vm docs/reference/node docs/reference/compiler
          # tools/clients: only clean ingested subdirs; preserve locally-authored web-client/, react-sdk/, index.md
          rm -rf docs/builder/tools/clients/rust-client
          rm -rf docs/builder/tools/clients/img
          rm -rf docs/builder/tools/clients/theme
          rm -f  docs/builder/tools/clients/common-errors.md
          rm -f  docs/builder/tools/clients/_category_.yml
          rm -rf docs/builder/tools/cli
          # tutorials: only clean ingested subdirs/files; preserve locally-authored rust-compiler/, index.md, _category_.json, recipes/_category_.json, recipes/{rust,web}/_category_.json
          rm -rf docs/builder/tutorials/miden-bank
          rm -rf docs/builder/tutorials/components
          rm -rf docs/builder/tutorials/img
          rm -rf docs/builder/tutorials/theme
          rm -f  docs/builder/tutorials/miden_node_setup.md
          # Recipes: remove everything under recipes/rust|web except _category_.json (restored via git checkout after re-ingest)
          for d in docs/builder/tutorials/recipes/rust docs/builder/tutorials/recipes/web; do
            if [ -d "$d" ]; then
              find "$d" -mindepth 1 ! -name _category_.json -exec rm -rf {} + 2>/dev/null || true
            fi
          done
          rm -rf docs/builder/tutorials/recipes/img

          # Reference docs → docs/reference/*
          if [ -d "vendor/protocol/docs/src" ]; then
            mkdir -p docs/reference/protocol
            cp -r vendor/protocol/docs/src/* docs/reference/protocol/
            echo "Synced protocol → docs/reference/protocol"
          fi

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

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

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

          # Builder docs → docs/builder/*
          # Sync tutorials into tutorials — selective ingest.
          # rust-compiler/, index.md, miden-bank/index.md, recipes/_category_.json,
          # recipes/rust/_category_.json, recipes/web/_category_.json, and the
          # parent _category_.json are locally authored in the docs repo and
          # preserved through this clean/ingest cycle.
          # Vendor's rust-client/ and web-client/ are renamed at ingest to
          # recipes/rust/ and recipes/web/ respectively (see docs repo
          # tutorials IA redesign). plugin-client-redirects is configured in
          # docusaurus.config.ts to keep old URLs pointing at the new ones.
          # lib.rs and vendor's _category_.yml are deliberately NOT ingested.
          if [ -d "vendor/tutorials/docs/src" ]; then
            mkdir -p docs/builder/tutorials
            for name in miden-bank components img theme; do
              src="vendor/tutorials/docs/src/$name"
              [ -d "$src" ] && cp -r "$src" docs/builder/tutorials/
            done
            for name in miden_node_setup.md; do
              src="vendor/tutorials/docs/src/$name"
              [ -f "$src" ] && cp    "$src" docs/builder/tutorials/
            done

            # Rename rust-client → recipes/rust, web-client → recipes/web.
            # Copy CONTENTS (using /. and ensuring the target dir exists) so
            # the locally-authored _category_.json already in recipes/{rust,web}/
            # isn't shadowed by a nested rust-client/ or web-client/ subdir.
            mkdir -p docs/builder/tutorials/recipes/rust
            mkdir -p docs/builder/tutorials/recipes/web
            if [ -d "vendor/tutorials/docs/src/rust-client" ]; then
              cp -r vendor/tutorials/docs/src/rust-client/. docs/builder/tutorials/recipes/rust/
              rm -f docs/builder/tutorials/recipes/rust/_category_.yml
            fi
            if [ -d "vendor/tutorials/docs/src/web-client" ]; then
              cp -r vendor/tutorials/docs/src/web-client/. docs/builder/tutorials/recipes/web/
              rm -f docs/builder/tutorials/recipes/web/_category_.yml
            fi
            # Ingested recipe pages use relative image paths like ../img/...
            # which now resolves under recipes/img/. Mirror the tutorials/img
            # dir into recipes/img/ so those refs keep working after the rename.
            if [ -d "vendor/tutorials/docs/src/img" ]; then
              cp -r vendor/tutorials/docs/src/img docs/builder/tutorials/recipes/
            fi
            # Restore locally-authored files over vendor versions.
            git checkout HEAD -- docs/builder/tutorials/miden-bank/index.md 2>/dev/null || true
            git checkout HEAD -- docs/builder/tutorials/recipes/_category_.json 2>/dev/null || true
            git checkout HEAD -- docs/builder/tutorials/recipes/rust/_category_.json 2>/dev/null || true
            git checkout HEAD -- docs/builder/tutorials/recipes/web/_category_.json 2>/dev/null || true
            echo "Synced tutorials (miden-bank, components, img, theme, miden_node_setup.md, recipes/rust, recipes/web) → docs/builder/tutorials"
          fi

          if [ -d "vendor/miden-client/docs/external/src" ]; then
            mkdir -p docs/builder/tools/clients
            # Selective ingestion: only subdirs/files we still auto-sync from miden-client.
            # web-client/, react-sdk/, and top-level index.md are locally authored in the docs repo
            # — they are preserved through this clean/ingest cycle.
            for name in rust-client img theme; do
              src="vendor/miden-client/docs/external/src/$name"
              [ -d "$src" ] && cp -r "$src" docs/builder/tools/clients/
            done
            for name in common-errors.md _category_.yml; do
              src="vendor/miden-client/docs/external/src/$name"
              [ -f "$src" ] && cp "$src" docs/builder/tools/clients/
            done
            echo "Synced miden-client (rust-client, img, theme, common-errors, _category_) → docs/builder/tools/clients"
          fi

          if [ -d "vendor/note-transport-service/docs/external/src" ]; then
            rm -rf docs/builder/tools/note-transport
            mkdir -p docs/builder/tools/note-transport
            cp -r vendor/note-transport-service/docs/external/src/* docs/builder/tools/note-transport/
            echo "Synced note-transport-service → docs/builder/tools/note-transport"
          fi

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

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

      - name: Build site
        env:
          NODE_OPTIONS: "--max-old-space-size=12288" # 12GB
        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