Przejdź do treści
Biblioteka skilli
Programowanie · Testowanie

emulate-seed

/emulate-seed

Generuje konfiguracje seed dla narzędzia emulate Vercela, które stanowo emuluje API (GitHub, Slack, Stripe, AWS, Okta i inne) w testach integracyjnych, CI i pracy offline.

Repozytorium
orchestkit ↗
Licencja
MIT
Ostatnia zmiana repozytorium
26.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
18
Skrypty
1
Komentarze HTML
0
Adresy URL w SKILL.md
11
Przestarzałość

Brak sygnałów. Repozytorium zmienione 26.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 1 skrypt w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: scripts/auto-discover.sh

Co robi i kiedy

Generuje konfiguracje seed dla narzędzia emulate Vercela, które stanowo emuluje API (GitHub, Slack, Stripe, AWS, Okta i inne) w testach integracyjnych, CI i pracy offline.

Oryginalny opis (EN)

Generate emulate seed configs for stateful API emulation. Wraps Vercel's emulate tool for GitHub, Vercel, Google OAuth, Slack, Apple Auth, Microsoft Entra, AWS, Okta, Clerk, Resend, Stripe, and MongoDB Atlas APIs — full state machines, not mocks. Use when setting up test environments, CI pipelines, integration tests, or offline development.

Jak działa

  1. New in 2026-04 (emulate 0.4.x)
  2. Auto-Discovery (M125 4)
  3. Quick Reference
  4. Quick Start
  5. Services (0.10.0 — 14 emulators)
  6. Seed Config Structure
  7. Programmatic SDK
  8. Webhook Delivery
  9. CI Integration
  10. Decision Matrix
Sekcje z nagłówków SKILL.md, w oryginale · 359 linii, 2 253 słów
Podgląd SKILL.md
---
name: emulate-seed
compatibility: "Claude Code 2.1.277+"
description: "Generate emulate seed configs for stateful API emulation. Wraps Vercel's emulate tool for GitHub, Vercel, Google OAuth, Slack, Apple Auth, Microsoft Entra, AWS, Okta, Clerk, Resend, Stripe, and MongoDB Atlas APIs — full state machines, not mocks. Use when setting up test environments, CI pipelines, integration tests, or offline development."
user-invocable: false
disable-model-invocation: false
context: inherit
metadata:
  category: testing
  upstream-package: emulate
  upstream-version-tested: "0.12.0"
  version: "1.3.0"
  author: "OrchestKit"
  complexity: "medium"
  tags: "emulate, testing, api-emulation, github, vercel, google, stripe, resend, okta, clerk, mongodb, seed, ci, stateful-testing"
---

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 {
  const parts = Object.fromEntries(header.split(',').map((kv) => kv.split('=')))
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex')
  return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
}
```

See `rules/webhook-setup.md` for webhook receiver patterns.

## CI Integration

```yaml
# .github/workflows/test.yml
jobs:
  test:
    steps:
      - uses: actions/checkout@v4
      - name: Start emulate
        run: npx emulate --service github --seed .emulate/ci.yaml &
      - name: Wait for emulate
        run: sleep 2
      - name: Run tests
        run: npm test
        env:
          GITHUB_API_BASE: http://localhost:4001
          VERCEL_API_BASE: http://localhost:4000
