emulate 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,416 @@
+# emulate
+
+Local drop-in replacement services for CI and no-network sandboxes. Fully stateful, production-fidelity API emulation. Not mocks.
+
+## Quick Start
+
+```bash
+npx emulate
+```
+
+All services start with sensible defaults. No config file needed:
+
+- **Vercel** on `http://localhost:4000`
+- **GitHub** on `http://localhost:4001`
+- **Google** on `http://localhost:4002`
+
+## CLI
+
+```bash
+# Start all services (zero-config)
+emulate
+
+# Start specific services
+emulate --service vercel,github
+
+# Custom port
+emulate --port 3000
+
+# Use a seed config file
+emulate --seed config.yaml
+
+# Generate a starter config
+emulate init
+
+# Generate config for a specific service
+emulate init --service vercel
+
+# List available services
+emulate list
+```
+
+### Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `-p, --port` | `4000` | Base port (auto-increments per service) |
+| `-s, --service` | all | Comma-separated services to enable |
+| `--seed` | auto-detect | Path to seed config (YAML or JSON) |
+
+The port can also be set via `EMULATE_PORT` or `PORT` environment variables.
+
+## Programmatic API
+
+```bash
+npm install emulate
+```
+
+Each call to `createEmulator` starts a single service:
+
+```typescript
+import { createEmulator } from 'emulate'
+
+const github = await createEmulator({ service: 'github', port: 4001 })
+const vercel = await createEmulator({ service: 'vercel', port: 4002 })
+
+github.url   // 'http://localhost:4001'
+vercel.url   // 'http://localhost:4002'
+
+await github.close()
+await vercel.close()
+```
+
+### Vitest / Jest setup
+
+```typescript
+// vitest.setup.ts
+import { createEmulator, type Emulator } from 'emulate'
+
+let github: Emulator
+let vercel: Emulator
+
+beforeAll(async () => {
+  ;[github, vercel] = await Promise.all([
+    createEmulator({ service: 'github', port: 4001 }),
+    createEmulator({ service: 'vercel', port: 4002 }),
+  ])
+  process.env.GITHUB_URL = github.url
+  process.env.VERCEL_URL = vercel.url
+})
+
+afterEach(() => { github.reset(); vercel.reset() })
+afterAll(() => Promise.all([github.close(), vercel.close()]))
+```
+
+### Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `service` | *(required)* | Service to emulate: `'github'`, `'vercel'`, or `'google'` |
+| `port` | `4000` | Port for the HTTP server |
+| `seed` | none | Inline seed data (same shape as YAML config) |
+
+### Instance methods
+
+| Method | Description |
+|--------|-------------|
+| `url` | Base URL of the running server |
+| `reset()` | Wipe the store and replay seed data |
+| `close()` | Shut down the HTTP server, returns a Promise |
+
+## Configuration
+
+Configuration is optional. To customize seed data, create `emulate.config.yaml` in your project root (or pass `--seed`):
+
+```yaml
+tokens:
+  my_token:
+    login: admin
+    scopes: [repo, user]
+
+vercel:
+  users:
+    - username: developer
+      name: Developer
+      email: dev@example.com
+  teams:
+    - slug: my-team
+      name: My Team
+  projects:
+    - name: my-app
+      team: my-team
+      framework: nextjs
+
+github:
+  users:
+    - login: octocat
+      name: The Octocat
+      email: octocat@github.com
+  orgs:
+    - login: my-org
+      name: My Organization
+  repos:
+    - owner: octocat
+      name: hello-world
+      language: JavaScript
+      auto_init: true
+
+google:
+  users:
+    - email: testuser@example.com
+      name: Test User
+  oauth_clients:
+    - client_id: my-client-id.apps.googleusercontent.com
+      client_secret: GOCSPX-secret
+      redirect_uris:
+        - http://localhost:3000/api/auth/callback/google
+```
+
+## OAuth & Integrations
+
+The emulator supports configurable OAuth apps and integrations with strict client validation.
+
+### Vercel Integrations
+
+```yaml
+vercel:
+  integrations:
+    - client_id: "oac_abc123"
+      client_secret: "secret_abc123"
+      name: "My Vercel App"
+      redirect_uris:
+        - "http://localhost:3000/api/auth/callback/vercel"
+```
+
+### GitHub OAuth Apps
+
+```yaml
+github:
+  oauth_apps:
+    - client_id: "Iv1.abc123"
+      client_secret: "secret_abc123"
+      name: "My Web App"
+      redirect_uris:
+        - "http://localhost:3000/api/auth/callback/github"
+```
+
+If no `oauth_apps` are configured, the emulator accepts any `client_id` (backward-compatible). With apps configured, strict validation is enforced.
+
+### GitHub Apps
+
+Full GitHub App support with JWT authentication and installation access tokens:
+
+```yaml
+github:
+  apps:
+    - app_id: 12345
+      slug: "my-github-app"
+      name: "My GitHub App"
+      private_key: |
+        -----BEGIN RSA PRIVATE KEY-----
+        ...your PEM key...
+        -----END RSA PRIVATE KEY-----
+      permissions:
+        contents: read
+        issues: write
+      events: [push, pull_request]
+      installations:
+        - installation_id: 100
+          account: my-org
+          repository_selection: all
+```
+
+JWT authentication: sign a JWT with `{ iss: "<app_id>" }` using the app's private key (RS256). The emulator verifies the signature and resolves the app.
+
+## Vercel API
+
+Every endpoint below is fully stateful with Vercel-style JSON responses and cursor-based pagination.
+
+### User & Teams
+- `GET /v2/user` - authenticated user
+- `PATCH /v2/user` - update user
+- `GET /v2/teams` - list teams (cursor paginated)
+- `GET /v2/teams/:teamId` - get team (by ID or slug)
+- `POST /v2/teams` - create team
+- `PATCH /v2/teams/:teamId` - update team
+- `GET /v2/teams/:teamId/members` - list members
+- `POST /v2/teams/:teamId/members` - add member
+
+### Projects
+- `POST /v11/projects` - create project (with optional env vars and git integration)
+- `GET /v10/projects` - list projects (search, cursor pagination)
+- `GET /v9/projects/:idOrName` - get project (includes env vars)
+- `PATCH /v9/projects/:idOrName` - update project
+- `DELETE /v9/projects/:idOrName` - delete project (cascades)
+- `GET /v1/projects/:projectId/promote/aliases` - promote aliases status
+- `PATCH /v1/projects/:idOrName/protection-bypass` - manage bypass secrets
+
+### Deployments
+- `POST /v13/deployments` - create deployment (auto-transitions to READY)
+- `GET /v13/deployments/:idOrUrl` - get deployment (by ID or URL)
+- `GET /v6/deployments` - list deployments (filter by project, target, state)
+- `DELETE /v13/deployments/:id` - delete deployment (cascades)
+- `PATCH /v12/deployments/:id/cancel` - cancel building deployment
+- `GET /v2/deployments/:id/aliases` - list deployment aliases
+- `GET /v3/deployments/:idOrUrl/events` - get build events/logs
+- `GET /v6/deployments/:id/files` - list deployment files
+- `POST /v2/files` - upload file (by SHA digest)
+
+### Domains
+- `POST /v10/projects/:idOrName/domains` - add domain (with verification challenge)
+- `GET /v9/projects/:idOrName/domains` - list domains
+- `GET /v9/projects/:idOrName/domains/:domain` - get domain
+- `PATCH /v9/projects/:idOrName/domains/:domain` - update domain
+- `DELETE /v9/projects/:idOrName/domains/:domain` - remove domain
+- `POST /v9/projects/:idOrName/domains/:domain/verify` - verify domain
+
+### Environment Variables
+- `GET /v10/projects/:idOrName/env` - list env vars (with decrypt option)
+- `POST /v10/projects/:idOrName/env` - create env vars (single, batch, upsert)
+- `GET /v10/projects/:idOrName/env/:id` - get env var
+- `PATCH /v9/projects/:idOrName/env/:id` - update env var
+- `DELETE /v9/projects/:idOrName/env/:id` - delete env var
+
+## GitHub API
+
+Every endpoint below is fully stateful. Creates, updates, and deletes persist in memory and affect related entities.
+
+### Users
+- `GET /user` - authenticated user
+- `PATCH /user` - update profile
+- `GET /users/:username` - get user
+- `GET /users` - list users
+- `GET /users/:username/repos` - list user repos
+- `GET /users/:username/orgs` - list user orgs
+- `GET /users/:username/followers` - list followers
+- `GET /users/:username/following` - list following
+
+### Repositories
+- `GET /repos/:owner/:repo` - get repo
+- `POST /user/repos` - create user repo
+- `POST /orgs/:org/repos` - create org repo
+- `PATCH /repos/:owner/:repo` - update repo
+- `DELETE /repos/:owner/:repo` - delete repo (cascades)
+- `GET/PUT /repos/:owner/:repo/topics` - get/replace topics
+- `GET /repos/:owner/:repo/languages` - languages
+- `GET /repos/:owner/:repo/contributors` - contributors
+- `GET /repos/:owner/:repo/forks` - list forks
+- `POST /repos/:owner/:repo/forks` - create fork
+- `GET/PUT/DELETE /repos/:owner/:repo/collaborators/:username` - collaborators
+- `GET /repos/:owner/:repo/collaborators/:username/permission`
+- `POST /repos/:owner/:repo/transfer` - transfer repo
+- `GET /repos/:owner/:repo/tags` - list tags
+
+### Issues
+- `GET /repos/:owner/:repo/issues` - list (filter by state, labels, assignee, milestone, creator, since)
+- `POST /repos/:owner/:repo/issues` - create
+- `GET /repos/:owner/:repo/issues/:number` - get
+- `PATCH /repos/:owner/:repo/issues/:number` - update (state transitions, events)
+- `PUT/DELETE /repos/:owner/:repo/issues/:number/lock` - lock/unlock
+- `GET /repos/:owner/:repo/issues/:number/timeline` - timeline events
+- `GET /repos/:owner/:repo/issues/:number/events` - events
+- `POST/DELETE /repos/:owner/:repo/issues/:number/assignees` - manage assignees
+
+### Pull Requests
+- `GET /repos/:owner/:repo/pulls` - list (filter by state, head, base)
+- `POST /repos/:owner/:repo/pulls` - create
+- `GET /repos/:owner/:repo/pulls/:number` - get
+- `PATCH /repos/:owner/:repo/pulls/:number` - update
+- `PUT /repos/:owner/:repo/pulls/:number/merge` - merge (with branch protection enforcement)
+- `GET /repos/:owner/:repo/pulls/:number/commits` - list commits
+- `GET /repos/:owner/:repo/pulls/:number/files` - list files
+- `POST/DELETE /repos/:owner/:repo/pulls/:number/requested_reviewers` - manage reviewers
+- `PUT /repos/:owner/:repo/pulls/:number/update-branch` - update branch
+
+### Comments
+- Issue comments: full CRUD on `/repos/:owner/:repo/issues/:number/comments`
+- Review comments: full CRUD on `/repos/:owner/:repo/pulls/:number/comments`
+- Commit comments: full CRUD on `/repos/:owner/:repo/commits/:sha/comments`
+- Repo-wide listings for each type
+
+### Reviews
+- `GET /repos/:owner/:repo/pulls/:number/reviews` - list
+- `POST /repos/:owner/:repo/pulls/:number/reviews` - create (with inline comments)
+- `GET/PUT /repos/:owner/:repo/pulls/:number/reviews/:id` - get/update
+- `POST /repos/:owner/:repo/pulls/:number/reviews/:id/events` - submit
+- `PUT /repos/:owner/:repo/pulls/:number/reviews/:id/dismissals` - dismiss
+
+### Labels & Milestones
+- Labels: full CRUD, add/remove from issues, replace all
+- Milestones: full CRUD, state transitions, issue counts
+
+### Branches & Git Data
+- Branches: list, get, protection CRUD (status checks, PR reviews, enforce admins)
+- Refs: get, match, create, update, delete
+- Commits: get, create
+- Trees: get (with recursive), create (with inline content)
+- Blobs: get, create
+- Tags: get, create
+
+### Organizations & Teams
+- Orgs: get, update, list
+- Org members: list, check, remove, get/set membership
+- Teams: full CRUD, members, repos
+
+### Releases
+- Releases: full CRUD, latest, by tag
+- Release assets: full CRUD, upload
+- Generate release notes
+
+### Webhooks
+- Repo webhooks: full CRUD, ping, test, deliveries
+- Org webhooks: full CRUD, ping
+- Real HTTP delivery to registered URLs on all state changes
+
+### Search
+- `GET /search/repositories` - full query syntax (user, org, language, topic, stars, forks, etc.)
+- `GET /search/issues` - issues + PRs (repo, is, author, label, milestone, state, etc.)
+- `GET /search/users` - users + orgs
+- `GET /search/code` - blob content search
+- `GET /search/commits` - commit message search
+- `GET /search/topics` - topic search
+- `GET /search/labels` - label search
+
+### Actions
+- Workflows: list, get, enable/disable, dispatch
+- Workflow runs: list, get, cancel, rerun, delete, logs
+- Jobs: list, get, logs
+- Artifacts: list, get, delete
+- Secrets: repo + org CRUD
+
+### Checks
+- Check runs: create, update, get, annotations, rerequest, list by ref/suite
+- Check suites: create, get, preferences, rerequest, list by ref
+- Automatic suite status rollup from check run results
+
+### Misc
+- `GET /rate_limit` - rate limit status
+- `GET /meta` - server metadata
+- `GET /octocat` - ASCII art
+- `GET /emojis` - emoji URLs
+- `GET /zen` - random zen phrase
+- `GET /versions` - API versions
+
+## Google API
+
+OAuth 2.0 and OpenID Connect emulation.
+
+- `GET /o/oauth2/v2/auth` - authorization endpoint
+- `POST /oauth2/v4/token` - token exchange
+- `GET /oauth2/v2/userinfo` - get user info
+- `GET /.well-known/openid-configuration` - OIDC discovery document
+- `GET /oauth2/v3/certs` - JSON Web Key Set (JWKS)
+
+## Architecture
+
+```
+packages/
+  emulate/          # CLI entry point (commander)
+    @internal/
+    core/           # HTTP server, in-memory store, plugin interface, middleware
+    vercel/         # Vercel API service
+    github/         # GitHub API service
+    google/         # Google OAuth 2.0 / OIDC
+apps/
+  web/              # Documentation site (Next.js)
+```
+
+The core provides a generic `Store` with typed `Collection<T>` instances supporting CRUD, indexing, filtering, and pagination. Each service plugin registers its routes on the shared Hono app and uses the store for state.
+
+## Auth
+
+Tokens are configured in the seed config and map to users. Pass them as `Authorization: Bearer <token>` or `Authorization: token <token>`.
+
+**Vercel**: All endpoints accept `teamId` or `slug` query params for team scoping. Pagination uses cursor-based `limit`/`since`/`until` with `pagination` response objects.
+
+**GitHub**: Public repo endpoints work without auth. Private repos and write operations require a valid token. Pagination uses `page`/`per_page` with `Link` headers.

package/dist/api.d.ts

@@ -0,0 +1,33 @@
+import * as _internal_core from '@internal/core';
+import { VercelSeedConfig } from '@internal/vercel';
+import { GitHubSeedConfig } from '@internal/github';
+import { GoogleSeedConfig } from '@internal/google';
+
+declare const SERVICE_PLUGINS: {
+    readonly vercel: _internal_core.ServicePlugin;
+    readonly github: _internal_core.ServicePlugin;
+    readonly google: _internal_core.ServicePlugin;
+};
+type ServiceName = keyof typeof SERVICE_PLUGINS;
+interface SeedConfig {
+    tokens?: Record<string, {
+        login: string;
+        scopes?: string[];
+    }>;
+    vercel?: VercelSeedConfig;
+    github?: GitHubSeedConfig;
+    google?: GoogleSeedConfig;
+}
+interface EmulatorOptions {
+    service: ServiceName;
+    port?: number;
+    seed?: SeedConfig;
+}
+interface Emulator {
+    url: string;
+    reset(): void;
+    close(): Promise<void>;
+}
+declare function createEmulator(options: EmulatorOptions): Promise<Emulator>;
+
+export { type Emulator, type EmulatorOptions, type SeedConfig, type ServiceName, createEmulator };