emulate 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,357 @@
+# 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.
+
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "emulate",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local drop-in replacement services for CI and no-network sandboxes",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,15 +35,15 @@
     "@hono/node-server": "^1",
     "commander": "^14",
     "picocolors": "^1.1.1",
-    "yaml": "^2",
-    "@internal/github": "0.1.0",
-    "@internal/google": "0.1.0",
-    "@internal/core": "0.1.0",
-    "@internal/vercel": "0.1.0"
+    "yaml": "^2"
   },
   "devDependencies": {
     "tsup": "^8",
-    "typescript": "^5.7"
+    "typescript": "^5.7",
+    "@internal/google": "0.1.0",
+    "@internal/github": "0.1.0",
+    "@internal/vercel": "0.1.0",
+    "@internal/core": "0.1.0"
   },
   "scripts": {
     "build": "tsup",