Refresh vercel provider: full REST surface, make pipeline, live smoke tests, Docusaurus 3.10 microsite

.github/workflows/build-and-test.yml

@@ -0,0 +1,163 @@
+name: build-and-test
+
+# Build the vercel provider from the current upstream spec and run every
+# credential-free test layer on each push / PR; the live smoke suite runs
+# only where the Vercel secrets are configured; a scheduled spec-drift job
+# opens an issue when the served spec adds or removes operations (the
+# mapping manifest must then be reviewed).
+
+on:
+  push:
+    branches: [main, 'feature/**']
+    paths-ignore: ['website/**']
+  pull_request:
+    branches: [main]
+    paths-ignore: ['website/**']
+  schedule:
+    - cron: '23 3 * * 1'   # weekly spec-drift check (Monday 03:23 UTC)
+  workflow_dispatch:
+
+jobs:
+  build-and-test:
+    if: github.event_name != 'schedule'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      # puts the latest stackql on PATH; bin/start-server.sh and the test
+      # runners resolve it from there
+      - name: Install stackql
+        uses: stackql/setup-stackql@v2
+
+      - name: stackql version
+        run: stackql --version
+
+      # Build from the COMMITTED spec snapshot so the run is reproducible
+      # (Vercel republishes its unversioned document continuously). Upstream
+      # drift is reported as a warning here; the spec-drift job below opens
+      # the review issue. Refresh locally with `make build` and commit the
+      # snapshot, pin, manifest and generated provider together.
+      - name: Check the committed spec snapshot against upstream (warns on drift)
+        run: |
+          if ! make check-spec; then
+            echo "::warning title=Vercel OpenAPI spec drift::The served document no longer matches provider-dev/config/spec_pin.json - run 'make build && make test' locally, review the diff, and commit. Building from the committed snapshot."
+          fi
+
+      - name: Split, merge and validate the mapping manifest
+        run: make split mappings validate-mappings
+
+      - name: Normalize and generate the provider
+        run: make pre-normalize normalize generate
+
+      - name: Fail on uncommitted generation drift
+        run: |
+          git add -N .
+          if ! git diff --quiet -- provider-dev/openapi provider-dev/config/all_services.csv; then
+            echo "Generated output differs from the committed artifacts - run 'make build' locally, review, and commit."
+            git diff --stat -- provider-dev/openapi provider-dev/config/all_services.csv
+            exit 1
+          fi
+
+      - name: Offline validation
+        run: make test-offline
+
+      - name: Meta-route tests
+        run: make test-meta
+
+      - name: Generate docs (sanity - the site build runs on the web workflows)
+        run: make docs
+
+  smoke:
+    # secret-gated live smoke suite against a dedicated Hobby team; skipped
+    # with a notice when the secrets are not configured (forks, external PRs).
+    runs-on: ubuntu-latest
+    needs: build-and-test
+    if: github.event_name != 'pull_request' && github.event_name != 'schedule'
+    env:
+      VERCEL_API_TOKEN: ${{ secrets.VERCEL_API_TOKEN }}
+      VERCEL_TEAM_ID: ${{ secrets.VERCEL_TEAM_ID }}
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install stackql
+        uses: stackql/setup-stackql@v2
+
+      - name: Live smoke suite (reads + project / env var / edge config / deployment lifecycle)
+        if: env.VERCEL_API_TOKEN != ''
+        run: make smoke
+
+      - name: Live smoke skipped (no credentials)
+        if: env.VERCEL_API_TOKEN == ''
+        run: |
+          echo "::notice title=Live smoke suite skipped::VERCEL_API_TOKEN is not configured - the live smoke suite did not run."
+
+  spec-drift:
+    # Diff the served spec against the pin on a schedule and on demand, and
+    # open an issue when it moves.
+    runs-on: ubuntu-latest
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Fetch and compare against the pin
+        id: drift
+        run: |
+          set +e
+          make check-spec > fetch.log 2>&1
+          rc=$?
+          set -e
+          cat fetch.log
+          if [ "$rc" -eq 0 ]; then
+            echo "drift=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "drift=true" >> "$GITHUB_OUTPUT"
+            # materialise what changed for the issue body
+            make fetch-spec split mappings > /dev/null 2>&1 || true
+            { npm run validate-mappings 2>&1 || true; } | tail -60 > drift.txt
+            cat drift.txt
+          fi
+
+      - name: Report drift
+        if: steps.drift.outputs.drift == 'true'
+        uses: actions/github-script@v9
+        with:
+          script: |
+            const fs = require('fs');
+            const stat = fs.existsSync('drift.txt') ? fs.readFileSync('drift.txt', 'utf8') : '(details unavailable)';
+            const title = 'Vercel OpenAPI spec drift detected';
+            const body = 'The document served at https://openapi.vercel.sh/ no longer matches provider-dev/config/spec_pin.json.\n\nMapping validation against the refreshed spec:\n\n```\n' + stat + '\n```\nRun `make build && make test`, map any new operations in provider-dev/config/all_services.csv (or delete rows for removed ones), update NOTES.md, and commit.';
+            await core.summary.addHeading(title).addCodeBlock(stat).write();
+            const { data: issues } = await github.rest.issues.listForRepo({
+              owner: context.repo.owner, repo: context.repo.repo, state: 'open', labels: 'spec-drift'
+            });
+            if (issues.some(i => i.title === title)) return;
+            await github.rest.issues.create({
+              owner: context.repo.owner, repo: context.repo.repo, title, body, labels: ['spec-drift']
+            });

