emulate-seed

上流バージョンの参照：emulate 0.12.0（2026-09-30）。

Emulate Seed Configs

emulate（Apache-2.0）用のシード設定を生成、管理します。これは Vercel Labs のステートフルな API エミュレーションツールです。各カテゴリの個別のルールファイルは rules/ にあり、必要に応じて読み込まれます。

対応するエージェント： このスキルは emulate-engineer サブエージェント（subagent_type: "ork:emulate-engineer"）と連携します。タスクに emulate 設定の一からの生成、Webhook の HMAC 設定、CI パイプラインへの統合、並列ワーカーのポート分離が含まれる場合は、インラインで対応するのではなく、このエージェントを起動してください。13 個のエミュレーターのサービスポート一覧とシードルールをすべて把握しています。

モックではありません。 Emulate は、連鎖削除、カーソルページネーション、Webhook 配信、HMAC 署名検証を備えた完全なステートマシンを提供します。API 経由で PR を作成すると、GET /repos/:owner/:repo/pulls に表示されます。リポジトリを削除すると、関連する Issue、PR、Webhook も連鎖して削除されます。

2026-04 の新機能（emulate 0.4.x）

• モジュール化された @emulators/* パッケージ — 各サービスは独立したパッケージ（@emulators/github、@emulators/stripe など）です。トップレベルの emulate は createEmulator と CLI を再エクスポートします。
• 4 つの新サービス（合計 12 個）：mongoatlas:4007、okta:4008、resend:4009、stripe:4010。すぐに使えるシード YAML ブロックを利用できます。
• Resend ローカル受信トレイ — GET http://localhost:4009/inbox は、実際のプロバイダーにアクセスせず、アサーション用に取得済みのメールを返します。
• Stripe のホスト型チェックアウト — 実際のセッションリダイレクトフローと checkout.session.completed／expired の Webhook 配信を提供し、E2E 決済テストに適しています。
• MongoDB Atlas — Admin API v2（プロジェクト／クラスター／DB ユーザー）と、完全な CRUD および aggregate を備えた Data API v1 を提供します。
• Okta OIDC — 完全な discovery、JWKS、authorize/token/userinfo/revoke/introspect に加え、Users／Groups／Apps の CRUD を提供します。
• Entra／Apple／Slack の拡張（v0.4.0） — PKCE とリフレッシュローテーション（Entra）、RS256 JWKS（Apple）、OAuth v2 の同意 UI（Slack）。
• @emulators/adapter-next — キャッチオールの Next.js ルートハンドラーにより、アプリと同じオリジンでエミュレーターを実行できます。Vercel のプレビューデプロイで OAuth コールバック URL がずれる問題を修正します。

自動検出（M125 #4）

scripts/auto-discover.sh はプロジェクトの package.json をスキャンし、依存関係を references/dep-to-emulator-map.json と照合して、一致する項目を報告するか、emulate.config.yaml に書き込みます。動作モードは 3 つです。

モード	動作
（デフォルト）	一致した依存関係とエミュレーターの統合結果を stderr に報告します。書き込みは行いません。
--json	人間向けのレポートの代わりに、機械可読な JSON を出力します。
--apply	emulate.config.yaml に書き込みます（--force がない場合、上書きは拒否されます）。

$ 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)

複数のエミュレーターに対応する依存関係は、合理的なプロバイダーをすべて選ぶ設定がデフォルトです。その後、ユーザーが YAML から不要なものを削除します。対応表にない依存関係は通知なしでスキップされます。対応範囲の拡張はコード変更ではなく、ドキュメントへの PR（references/dep-to-emulator-map.json の編集）で行います。

dev は起動時に生成された emulate.config.yaml を読み込みます。src/skills/dev/scripts/boot.sh を参照してください。

クイックリファレンス

カテゴリ	ルール	影響度	使用する場面
シード設定	1	高	テスト環境向けに emulate.config.yaml を設定するとき
サービスの選択	1	中	テストで GitHub／Vercel／Google のどれを使うか選ぶとき
Webhook の設定	1	中	HMAC 検証を伴う Webhook 配信をテストするとき
並列 CI	1	高	ポートの衝突を避けてテストを並列実行するとき
認証トークン	1	中	エミュレートされたユーザーに紐付くトークンをシードするとき

合計：5 カテゴリにわたる 5 つのルール

クイックスタート

# 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

サービス（0.10.0 — 14 エミュレーター）

リリースを通じた新機能：

• 0.5.0 — Clerk、MongoDB Atlas、Stripe、Resend、Okta のエミュレーターを追加。ポートレス統合（専用ポートを必要としない組み込みエミュレーター）、Google OAuth の hd クレーム対応、Stripe Checkout と Resend のマジックリンクのサンプルを追加。AWS S3 エミュレーターが公式 SDK のワイヤーフォーマットに一致するようになりました。
• 0.6.0 — Slack を拡張（OAuth v2 の同意画面、会話／リアクション）。
• 0.6.1 — Vercel Blob ストア。
• 0.7.0 — Linear（13 番目のプロバイダー）を追加：状態を保持する組織／チーム／課題／サイクルと Webhook。
• 0.8.0 — Twilio（14 番目のプロバイダー）を追加：アカウント、電話番号、メッセージ、通話、会話、メッセージングサービス、Verify フロー、シミュレーターエンドポイントと、Next.js の SMS 認証サンプル。
• 0.9.0 — Nuxt エミュレーターアダプターを追加（Next.js アダプターと並行して利用可能）。プロバイダー数に変更はありません。
• 0.10.0 — 状態を保持する GitHub リポジトリのコンテンツとコミット履歴（GET /repos/:owner/:repo/readme、書き込み時に実際のコミットが作成される GET／PUT／DELETE /repos/:owner/:repo/contents/:path、GET /repos/:owner/:repo/commits、数値 ID による GET /repositories/:id）。Emulator オブジェクトに読み取り専用の generatedSecrets 配列を追加し、新たに GeneratedSecret 型をエクスポート。GitHub App の JWT 検証で PKCS#1 に加えて PKCS#8 キーも受け入れるようになりました。プロバイダー数に変更はありません。

すべて後方互換性がありますが、知っておくべき動作変更が 1 つあります。0.10.0 では、Stripe の Webhook 配信が Stripe 独自の Stripe-Signature ヘッダー形式に切り替わりました。上流では破壊的変更ではなくバグ修正として扱われていますが、Stripe の配信で以前の GitHub 形式の sha256= ヘッダーを検証するテストは失敗するようになります。両方の形式については、以下の「Webhook 配信」を参照してください。

サービス	デフォルトポート	対応範囲
Vercel	:4000	プロジェクト、デプロイ、ドメイン、環境変数、チーム
GitHub	:4001	リポジトリ、PR、課題、コメント、レビュー、Actions、Webhook、組織、チーム
Google OAuth	:4002	OAuth 2.0 の認可、トークン交換、ユーザー情報
Slack	:4003	チャット、会話、ユーザー、リアクション、同意画面付き OAuth v2
Apple Auth	:4004	Apple でサインイン — OIDC ディスカバリー、JWKS（RS256）、認証フロー、トークン交換
Microsoft Entra	:4005	OAuth 2.0/OIDC v2.0、認可コード + PKCE、リフレッシュトークンのローテーション、v1 トークンエンドポイント、Graph /users/{id}
AWS	:4006	S3 バケット、SQS キュー、IAM ユーザー／ロール、STS アイデンティティ
MongoDB Atlas (0.4+)	:4007	Admin API v2（プロジェクト、クラスター、DB ユーザー）+ Data API v1（完全な CRUD + 集計）
Okta (0.4+)	:4008	OIDC ディスカバリー、JWKS、認可／トークン／ユーザー情報／失効／イントロスペクション、Users/Groups/Apps の CRUD
Resend (0.4+)	:4009	送信 + 一括送信（1 リクエストあたり 100 件）、一覧／取得／キャンセル、ドメイン、API キー、オーディエンス、連絡先、ローカル受信トレイ（GET /inbox）
Stripe (0.4+)	:4010	顧客、支払い方法、顧客セッション、支払いインテント、請求、商品、価格、Webhook 配信付きのホスト型チェックアウトセッション
Clerk (0.5+)	（オンデマンド）	ユーザー、セッション、組織
Linear (0.7+)	（オンデマンド）	組織、チーム、課題、サイクル、Webhook
Twilio (0.8+)	（オンデマンド）	アカウント、電話番号、メッセージ、通話、会話、メッセージングサービス、Verify フロー、シミュレーターエンドポイント

エンドポイントの一覧は references/api-coverage.md を参照してください。

Next.js アダプター（0.4+）— @emulators/adapter-next

キャッチオールのルートハンドラーを介して、エミュレーターを Next.js アプリと同じオリジンで実行します。Vercel のプレビュー環境へのデプロイで発生する OAuth コールバック URL のずれを解消し、http://localhost:4001 へのリダイレクト不一致をなくします。

// 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 */ },
})

