chore(nx-dev): sync docs kb articles into the pylon knowledge base

.github/workflows/pylon-kb-sync.yml

@@ -0,0 +1,110 @@
+name: Pylon KB Sync
+
+# Mirrors astro-docs/src/content/docs/kb into the Pylon knowledge base so the
+# support widget can suggest these articles as answers. nx.dev stays canonical.
+
+on:
+  schedule:
+    - cron: '0 7 * * *'
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        description: 'Report changes without writing to Pylon'
+        type: boolean
+        default: true
+      prune:
+        description: 'Delete Pylon articles whose source page no longer exists'
+        type: boolean
+        default: false
+  # Changes to the tooling or to the articles it converts are exercised on the
+  # PR itself, always as a dry run so a review never writes to Pylon.
+  pull_request:
+    paths:
+      - 'astro-docs/scripts/pylon/**'
+      - 'astro-docs/src/content/docs/kb/**'
+      - '.github/workflows/pylon-kb-sync.yml'
+
+permissions: {}
+
+jobs:
+  # Conversion is worth checking on every PR, including forks, and needs no
+  # credentials to do it.
+  preview:
+    if: ${{ github.repository_owner == 'nrwl' }}
+    permissions:
+      contents: read # to fetch code (actions/checkout)
+    runs-on: ubuntu-latest
+    name: Render articles
+    steps:
+      - name: Checkout
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+
+      - name: Setup dev tools with mise
+        uses: jdx/mise-action@146a28175021df8ca24f8ee1828cc2a60f980bd5 # v3
+
+      - name: Enable corepack and install pnpm
+        run: |
+          corepack enable
+          corepack prepare --activate
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Convert every article
+        working-directory: astro-docs
+        run: pnpm exec tsx scripts/pylon/render-preview.ts
+
+  sync:
+    # Fork PRs get no secrets, so the sync would only fail on a missing token.
+    if: ${{ github.repository_owner == 'nrwl' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) }}
+    needs: preview
+    permissions:
+      contents: read # to fetch code (actions/checkout)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+
+      - name: Setup dev tools with mise
+        uses: jdx/mise-action@146a28175021df8ca24f8ee1828cc2a60f980bd5 # v3
+
+      - name: Enable corepack and install pnpm
+        run: |
+          corepack enable
+          corepack prepare --activate
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Sync knowledge base
+        working-directory: astro-docs
+        env:
+          PYLON_API_TOKEN: ${{ secrets.PYLON_API_TOKEN }}
+          PYLON_AUTHOR_USER_ID: ${{ vars.PYLON_AUTHOR_USER_ID }}
+          DRY_RUN: ${{ github.event_name == 'pull_request' || inputs.dry-run }}
+          PRUNE: ${{ inputs.prune }}
+        run: |
+          # Both variables arrive as the literal strings "true"/"false"/"", so
+          # they have to be compared rather than tested for emptiness.
+          args=""
+          if [ "$DRY_RUN" = "true" ]; then args="$args --dry-run"; fi
+          if [ "$PRUNE" = "true" ]; then args="$args --prune"; fi
+          echo "sync-kb.ts$args"
+          pnpm exec tsx scripts/pylon/sync-kb.ts $args
+
+  report:
+    if: ${{ always() && github.repository_owner == 'nrwl' && github.event_name == 'schedule' }}
+    needs: sync
+    runs-on: ubuntu-latest
+    name: Report status
+    steps:
+      - name: Send notification
+        uses: ravsamhq/notify-slack-action@be814b201e233b2dc673608aa46e5447c8ab13f2 # v11
+        with:
+          status: ${{ needs.sync.result }}
+          message_format: '{emoji} Pylon KB sync has {status_message}'
+          notification_title: '{workflow}'
+          footer: '<{run_url}|View Run> / Last commit <{commit_url}|{commit_sha}>'
+          notify_when: 'failure'
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.ACTION_MONITORING_SLACK }}

astro-docs/project.json

@@ -171,6 +171,22 @@
         "{projectRoot}/scripts/vale-changed.mjs"
       ]
     },
+    "pylon-sync": {
+      "//": "Mirrors src/content/docs/kb into the Pylon knowledge base. Needs PYLON_API_TOKEN. Runs nightly via .github/workflows/pylon-kb-sync.yml",
+      "cache": false,
+      "command": "tsx scripts/pylon/sync-kb.ts",
+      "options": {
+        "cwd": "astro-docs"
+      }
+    },
+    "pylon-preview": {
+      "//": "Renders kb articles through the Pylon converter offline, no API token needed",
+      "cache": false,
+      "command": "tsx scripts/pylon/render-preview.ts",
+      "options": {
+        "cwd": "astro-docs"
+      }
+    },
     "format": {
       "cache": true,
       "//": "nx format doesn't respect overrides, so we manually run prettier for mdoc files",