docs.yml

name: Deploy Documentation

on:
  push:
    branches:
      - main
      - 'labs/**'
    paths:
      - 'docs/**'
      - 'scripts/collect-labs.sh'
      - 'LABS.md'
  workflow_dispatch:
    inputs:
      wiki_only:
        description: 'Sync wiki only (skip pages deploy)'
        required: false
        default: 'false'
        type: choice
        options:
          - 'false'
          - 'true'

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

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

jobs:
  build:
    runs-on: ubuntu-latest
    if: ${{ !(github.event_name == 'workflow_dispatch' && inputs.wiki_only == 'true') }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0    # Full history — needed to access labs/* branches

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install MkDocs and dependencies
        run: |
          pip install mkdocs-material pymdown-extensions mkdocs-callouts

      - name: Collect Labs branches
        run: ./scripts/collect-labs.sh

      - name: Build documentation
        run: mkdocs build
        working-directory: docs

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

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    if: ${{ !(github.event_name == 'workflow_dispatch' && inputs.wiki_only == 'true') }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

  sync-wiki:
    runs-on: ubuntu-latest
    needs: [deploy]
    if: ${{ always() && (needs.deploy.result == 'success' || needs.deploy.result == 'skipped') }}
    steps:
      - name: Checkout main repo
        uses: actions/checkout@v4
        with:
          path: main

      - name: Checkout wiki
        uses: actions/checkout@v4
        with:
          repository: ${{ github.repository }}.wiki
          path: wiki
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Sync docs to wiki
        run: |
          python3 << 'PYSCRIPT'
          import yaml, os, shutil, glob, re

          DOCS_DIR = 'main/docs/docs'
          WIKI_DIR = 'wiki'
          MKDOCS_YML = 'main/docs/mkdocs.yml'
          SCREENSHOTS_DIR = 'main/docs/screenshots'

          # ── MkDocs YAML loader (ignores !!python/name: tags) ────────
          class MkDocsLoader(yaml.SafeLoader):
              pass

          def _ignore_python_tags(loader, tag_suffix, node):
              return None

          MkDocsLoader.add_multi_constructor(
              'tag:yaml.org,2002:python/', _ignore_python_tags
          )

          # ── Single source of truth: path → wiki page name ──────────
          SPECIAL_NAMES = {
              'index.md': 'Home',
              'about.md': 'About',
              'faq.md': 'FAQ',
              'roadmap.md': 'Roadmap',
          }

          def path_to_wiki_name(rel_path):
              """Convert a docs-relative path to a wiki page name.
              
              Examples:
                index.md                        → Home
                about.md                        → About
                getting-started/quickstart.md   → Getting-Started--Quickstart
                architecture/overview.md        → Architecture--Overview
                memory/index.md                 → Memory
                cortex/index.md                 → Cortex
              """
              if rel_path in SPECIAL_NAMES:
                  return SPECIAL_NAMES[rel_path]

              path = rel_path.replace('.md', '')
              parts = path.split('/')

              # index.md in a subdirectory → use directory name only
              if parts[-1] == 'index':
                  parts = parts[:-1]

              if not parts:
                  return 'Home'

              # Title-case each segment, join with '--' (double hyphen)
              # to separate directory from filename.
              # Within each segment, hyphens become spaces for title-casing,
              # then go back to hyphens.
              def title_case_segment(seg):
                  return '-'.join(
                      word.capitalize()
                      for word in seg.replace('-', ' ').split()
                  )

              return '--'.join(title_case_segment(s) for s in parts)

          # ── 1. Clean wiki directory ─────────────────────────────────
          for f in glob.glob(os.path.join(WIKI_DIR, '*.md')):
              basename = os.path.basename(f)
              if basename != '_Footer.md':
                  os.remove(f)

          for d in ['images', 'screenshots']:
              p = os.path.join(WIKI_DIR, d)
              if os.path.isdir(p):
                  shutil.rmtree(p)

          # ── 2. Copy all .md files with wiki names ───────────────────
          page_map = {}  # rel_path → wiki_name (for link fixing)
          reverse_page_map = {}  # wiki_name → rel_path

          for root, dirs, files in os.walk(DOCS_DIR):
              for fname in files:
                  full_path = os.path.join(root, fname)
                  rel_path = os.path.relpath(full_path, DOCS_DIR)

                  if fname.endswith('.md'):
                      wiki_name = path_to_wiki_name(rel_path)
                      page_map[rel_path] = wiki_name
                      reverse_page_map[wiki_name] = rel_path
                      dest = os.path.join(WIKI_DIR, f'{wiki_name}.md')
                      shutil.copy2(full_path, dest)
                      print(f'  📄 {rel_path} → {wiki_name}.md')

                  elif fname.lower().endswith(('.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp')):
                      dest_dir = os.path.join(WIKI_DIR, 'images', os.path.dirname(rel_path))
                      os.makedirs(dest_dir, exist_ok=True)
                      shutil.copy2(full_path, os.path.join(dest_dir, fname))

          # Copy top-level screenshots
          if os.path.isdir(SCREENSHOTS_DIR):
              dest = os.path.join(WIKI_DIR, 'screenshots')
              shutil.copytree(SCREENSHOTS_DIR, dest, dirs_exist_ok=True)

          print(f'\n✅ Copied {len(page_map)} pages')

          # ── 3. Fix content in wiki pages ────────────────────────────
          for wiki_file in glob.glob(os.path.join(WIKI_DIR, '*.md')):
              basename = os.path.basename(wiki_file)
              if basename.startswith('_'):
                  continue

              wiki_name_no_ext = basename[:-3]  # remove '.md'
              rel_path = reverse_page_map.get(wiki_name_no_ext)

              with open(wiki_file, 'r', encoding='utf-8') as f:
                  content = f.read()

              # Remove YAML frontmatter
              content = re.sub(r'^---\n.*?\n---\n', '', content, count=1, flags=re.DOTALL)

              # Fix relative links to other wiki pages
              if rel_path:
                  def resolve_relative_link(source_rel_path, target_link):
                      if target_link.startswith(('http://', 'https://', 'mailto:', '#')):
                          return None
                      
                      # Handle anchors
                      anchor = ""
                      if '#' in target_link:
                          target_link, anchor = target_link.split('#', 1)
                          anchor = f"#{anchor}"
                      
                      if not target_link.endswith('.md'):
                          return None
                          
                      source_dir = os.path.dirname(source_rel_path)
                      resolved_path = os.path.normpath(os.path.join(source_dir, target_link)).replace('\\', '/')
                      return resolved_path, anchor

                  def replace_link(match):
                      text = match.group(1)
                      target = match.group(2)
                      
                      resolved = resolve_relative_link(rel_path, target)
                      if resolved:
                          resolved_path, anchor = resolved
                          if resolved_path in page_map:
                              target_wiki_name = page_map[resolved_path]
                              if text == target_wiki_name:
                                  return f"[[{target_wiki_name}{anchor}]]"
                              else:
                                  return f"[[{text}|{target_wiki_name}{anchor}]]"
                      return match.group(0)

                  # Match [text](target) but not ![image](target)
                  content = re.sub(r'(?<!\!)\[([^\]]+)\]\(([^)]+)\)', replace_link, content)

              # Fix image paths
              content = content.replace('](../screenshots/', '](screenshots/')
              content = content.replace('](../../screenshots/', '](screenshots/')

              # Convert MkDocs admonitions to blockquotes
              content = re.sub(
                  r'^!!! (\w+) "([^"]*)"',
                  r'> **\1:** \2',
                  content, flags=re.MULTILINE
              )
              content = re.sub(
                  r'^!!! quote "([^"]*)"',
                  r'> **\1**',
                  content, flags=re.MULTILINE
              )

              # Convert tabs to headings
              content = re.sub(r'^=== "([^"]*)"', r'### \1', content, flags=re.MULTILINE)

              # Convert snippets
              content = re.sub(r'^--8<-- "([^"]*)"', r'> *See: \1*', content, flags=re.MULTILINE)

              with open(wiki_file, 'w', encoding='utf-8') as f:
                  f.write(content)

          # ── 4. Generate _Sidebar.md from mkdocs nav ─────────────────
          with open(MKDOCS_YML, 'r') as f:
              config = yaml.load(f, Loader=MkDocsLoader)

          nav = config.get('nav', [])

          def write_nav(items, depth, out):
              indent = '  ' * depth
              for item in items:
                  if isinstance(item, str):
                      wiki_name = path_to_wiki_name(item)
                      out.append(f'{indent}- [[{wiki_name}]]')
                  elif isinstance(item, dict):
                      for title, value in item.items():
                          if isinstance(value, str):
                               wiki_name = path_to_wiki_name(value)
                               out.append(f'{indent}- [[{title}|{wiki_name}]]')
                          elif isinstance(value, list):
                               out.append(f'{indent}- **{title}**')
                               write_nav(value, depth + 1, out)

          sidebar_lines = [
              '**[🏠 Home](Home)**',
              '',
              '---',
              '',
          ]
          write_nav(nav, 0, sidebar_lines)

          sidebar_path = os.path.join(WIKI_DIR, '_Sidebar.md')
          with open(sidebar_path, 'w', encoding='utf-8') as f:
              f.write('\n'.join(sidebar_lines) + '\n')

          print(f'✅ Generated _Sidebar.md with {len(sidebar_lines)} lines')
          PYSCRIPT

          echo "✅ Wiki sync complete: $(ls -1 wiki/*.md | wc -l) pages"

      - name: Push wiki changes
        run: |
          cd wiki
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add -A
          git diff --cached --quiet || git commit -m "docs: sync from main repo docs [skip ci]"
          git push