Emulate Seed

Upstream version reference: emulate 0.12.0 (2026-09-30).

Emulate Seed Configs

Generate and manage seed configs for emulate (Apache-2.0) — Vercel Labs' stateful API emulation tool. Each category has individual rule files in rules/ loaded on-demand.

Paired agent: This skill pairs with the emulate-engineer subagent (subagent_type: "ork:emulate-engineer"). When a task involves generating a full emulate config from scratch, webhook HMAC setup, CI pipeline integration, or parallel-worker port isolation, spawn the agent rather than handling it inline — it has the full 13-emulator service-port matrix and seed-rules in context.

Not mocks. Emulate provides full state machines with cascading deletes, cursor pagination, webhook delivery, and HMAC signature verification. Create a PR via the API and it appears in GET /repos/:owner/:repo/pulls. Delete a repo and its issues, PRs, and webhooks cascade-delete.

New in 2026-04 (emulate 0.4.x)

• Modular @emulators/* packages — each service is its own package (@emulators/github, @emulators/stripe, etc.); top-level emulate re-exports createEmulator and the CLI.
• 4 new services (12 total): mongoatlas:4007, okta:4008, resend:4009, stripe:4010 with drop-in seed YAML blocks.
• Resend local inbox — GET http://localhost:4009/inbox returns captured emails for assertions without hitting a real provider.
• Stripe hosted checkout — real session redirect flow + checkout.session.completed/expired webhook delivery, suitable for E2E payment tests.
• MongoDB Atlas — Admin API v2 (projects/clusters/DB users) + Data API v1 with full CRUD + aggregate.
• Okta OIDC — full discovery, JWKS, authorize/token/userinfo/revoke/introspect plus Users/Groups/Apps CRUD.
• Entra / Apple / Slack expansions (v0.4.0) — PKCE + refresh rotation (Entra), RS256 JWKS (Apple), OAuth v2 consent UI (Slack).
• @emulators/adapter-next — catch-all Next.js route handler runs emulators on the same origin as the app; fixes OAuth callback URL drift on Vercel preview deploys.

Auto-Discovery (M125 #4)

scripts/auto-discover.sh scans the project's package.json, matches deps against references/dep-to-emulator-map.json, and either reports the matches or writes emulate.config.yaml. Three modes:

$ bash "${CLAUDE_SKILL_DIR}/scripts/auto-discover.sh"
emulate-seed --auto — scanning /path/to/package.json

Detected:
  @octokit/rest  →  github · Any GitHub API client
  next-auth  →  google-oauth, apple-auth, microsoft-entra · Default OAuth providers
  stripe  →  stripe
  @vercel/blob  →  aws · @vercel/blob is S3-compatible

Union: apple-auth, aws, github, google-oauth, microsoft-entra, stripe

$ bash "${CLAUDE_SKILL_DIR}/scripts/auto-discover.sh" --apply
…
✓ Wrote /path/to/emulate.config.yaml with 6 service(s)

Multi-emulator deps default to all reasonable providers; the user prunes the YAML afterwards. Unmapped deps are silently skipped — extending coverage is a docs PR (edit references/dep-to-emulator-map.json), not a code change.

dev reads the resulting emulate.config.yaml at boot — see src/skills/dev/scripts/boot.sh.

Quick Reference

Total: 5 rules across 5 categories

Quick Start

# Install (packages published under @emulators/* scope)
npm install --save-dev emulate

# Start all services
npx emulate

# Start specific services with seed data
npx emulate --service github,stripe --seed ./emulate.config.yaml

# Generate a starter config
npx emulate init --service github

Services (0.10.0 — 14 emulators)

New across releases:

• 0.5.0 — added Clerk, MongoDB Atlas, Stripe, Resend, and Okta emulators; portless integration (embedded emulators without dedicated ports); Google OAuth hd claim support; Stripe Checkout + Resend magic link examples; AWS S3 emulator now matches the official SDK wire format.
• 0.6.0 — expanded Slack (OAuth v2 consent UI, conversations/reactions).
• 0.6.1 — Vercel Blob store.
• 0.7.0 — added Linear (13th provider): stateful orgs/teams/issues/cycles + webhooks.
• 0.8.0 — added Twilio (14th provider): accounts, phone numbers, messages, calls, conversations, messaging services, Verify flows, and simulator endpoints, with a Next.js SMS-verification example.
• 0.9.0 — added a Nuxt emulator adapter (alongside the Next.js adapter); provider count unchanged.
• 0.10.0 — stateful GitHub repository contents and commit history (GET /repos/:owner/:repo/readme, GET/PUT/DELETE /repos/:owner/:repo/contents/:path where writes produce real commits, GET /repos/:owner/:repo/commits, and GET /repositories/:id by numeric ID); a readonly generatedSecrets array on the Emulator object with a new exported GeneratedSecret type; GitHub App JWT verification now accepts PKCS#8 as well as PKCS#1 keys. Provider count unchanged.

All backwards-compatible, with one behaviour change worth knowing: 0.10.0 switched Stripe webhook deliveries to Stripe's own Stripe-Signature header format. Upstream files it under bug fixes rather than breaking changes, but a test asserting the old GitHub-style sha256= header on a Stripe delivery will now fail. See Webhook Delivery below for both formats.

See references/api-coverage.md for full endpoint lists.

Next.js Adapter (0.4+) — @emulators/adapter-next

Runs emulators on the same origin as your Next.js app via a catch-all route handler. Fixes the OAuth callback URL drift problem on Vercel preview deploys — no more http://localhost:4001 redirect mismatches.

// next.config.js
const { withEmulate } = require('@emulators/adapter-next')
module.exports = withEmulate({ /* your next config */ })

// app/api/[...emulate]/route.ts
import { createEmulateHandler } from '@emulators/adapter-next'
export const { GET, POST } = createEmulateHandler({
  services: ['github', 'stripe', 'resend'],
  persistence: { /* load(), save() or built-in filePersistence */ },
})