emulate-seed

Upstream version reference: `emulate` 0.12.0 (2026-09-30). # Emulate Seed Configs Generate and manage seed configs for [emulate](https://github.com/vercel-labs/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`](../../agents/emulate-engineer.md) 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: | Mode | Behavior | |---|---| | (default) | Report matched deps + emulator union on stderr; do not write | | `--json` | Emit machine-readable JSON instead of human report | | `--apply` | Write `emulate.config.yaml` (refuses to overwrite without `--force`) | ```bash $ 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 | Category | Rules | Impact | When to Use | |----------|-------|--------|-------------| | [Seed Config](#seed-config) | 1 | HIGH | Setting up emulate.config.yaml for test environments | | [Service Selection](#service-selection) | 1 | MEDIUM | Choosing GitHub/Vercel/Google for your tests | | [Webhook Setup](#webhook-setup) | 1 | MEDIUM | Testing webhook delivery with HMAC verification | | [Parallel CI](#parallel-ci) | 1 | HIGH | Running tests in parallel without port collisions | | [Auth Tokens](#auth-tokens) | 1 | MEDIUM | Seeding tokens mapped to emulated users | **Total: 5 rules across 5 categories** ## Quick Start ```bash # 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. | Service | Default Port | Coverage | |---------|-------------|----------| | **Vercel** | `:4000` | Projects, deployments, domains, env vars, teams | | **GitHub** | `:4001` | Repos, PRs, issues, comments, reviews, Actions, webhooks, orgs, teams | | **Google OAuth** | `:4002` | OAuth 2.0 authorize, token exchange, userinfo | | **Slack** | `:4003` | Chat, conversations, users, reactions, OAuth v2 with consent UI | | **Apple Auth** | `:4004` | Sign in with Apple — OIDC discovery, JWKS (RS256), auth flow, token exchange | | **Microsoft Entra** | `:4005` | OAuth 2.0/OIDC v2.0, authorization code + PKCE, refresh token rotation, v1 token endpoint, Graph `/users/{id}` | | **AWS** | `:4006` | S3 buckets, SQS queues, IAM users/roles, STS identity | | **MongoDB Atlas** *(0.4+)* | `:4007` | Admin API v2 (projects, clusters, DB users) + Data API v1 (full CRUD + aggregate) | | **Okta** *(0.4+)* | `:4008` | OIDC discovery, JWKS, authorize/token/userinfo/revoke/introspect, Users/Groups/Apps CRUD | | **Resend** *(0.4+)* | `:4009` | Send + batch (100/req), list/retrieve/cancel, domains, API keys, audiences, contacts, **local inbox** (`GET /inbox`) | | **Stripe** *(0.4+)* | `:4010` | Customers, payment methods, customer sessions, payment intents, charges, products, prices, **hosted checkout session** w/ webhook delivery | | **Clerk** *(0.5+)* | (on-demand) | Users, sessions, organizations | | **Linear** *(0.7+)* | (on-demand) | Orgs, teams, issues, cycles, webhooks | | **Twilio** *(0.8+)* | (on-demand) | Accounts, phone numbers, messages, calls, conversations, messaging services, Verify flows, simulator endpoints | 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. ```typescript // 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 */ }, }) ``` ## Seed Config Structure A seed config pre-populates the emulator with tokens, users, repos, and projects so tests start from a known state. ```yaml # emulate.config.yaml tokens: dev_token: login: yonatangross scopes: [repo, workflow, admin:org] ci_token: login: ci-bot scopes: [repo] github: users: - login: yonatangross name: Yonatan Gross - login: ci-bot name: CI Bot repos: - owner: yonatangross name: my-project private: false default_branch: main topics: [typescript, testing] vercel: users: - username: yonatangross email: yonaigross@gmail.com projects: - name: my-docs framework: next # NEW in 0.4.x — drop-in seed blocks okta: users: - login: alice@example.com firstName: Alice lastName: Smith groups: [{ name: Everyone }, { name: Admins }] apps: [{ name: My Web App }] authorization_servers: - name: default audiences: ["api://default"] resend: domains: [{ name: example.com }] api_keys: [{ name: default }] # In tests: GET http://localhost:4009/inbox to assert captured emails stripe: customers: - name: Test Customer email: customer@example.com products: [{ name: Pro Plan }, { name: Starter Plan }] prices: - { product: Pro Plan, unit_amount: 4900, currency: usd, recurring: { interval: month } } - { product: Starter Plan, unit_amount: 1900, currency: usd, recurring: { interval: month } } # Webhook delivery fires on checkout.session.completed / expired mongoatlas: projects: [{ name: my-project }] clusters: [{ project: my-project, name: my-cluster }] database_users: [{ project: my-project, username: app-user }] ``` See `rules/seed-config.md` for full schema and best practices. ## Programmatic SDK > Service packages live under the `@emulators/*` scope (e.g., `@emulators/github`, `@emulators/stripe`). The programmatic API (`createEmulator`) is exported from the top-level `emulate` package. ```typescript import { createEmulator } from 'emulate' const github = await createEmulator({ service: 'github', port: 4001 }) // github.url -> 'http://localhost:4001' // State is real — create a PR and it appears in the list const res = await fetch(`${github.url}/repos/org/repo/pulls`, { method: 'POST', headers: { Authorization: 'Bearer dev_token' }, body: JSON.stringify({ title: 'Test PR', head: 'feature', base: 'main' }) }) const prs = await fetch(`${github.url}/repos/org/repo/pulls`) // -> includes the PR we just created // Auto-generated credentials (0.10.0+): readonly GeneratedSecret[], each // { service, kind, id, label, value }. A GitHub App emulator, for example, // generates its own RSA key rather than making you supply one. github.generatedSecrets // Cleanup github.reset() // Synchronous state wipe await github.close() // Shut down server ``` `seed` here is a parsed object, not a path. Only the CLI `--seed` flag takes a filename. For multi-service setup, lifecycle hooks, and the Vitest/Jest wiring, see `references/upstream.md`. For the ork-side corrections to that API, see `references/ork-delta.md`. ## Webhook Delivery Emulate delivers real webhooks with HMAC-SHA256 signatures when state changes. The signature FORMAT is per-provider, so one generic verifier does not cover every service. GitHub-format headers remain the default; Stripe has used its own format since 0.10.0. ```typescript import crypto from 'crypto' // GitHub format (the default for most services): sha256=<hmac over the raw body> function verifyWebhook(payload: string, signature: string, secret: string): boolean { const expected = 'sha256=' + crypto .createHmac('sha256', secret) .update(payload) .digest('hex') return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected)) } // Stripe format, as of emulate 0.10.0: Stripe-Signature: t=<timestamp>,v1=<hmac>, // where the HMAC covers `<timestamp>.<raw body>`, NOT the body alone. Verifying a // Stripe delivery with the GitHub helper above fails on both counts. function verifyStripeWebhook(rawBody: string, header: string, secret: string): boolean {