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

[jeffreyaven]

Summary

Rebuilds the vercel provider from the current Vercel OpenAPI document (417 operations) and brings the repository in line with the sibling provider repos: a make pipeline, a checked-in operation mapping manifest, offline / meta-route / live smoke test layers, CI, and the shared Docusaurus 3.10 microsite.

Provider

• 38 services, 134 resources, 400 methods (156 SELECT, 53 INSERT, 41 UPDATE, 6 REPLACE, 56 DELETE, 88 EXEC); 13 operations skipped with reasons in NOTES.md (OCI registry endpoints the spec places on api.vercel.com where they are not served, a 302-only download, operations with no 2xx response). Vercel has no GraphQL API.
• Bearer auth from VERCEL_API_TOKEN (Terraform parity).
• snake_case surface: snake_case_aliases: true on the provider plus request.nativeCasing: camel on every method; path parameters are physically snake_case (id_or_name, project_id).
• Pagination on 32 list methods across Vercel's five dialects (until, from, next, cursor, page number), inferred per method from the operation; LIMIT n pushed down as ?limit=n (max 100) on 37 methods.
• Naive request body translation on every write; octet-stream upload transforms on files.upload, artifacts.upload, projects.upload_avatar (@value is sent verbatim as the body); text wrappers for jsonl / ndjson / opaque responses.
• Lifecycle actions (cancel, promote, rollback, pause, restore, rerequest, test, ...) are EXEC methods on their resources, keeping non-selectable resources to 18.
• Spec corrections applied before normalize (pre_normalize.mjs), each backed by a live observation: list responses the spec declares as objects but the API returns as bare arrays, opaque oneOf placeholders that poisoned merged schemas, an undeclared microfrontends response, and request body properties colliding with a query parameter of the same name (the team slug alias), which otherwise sent an empty body.

Resource names change from the previous provider version (the old names were inconsistent and partly wrong, e.g. vercel.checks.deployments); this is the accepted one-time break. provider-dev/config/all_services.csv is now the durable record of every operation mapping and is merged, never regenerated, so names cannot drift between versions by accident.

Pipeline

make help lists every target. make all runs deps, fetch, split, mappings merge, validate, pre-normalize, normalize, generate, post-process, offline and meta-route tests, docs and the website build. It stops at validate-mappings when upstream adds or removes operations. make smoke / make smoke-live / make smoke-cleanup are separate so all never touches a Vercel account.

The Vercel document is unversioned and republished continuously, so the snapshot is committed with a hash pin (spec_pin.json); CI builds from the snapshot and warns on drift, and a weekly job opens an issue when the served document changes.

Tests

• tests/offline_validation.mjs: SHOW / DESCRIBE via stackql exec plus assertions on the generated YAML (30 checks).
• bin/test-meta-routes.cjs: every service, resource and method over a local stackql srv, DESCRIBE on every selectable resource, unique signatures per verb.
• tests/smoke_test.mjs (pgwire-lite over a server the suite starts, --live for the published provider): read smokes plus a full lifecycle mirroring the Terraform provider's headline resources: project, environment variable, Edge Config with items and a read token, a hello world index.html uploaded and deployed to production, polled to READY and fetched over HTTPS from its alias, deployment files and events, pause / unpause, then deletes. Names everything stackql-smoke-<stamp> and sweeps breadcrumbs first. Free on a Hobby team.

Results: offline 30/30, meta-route suite passing, smoke 49/49, make all green locally and in CI.

Docs

Docusaurus 3.10.2 on the shared stackql/docusaurus-config (vendored to .shared-config/ at build time), showLastUpdateTime on, generic Docusaurus scaffold removed, CNAME corrected to vercel-provider.stackql.io (it pointed at snowflake). The landing page carries getting-started queries: project inventory, deployments by state, environment variable audit, domains and DNS, Edge Config items, members and tokens, provisioning end to end and the static-site deployment walkthrough.

Known constraints (details in NOTES.md)

• Vercel scopes by a teamId query parameter; team_id must be in the WHERE clause. any-sdk honours x-stackQL-envVar on server URL variables only, so VERCEL_TEAM_ID is a scripting convention until the engine supports the extension on query parameters.
• In stackql srv, the first select method used on a resource in a session fixes its physical table (drm getTableName is keyed on resource + generation, not method); a get after a list on projects or deployments returns no rows over the wire. stackql exec is unaffected. The smoke suite works around it; this is a core issue worth a separate ticket.

Follow-ups

• Add VERCEL_API_TOKEN (and optionally VERCEL_TEAM_ID) as repository secrets so the CI smoke job runs.
• Publish to stackql-provider-registry, then make smoke-live.

🤖 Generated with Claude Code