feat: auto-update from stacks-core

.github/workflows/sync-clarity-reference.yml

@@ -0,0 +1,92 @@
+name: Sync Clarity reference from stacks-core
+
+# Regenerates docs/reference/clarity/functions.md and keywords.md from the
+# JSON emitted by `stacks-inspect docgen` in stacks-network/stacks-core, and
+# opens a PR if there is drift.
+#
+# Currently runs on manual dispatch only. Re-enable the cron once the upstream
+# `alias` + `notices` fields have landed in stacks-core so the regeneration
+# does not strip hand-written extras from the published docs.
+
+on:
+  workflow_dispatch:
+    inputs:
+      stacks_core_ref:
+        description: "stacks-core branch/tag/sha to regenerate from"
+        required: false
+        default: "develop"
+  # schedule:
+  #   - cron: "0 12 * * 1"  # Mondays 12:00 UTC
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout docs
+        uses: actions/checkout@v4
+
+      - name: Checkout stacks-core
+        uses: actions/checkout@v4
+        with:
+          repository: stacks-network/stacks-core
+          ref: ${{ inputs.stacks_core_ref || 'develop' }}
+          path: stacks-core
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo registry & target
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            stacks-core/target
+          key: stacks-inspect-${{ runner.os }}-${{ hashFiles('stacks-core/Cargo.lock') }}
+          restore-keys: |
+            stacks-inspect-${{ runner.os }}-
+
+      - name: Build stacks-inspect
+        working-directory: stacks-core
+        run: cargo build --release -p stacks-inspect
+
+      - name: Dump Clarity API JSON
+        run: stacks-core/target/release/stacks-inspect docgen > clarity-api.json
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Regenerate reference markdown
+        run: node scripts/generate-clarity-reference.mjs clarity-api.json
+
+      - name: Detect drift
+        id: diff
+        run: |
+          if git diff --quiet -- docs/reference/clarity/functions.md docs/reference/clarity/keywords.md; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Open pull request
+        if: steps.diff.outputs.changed == 'true'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          commit-message: "chore: sync Clarity reference from stacks-core"
+          title: "chore: sync Clarity reference from stacks-core"
+          body: |
+            Regenerated `docs/reference/clarity/functions.md` and `docs/reference/clarity/keywords.md`
+            from `stacks-inspect docgen` against stacks-network/stacks-core@${{ inputs.stacks_core_ref || 'develop' }}.
+
+            Generated by `.github/workflows/sync-clarity-reference.yml`.
+          branch: chore/sync-clarity-reference
+          delete-branch: true
+          add-paths: |
+            docs/reference/clarity/functions.md
+            docs/reference/clarity/keywords.md