```

### Parallel Test Execution

Each test worker gets its own port to avoid race conditions:

```typescript
// vitest.config.ts
const workerPort = 4001 + parseInt(process.env.VITEST_WORKER_ID || '0')
```

See `rules/parallel-ci.md` for full parallel isolation patterns.

## Decision Matrix

| Tool | When to Use | Stateful? | Platforms |
|------|------------|-----------|-----------|
| **emulate** (FIRST CHOICE) | GitHub/Vercel/Google/Slack/Apple/Entra/AWS/Okta/Resend/Stripe/MongoDB/Clerk/Linear testing | YES | All 13 services |
| Pact | Contract verification between services | No | Any |
| MSW | In-browser/Node HTTP mocking | No | Any |
| Nock | Node.js HTTP intercept | No | Any |
| WireMock | HTTP stub server | Partial | Any |

**Use emulate when:**
- Testing code that calls GitHub, Vercel, Google, Slack, Apple, Entra, AWS, Okta, Resend, Stripe, MongoDB Atlas, Clerk, or Linear
- You need state persistence across multiple API calls in a test
- You want webhook delivery with real HMAC signatures (GitHub, Stripe)
- You need cascading side-effects (delete repo -> PRs cascade-delete)
- You need to assert on sent emails without hitting a real provider (Resend local `/inbox`)
- You need hosted Stripe checkout sessions with real redirect flow in tests

**Use MSW/Nock when:**
- Mocking arbitrary HTTP APIs not covered by emulate
- You need in-browser interception (MSW)
- Tests only need single request/response pairs

## Upstream coverage (do not restate)

This skill is a wrap plus our delta. emulate ships its own per-service reference docs;
copying them here only produces something that goes stale on the next release. If a
topic below comes up, read the first-party source, not a paraphrase.

| Topic | First-party source |
|---|---|
| Programmatic API (`createEmulator`, `url`, `reset()`, `close()`), Vitest/Jest wiring, config auto-detection order, token fallback | `references/upstream.md` (synced from `vercel-labs/emulate`, `skills/emulate/SKILL.md`) |
| GitHub endpoint recipes, GitHub App JWT seeding, Octokit and Auth.js base-URL wiring, GitHub OAuth flow | https://github.com/vercel-labs/emulate/blob/main/skills/github/SKILL.md |
| Google OIDC discovery, JWKS, authorize/token/userinfo/revoke, PKCE, `google-auth-library`, Passport, `openid-client` | https://github.com/vercel-labs/emulate/blob/main/skills/google/SKILL.md |
| Vercel endpoint recipes, cursor pagination, team scoping, integration OAuth flow | https://github.com/vercel-labs/emulate/blob/main/skills/vercel/SKILL.md |
| Every other emulator (Slack, Apple, Entra, AWS, Okta, Resend, Stripe, MongoDB Atlas, Clerk, Linear, Twilio) | https://github.com/vercel-labs/emulate/tree/main/skills |

**What stays ours:** `references/ork-delta.md` (the corrections and house conventions that
are not in any vendor doc), `references/cli-reference.md`, `references/api-coverage.md`,
`references/dep-to-emulator-map.json`, `scripts/auto-discover.sh`, and everything in `rules/`.

Read `references/ork-delta.md` before copying any snippet out of a vendor doc. It records
the two API facts vendor prose does not spell out (the exported factory is `createEmulator`,
and `seed` in the programmatic options is an object rather than a path) plus the
`*_API_BASE` env-var convention this repo uses instead of the vendor's `*_EMULATOR_URL`.

## Related Skills

- `testing-integration` — Integration test patterns (emulate as first choice for API tests)
- `testing-e2e` — End-to-end test patterns with emulated backends
- `testing-unit` — Unit test patterns (use emulate for API-dependent units)
- `security-patterns` — Auth token patterns (emulate token seeding)

## CLI Reference

See `references/cli-reference.md` for all CLI flags and commands.
Pliki w paczce (18)
  • SKILL.md 18 KB
  • test-cases.json 3 KB
  • references/api-coverage.md 5 KB
  • references/cli-reference.md 2 KB
  • references/dep-to-emulator-map.json 2 KB
  • references/ork-delta.md 3 KB
  • references/upstream-github.md 18 KB
  • references/upstream-google.md 19 KB
  • references/upstream-vercel.md 15 KB
  • references/upstream.md 12 KB
  • rules/_sections.md 1 KB
  • rules/_template.md 1 KB
  • rules/auth-tokens.md 3 KB
  • rules/parallel-ci.md 3 KB
  • rules/seed-config.md 2 KB
  • rules/service-selection.md 3 KB
  • rules/webhook-setup.md 3 KB
  • scripts/auto-discover.sh 4 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · yonatangross/orchestkit100MIT
yonatangross/orchestkit100MIT

Identyczna treść występuje jeszcze w 1 innych folderach na GitHubie. Tu pokazujemy jedną, najlepiej ocenioną kopię.

Migawka bazy z 13.11.2026 · wersja paczki 0ec5c3094121 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 95emulate
    Uruchamia lokalne emulatory API, takich jak Vercel, GitHub, Google, Slack czy AWS, z danymi startowymi do testów bez sieci.
  • 95emulate
    Uruchamia lokalne emulatory API usług takich jak Vercel, GitHub, Google, Slack, Apple, Microsoft, AWS, Clerk, Linear i Twilio, z danymi startowymi, testami lokalnymi i CI bez dostępu do sieci.
  • 95vercel
    Emuluje lokalnie REST API Vercel do testów integracji: projekty, wdrożenia, domeny, OAuth, zmienne środowiskowe, klucze API i Vercel Blob, bez wywołań prawdziwego API.
  • 100cursor-sso-integration
    Konfiguruje logowanie jednokrotne SAML 2.0 i OIDC w Cursor z Okta, Microsoft Entra ID i Google Workspace.
  • 90slack-agent
    Buduje agentów i boty Slack w frameworku eve od Vercela: definiuje narzędzia, łączy się przez Vercel Connect, konfiguruje kanał Slack i testuje.
  • 100local-vercel-connect-d6247856
    Pomaga bezpiecznie uzyskać tokeny OAuth dla usług zewnętrznych, takich jak Slack, GitHub czy serwery MCP, przez Vercel OIDC.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.