.github/workflows/prod-web-deploy.yml

@@ -1,58 +1,58 @@
-name: Deploy to GitHub Pages
-
-on:
-  push:
-    branches:
-      - main
-    paths:
-      - 'website/**'      
-
-jobs:
-  build:
-    name: Build Docusaurus
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: yarn
-          cache-dependency-path: website/yarn.lock
-
-      - name: Install dependencies
-        run: yarn install --frozen-lockfile
-        working-directory: website
-
-      - name: Build website
-        run: yarn build
-        working-directory: website
-
-      - name: Upload Build Artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: website/build # Ensure the path is correctly set to the Docusaurus build output
-
-  deploy:
-    name: Deploy to GitHub Pages
-    needs: build
-
-    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
-    permissions:
-      pages: write # to deploy to Pages
-      id-token: write # to verify the deployment originates from an appropriate source
-
-    # Deploy to the github-pages environment
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-
-    runs-on: ubuntu-latest
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
-        with:
-          working-directory: website/build # Ensures the correct directory is used for deployment
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'website/**'      
+
+jobs:
+  build:
+    name: Build Docusaurus
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 20
+          cache: yarn
+          cache-dependency-path: website/yarn.lock
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+        working-directory: website
+
+      - name: Build website
+        run: yarn build
+        working-directory: website
+
+      - name: Upload Build Artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: website/build # Ensure the path is correctly set to the Docusaurus build output
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5
+        with:
+          working-directory: website/build # Ensures the correct directory is used for deployment

.github/workflows/test-web-deploy.yml

@@ -1,31 +1,31 @@
-name: Test deployment
-
-on:
-  pull_request:
-    branches:
-      - main
-    paths:
-      - 'website/**'
-      
-jobs:
-  test-deploy:
-    name: Test deployment
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: yarn
-          cache-dependency-path: website/yarn.lock
-
-      - name: Install dependencies
-        run: yarn install --frozen-lockfile
-        working-directory: website
-
-      - name: Test build website
-        run: yarn build
+name: Test deployment
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'website/**'
+
+jobs:
+  test-deploy:
+    name: Test deployment
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 20
+          cache: yarn
+          cache-dependency-path: website/yarn.lock
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+        working-directory: website
+
+      - name: Test build website
+        run: yarn build
         working-directory: website