sync-cli-docs.yml

name: Sync CLI Docs to KeeperHub

on:
  workflow_dispatch:
  release:
    types: [published]

permissions:
  contents: read

concurrency:
  group: cli-docs-sync
  cancel-in-progress: true

jobs:
  sync:
    runs-on: ubuntu-latest
    timeout-minutes: 10

    steps:
      - name: Checkout CLI repo
        uses: actions/checkout@v4

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version-file: go.mod

      - name: Regenerate CLI docs
        run: go generate ./docs/...

      # The sync copies whatever is on disk. If regeneration changes anything,
      # the tag's committed reference did not match its own command tree, and
      # the copy would silently publish stale pages. Fail here rather than open
      # a PR that looks authoritative.
      - name: Fail if the tag's committed docs are stale
        run: |
          if ! git diff --quiet -- docs/ || [ -n "$(git ls-files --others --exclude-standard docs/)" ]; then
            echo "::error::Committed docs do not match generated output for this ref."
            git status --short -- docs/
            exit 1
          fi

      - name: Checkout KeeperHub repo
        uses: actions/checkout@v4
        with:
          repository: KeeperHub/keeperhub
          token: ${{ secrets.KEEPERHUB_PAT }}
          path: keeperhub
          ref: staging

      - name: Sync docs to KeeperHub
        id: sync
        run: |
          CLI_DOCS="docs"
          KH_DOCS="keeperhub/docs/cli"

          # Sync command reference files
          rm -rf "$KH_DOCS/commands/"kh*.md
          cp "$CLI_DOCS/"kh*.md "$KH_DOCS/commands/"

          # A partial copy publishes a reference that looks complete but omits
          # commands entirely, which reads as "this command does not exist".
          GENERATED=$(find "$CLI_DOCS" -maxdepth 1 -name 'kh*.md' | wc -l)
          COPIED=$(find "$KH_DOCS/commands" -maxdepth 1 -name 'kh*.md' | wc -l)
          if [ "$GENERATED" -ne "$COPIED" ]; then
            echo "::error::Synced $COPIED of $GENERATED command pages."
            exit 1
          fi
          echo "Synced $COPIED command pages."

          # Sync hand-written guides (add frontmatter for Nextra)
          for file in quickstart.md concepts.md; do
            TITLE=$(head -1 "$CLI_DOCS/$file" | sed 's/^# //')

            # Build the Nextra-compatible version with frontmatter
            {
              echo "---"
              echo "title: \"$TITLE\""
              echo "description: \"KeeperHub CLI $TITLE\""
              echo "---"
              echo ""
              cat "$CLI_DOCS/$file"
            } > "$KH_DOCS/$file"
          done

          # Regenerate commands/_meta.ts from the synced files
          {
            echo "export default {"
            for f in "$KH_DOCS/commands/"kh*.md; do
              stem=$(basename "$f" .md)
              label=$(echo "$stem" | sed 's/_/ /g')
              # Quote keys that contain hyphens
              if echo "$stem" | grep -q '-'; then
                echo "  \"$stem\": \"$label\","
              else
                echo "  $stem: \"$label\","
              fi
            done
            echo "};"
          } > "$KH_DOCS/commands/_meta.ts"

          # Fix internal links in quickstart and concepts for Nextra
          sed -i 's|\[Command reference\](kh\.md)|[Command reference](./commands/kh)|g' "$KH_DOCS/quickstart.md"
          sed -i 's|\[concepts\.md\](concepts\.md)|[Concepts](./concepts)|g' "$KH_DOCS/quickstart.md"
          sed -i 's|\[quickstart\.md\](quickstart\.md)|[Quickstart](./quickstart)|g' "$KH_DOCS/concepts.md"

          # Check if anything changed
          cd keeperhub
          if git diff --quiet && [ -z "$(git ls-files --others --exclude-standard docs/cli/)" ]; then
            echo "No changes to sync."
            echo "has_changes=false" >> "$GITHUB_OUTPUT"
          else
            echo "has_changes=true" >> "$GITHUB_OUTPUT"
          fi

      - name: Create PR in KeeperHub
        if: steps.sync.outputs.has_changes == 'true'
        env:
          GH_TOKEN: ${{ secrets.KEEPERHUB_PAT }}
          RELEASE_TAG: ${{ github.event.release.tag_name || 'manual' }}
        run: |
          cd keeperhub
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"

          # Sanitize tag for branch name
          SAFE_TAG=$(echo "$RELEASE_TAG" | sed 's/[^a-zA-Z0-9.-]/-/g')
          BRANCH="docs/cli-sync-${SAFE_TAG}"

          git checkout -b "$BRANCH"
          git add docs/cli/
          git commit -m "docs: sync CLI reference from ${RELEASE_TAG}"
          git push origin "$BRANCH"

          gh pr create \
            --base staging \
            --title "docs: sync CLI reference from ${RELEASE_TAG}" \
            --body "Auto-synced CLI command reference from cli@${RELEASE_TAG}. Changes generated by go generate ./docs/... and copied to docs/cli/."