シード設定の構造

シード設定では、エミュレーターにトークン、ユーザー、リポジトリ、プロジェクトを事前に登録し、テストを既知の状態から開始できるようにします。

# 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: [email protected]
  projects:
    - name: my-docs
      framework: next

# NEW in 0.4.x — drop-in seed blocks
okta:
  users:
    - login: [email protected]
      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: [email protected]
  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 }]

スキーマ全体とベストプラクティスについては、rules/seed-config.md を参照してください。

プログラムから利用する SDK

サービスパッケージは @emulators/* スコープ（例：@emulators/github、@emulators/stripe）にあります。プログラムから利用する API（createEmulator）は、トップレベルの emulate パッケージからエクスポートされます。

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 はパスではなく、解析済みのオブジェクトです。ファイル名を指定するのは、CLI の --seed フラグだけです。 複数サービスのセットアップ、ライフサイクルフック、Vitest／Jest の接続については、 references/upstream.md を参照してください。この API に対する ork 側の修正については、references/ork-delta.md を参照してください。

Webhook の配信

Emulate は、状態が変化したときに HMAC-SHA256 署名付きの実際の Webhook を配信します。 署名の形式はプロバイダーごとに異なるため、単一の汎用検証ツールですべてのサービスに対応することはできません。 GitHub 形式のヘッダーが引き続きデフォルトです。Stripe は 0.10.0 以降、独自の形式を使用しています。

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))
}

Webhook の受信パターンについては、rules/webhook-setup.md を参照してください。

CI との統合

# .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

テストの並列実行

競合状態を避けるため、各テストワーカーには個別のポートが割り当てられます。

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

並列実行時の分離パターンの詳細については、rules/parallel-ci.md を参照してください。

判断マトリックス

ツール	使用する場面	状態を保持するか	プラットフォーム
emulate（第一候補）	GitHub／Vercel／Google／Slack／Apple／Entra／AWS／Okta／Resend／Stripe／MongoDB／Clerk／Linear のテスト	はい	全 13 サービス
Pact	サービス間のコントラクト検証	いいえ	任意
MSW	ブラウザー内／Node の HTTP モック	いいえ	任意
Nock	Node.js の HTTP インターセプト	いいえ	任意
WireMock	HTTP スタブサーバー	一部	任意

次の場合は emulate を使用してください：

• GitHub、Vercel、Google、Slack、Apple、Entra、AWS、Okta、Resend、Stripe、MongoDB Atlas、Clerk、Linear を呼び出すコードをテストする場合
• テスト中に複数の API 呼び出しにまたがって状態を保持する必要がある場合
• 実際の HMAC 署名付き Webhook の配信が必要な場合（GitHub、Stripe）
• 連鎖する副作用が必要な場合（リポジトリの削除 → PR も連鎖して削除）
• 実際のプロバイダーに接続せず、送信メールを検証する必要がある場合（Resend のローカル /inbox）
• テストで実際のリダイレクトフローを伴う、ホスト型 Stripe チェックアウトセッションが必要な場合

次の場合は MSW／Nock を使用してください：

• emulate が対応していない任意の HTTP API をモックする場合
• ブラウザー内でのインターセプトが必要な場合（MSW）
• テストで単一のリクエスト／レスポンスの組み合わせだけが必要な場合

アップストリームのカバレッジ（再記載しないでください）

このスキルは、ラッパーと独自の差分で構成されています。emulate には、サービスごとのリファレンスドキュメントが用意されています。 これらをここにコピーしても、次のリリースで古くなるだけです。以下のトピックが出てきた場合は、 言い換えではなく、一次ソースを参照してください。

トピック	一次ソース
プログラム API（createEmulator、url、reset()、close()）、Vitest/Jest の連携、設定の自動検出順序、トークンのフォールバック	references/upstream.md（vercel-labs/emulate の skills/emulate/SKILL.md と同期）
GitHub エンドポイントのレシピ、GitHub App JWT のシーディング、Octokit および Auth.js のベース URL 設定、GitHub OAuth フロー	https://github.com/vercel-labs/emulate/blob/main/skills/github/SKILL.md
Google OIDC ディスカバリー、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 エンドポイントのレシピ、カーソルページネーション、チームスコープ設定、インテグレーションの OAuth フロー	https://github.com/vercel-labs/emulate/blob/main/skills/vercel/SKILL.md
その他すべてのエミュレーター（Slack、Apple、Entra、AWS、Okta、Resend、Stripe、MongoDB Atlas、Clerk、Linear、Twilio）	https://github.com/vercel-labs/emulate/tree/main/skills

独自に管理する内容： references/ork-delta.md（ベンダーのドキュメントにはない修正とプロジェクト独自の規約）、references/cli-reference.md、references/api-coverage.md、references/dep-to-emulator-map.json、scripts/auto-discover.sh、および rules/ 内のすべてのファイル。

ベンダーのドキュメントからスニペットをコピーする前に、references/ork-delta.md を読んでください。ここには、ベンダーの説明に記載されていない API に関する 2 つの事実（エクスポートされるファクトリーは createEmulator であること、およびプログラムオプションの seed はパスではなくオブジェクトであること）に加え、このリポジトリでベンダーの *_EMULATOR_URL ではなく使用する *_API_BASE 環境変数の規約が記載されています。

関連スキル

• testing-integration — インテグレーションテストのパターン（API テストでは emulate を第一候補として使用）
• testing-e2e — エミュレートされたバックエンドを使ったエンドツーエンドテストのパターン
• testing-unit — ユニットテストのパターン（API に依存するユニットでは emulate を使用）
• security-patterns — 認証トークンのパターン（emulate によるトークンのシーディング）

CLI リファレンス

すべての CLI フラグとコマンドについては、references/cli-reference.md を参照してください。