Add Linear emulator (#180)

* Add Linear emulator

- Add a stateful Linear service with GraphQL, OAuth, webhooks, inspector, and seed support.

- Register Linear in the CLI package and default service config.

- Document the supported surface and cover it with Linear SDK conformance tests.

* Reject Linear refresh tokens for API auth

* Fix Linear strict scope enforcement

* Fix Linear issue or filters

* Fix Linear emulator edge cases

* Fix Linear emulator edge cases

* Fix Linear seed override handling

* Fix Linear SDK compatibility

* Fix Linear issue mutation validation

* Fix Linear SDK mutation compatibility

* Fix Linear OAuth Basic auth parsing

* Fix Linear GraphQL validation edge cases

* Fix Linear docs site wiring

Author: ctate

README.md

@@ -16,7 +16,13 @@ All services start with sensible defaults. No config file needed:
 - **Slack** on `http://localhost:4003`
 - **Apple** on `http://localhost:4004`
 - **Microsoft** on `http://localhost:4005`
-- **AWS** on `http://localhost:4006`
+- **Okta** on `http://localhost:4006`
+- **AWS** on `http://localhost:4007`
+- **Resend** on `http://localhost:4008`
+- **Stripe** on `http://localhost:4009`
+- **MongoDB Atlas** on `http://localhost:4010`
+- **Clerk** on `http://localhost:4011`
+- **Linear** on `http://localhost:4012`
 
 ## CLI
 
@@ -141,7 +147,7 @@ afterAll(() => Promise.all([github.close(), vercel.close()]))
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `service` | *(required)* | Service name: `'vercel'`, `'github'`, `'google'`, `'slack'`, `'apple'`, `'microsoft'`, or `'aws'` |
+| `service` | *(required)* | Service name: `'vercel'`, `'github'`, `'google'`, `'slack'`, `'apple'`, `'microsoft'`, `'okta'`, `'aws'`, `'resend'`, `'stripe'`, `'mongoatlas'`, `'clerk'`, or `'linear'` |
 | `port` | `4000` | Port for the HTTP server |
 | `seed` | none | Inline seed data (same shape as YAML config) |
 | `baseUrl` | none | Override advertised base URL. Per-service `baseUrl` in seed config takes highest priority, then this option, then `EMULATE_BASE_URL` env var (supports `{service}`), then `PORTLESS_URL` (supports `{service}`, automatically set by the `portless` CLI wrapper), then `http://localhost:<port>`. |
@@ -332,6 +338,51 @@ slack:
         - team:read
   strict_scopes: false
 
+linear:
+  organization:
+    name: Acme
+    url_key: acme
+  users:
+    - email: admin@example.com
+      name: Admin User
+      admin: true
+    - email: dev@example.com
+      name: Developer
+  teams:
+    - key: ENG
+      name: Engineering
+      states:
+        - name: Backlog
+          type: backlog
+        - name: Todo
+          type: unstarted
+        - name: In Progress
+          type: started
+        - name: Done
+          type: completed
+  labels:
+    - name: Bug
+      color: "#d92d20"
+      team: ENG
+  issues:
+    - team: ENG
+      title: Fix local checkout test
+      state: Todo
+      assignee: dev@example.com
+      labels: [Bug]
+  oauth_apps:
+    - client_id: lin_example_client_id
+      client_secret: example_client_secret
+      name: My Linear App
+      redirect_uris:
+        - http://localhost:3000/api/auth/callback/linear
+      scopes: [read, write, issues:create, comments:create]
+  tokens:
+    - token: lin_test_admin
+      user: admin@example.com
+      scopes: [read, write, issues:create, comments:create, admin]
+  strict_scopes: false
+
 apple:
   users:
     - email: testuser@icloud.com
@@ -447,6 +498,20 @@ slack:
         - "http://localhost:3000/api/auth/callback/slack"
 ```
 
+### Linear OAuth Apps
+
+```yaml
+linear:
+  oauth_apps:
+    - client_id: "lin_example_client_id"
+      client_secret: "example_client_secret"
+      name: "My Linear App"
+      redirect_uris:
+        - "http://localhost:3000/api/auth/callback/linear"
+      scopes: [read, write, issues:create, comments:create]
+      actor: user
+```
+
 ### Apple OAuth Clients
 
 ```yaml
@@ -771,6 +836,35 @@ Slack scope checks are relaxed by default so local tests can use simple bearer t
 
 Current Slack limits: Slack Connect, Enterprise Grid admin APIs, Audit Logs API, SCIM, Legal Holds, Socket Mode, slash command and interaction simulation, user groups, reminders, stars, calls, canvases, lists, functions, workflows, chat streaming, legacy `files.upload`, exact rate limiting, and paid-plan behavior are not implemented.
 
+## Linear API
+
+Stateful Linear GraphQL API emulation with seeded organizations, users, teams, workflow states, issues, comments, labels, projects, cycles, OAuth apps, tokens, webhooks, and basic agent sessions. GraphQL reads and writes mutate in-memory state and use Relay-style connections with opaque cursors. OAuth supports authorization code, PKCE, refresh token, revoke, client credentials, and `actor=app` tokens for local app-actor tests. Supported writes dispatch Linear-shaped webhook payloads with `Linear-Delivery`, `Linear-Event`, and `Linear-Signature` headers when webhooks are configured.
+
+### GraphQL
+
+- `POST /graphql` - GraphQL endpoint for queries and mutations
+- `GET /graphql` - query-string GraphQL endpoint for tooling
+- Queries: `viewer`, `organization`, `users`, `user`, `teams`, `team`, `workflowStates`, `workflowState`, `issues`, `issue`, `comments`, `comment`, `issueLabels`, `issueLabel`, `projects`, `project`, `cycles`, `cycle`, `webhooks`, `webhook`, `agentSessions`, `agentSession`
+- Mutations: `issueCreate`, `issueUpdate`, `issueDelete`, `issueArchive`, `issueUnarchive`, `commentCreate`, `commentUpdate`, `commentDelete`, `issueLabelCreate`, `issueLabelUpdate`, `issueLabelDelete`, `issueAddLabel`, `issueRemoveLabel`, `webhookCreate`, `webhookDelete`, `agentSessionCreateOnIssue`, `agentSessionCreateOnComment`, `agentSessionUpdate`, `agentActivityCreate`
+
+### OAuth
+
+- `GET /oauth/authorize` - authorization endpoint with local user picker
+- `POST /oauth/authorize/callback` - local user picker callback that creates an authorization code
+- `POST /oauth/token` - authorization code, refresh token, and client credentials grants
+- `POST /oauth/revoke` - revoke access or refresh tokens
+
+OAuth app `actor` config is authoritative. Apps configured with `actor: user` use authorization code flows. Apps configured with `actor: app` use the app install flow and can request client credentials tokens.
+
+### Webhooks And Inspector
+
+- `webhookCreate` / `webhookDelete` manage local webhook subscriptions
+- `GET /` - tabbed local inspector for issues, teams, users, projects, agents, auth records, webhook subscriptions, and deliveries
+
+Linear scope checks are relaxed by default so local tests can use simple bearer tokens or the seeded `lin_test_admin` token. Set `linear.strict_scopes: true` in seed config to require `read`, `write`, `issues:create`, `comments:create`, or `admin` on supported GraphQL operations.
+
+Current Linear limits: full schema coverage, exact production rate limiting, notification inbox behavior, rich document APIs, customer APIs, initiative APIs, exact search relevance, and production agent behavior are not implemented. Agent support is a focused local-test subset.
+
 ## Apple Sign In
 
 Sign in with Apple emulation with authorization code flow, PKCE support, RS256 ID tokens, and OIDC discovery.
@@ -954,6 +1048,7 @@ packages/
     github/         # GitHub API service
     google/         # Google OAuth 2.0 / OIDC + Gmail, Calendar, Drive
     slack/          # Slack Web API, OAuth v2, incoming webhooks
+    linear/         # Linear GraphQL API, OAuth, webhooks
     apple/          # Apple Sign In / OIDC
     microsoft/      # Microsoft Entra ID OAuth 2.0 / OIDC + Graph /me
     aws/            # AWS S3, SQS, IAM, STS
@@ -975,6 +1070,8 @@ Tokens are configured in the seed config and map to users. Pass them as `Authori
 
 **Slack**: All Web API endpoints require `Authorization: Bearer <token>`. Seeded OAuth apps create local installation records, and OAuth v2 flow with user picker UI creates scoped bot tokens. Optional strict scope mode returns `missing_scope` when a token lacks a required method scope.
 
+**Linear**: GraphQL accepts `Authorization: Bearer <token>` or a bare personal API key value. Seeded Linear tokens map to users or app actors, OAuth apps support local authorization code and client credentials flows, and optional strict scope mode checks supported GraphQL operations.
+
 **Apple**: OIDC authorization code flow with RS256 ID tokens. On first auth per user/client pair, a `user` JSON blob is included.
 
 **Microsoft**: OIDC authorization code flow with PKCE support. Also supports client credentials grants. Microsoft Graph `/v1.0/me` available.

apps/web/app/api/docs-chat/route.ts

@@ -12,7 +12,7 @@ export const maxDuration = 60;
 
 const DEFAULT_MODEL = "anthropic/claude-haiku-4.5";
 
-const SYSTEM_PROMPT = `You are a helpful documentation assistant for emulate, a local drop-in replacement for Vercel, GitHub, Google, Slack, Apple, Microsoft, AWS, Okta, MongoDB Atlas, Resend, and Stripe APIs used in CI and no-network sandboxes.
+const SYSTEM_PROMPT = `You are a helpful documentation assistant for emulate, a local drop-in replacement for Vercel, GitHub, Google, Slack, Apple, Microsoft, Okta, AWS, Resend, Stripe, MongoDB Atlas, Clerk, and Linear APIs used in CI and no-network sandboxes.
 
 emulate provides fully stateful, production-fidelity API emulation, not mocks. The CLI is installed as the "emulate" npm package and run via "npx emulate". It also supports a programmatic API via createEmulator and a Next.js adapter (@emulators/adapter-next) for embedding emulators in your app.
 

apps/web/app/docs/architecture/page.mdx

@@ -10,13 +10,15 @@ packages/
     github/         # GitHub API service
     google/         # Google OAuth 2.0 / OIDC + Gmail, Calendar, Drive
     slack/          # Slack Web API, OAuth v2, incoming webhooks
+    linear/         # Linear GraphQL API, OAuth, webhooks
     apple/          # Apple Sign In / OIDC
     microsoft/      # Microsoft Entra ID OAuth 2.0 / OIDC + Graph /me
     aws/            # AWS S3, SQS, IAM, STS
     okta/           # Okta identity provider / OIDC
     mongoatlas/     # MongoDB Atlas Admin API + Data API
     resend/         # Resend email API
     stripe/         # Stripe billing and payments API
+    clerk/          # Clerk Backend API and OAuth
 apps/
   web/              # Documentation site (Next.js)
 ```

apps/web/app/docs/linear/layout.tsx

@@ -0,0 +1,7 @@
+import { pageMetadata } from "@/lib/page-metadata";
+
+export const metadata = pageMetadata("linear");
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return children;
+}

apps/web/app/docs/linear/page.mdx

@@ -0,0 +1,117 @@
+# Linear API
+
+Stateful Linear GraphQL API emulation with organizations, users, teams, workflow states, issues, comments, labels, projects, cycles, OAuth apps, tokens, webhooks, and basic agent sessions.
+
+## Start
+
+```bash
+npx emulate --service linear
+```
+
+When Linear is the only enabled service, it starts on `http://localhost:4000`. When all services are started, it uses `http://localhost:4012`.
+
+## URL Mapping
+
+| Real Linear URL | Emulator URL |
+|-----------------|--------------|
+| `https://api.linear.app/graphql` | `$LINEAR_EMULATOR_URL/graphql` |
+| `https://linear.app/oauth/authorize` | `$LINEAR_EMULATOR_URL/oauth/authorize` |
+| `https://api.linear.app/oauth/token` | `$LINEAR_EMULATOR_URL/oauth/token` |
+| `https://api.linear.app/oauth/revoke` | `$LINEAR_EMULATOR_URL/oauth/revoke` |
+
+## GraphQL
+
+- `POST /graphql` - GraphQL endpoint for queries and mutations
+- `GET /graphql` - query-string GraphQL endpoint for tooling
+
+Supported queries:
+
+- `viewer`
+- `organization`
+- `users`, `user`
+- `teams`, `team`
+- `workflowStates`, `workflowState`
+- `issues`, `issue`
+- `comments`, `comment`
+- `issueLabels`, `issueLabel`
+- `projects`, `project`
+- `cycles`, `cycle`
+- `webhooks`, `webhook`
+- `agentSessions`, `agentSession`
+
+Supported mutations:
+
+- `issueCreate`, `issueUpdate`, `issueDelete`, `issueArchive`, `issueUnarchive`
+- `commentCreate`, `commentUpdate`, `commentDelete`
+- `issueLabelCreate`, `issueLabelUpdate`, `issueLabelDelete`
+- `issueAddLabel`, `issueRemoveLabel`
+- `webhookCreate`, `webhookDelete`
+- `agentSessionCreateOnIssue`, `agentSessionCreateOnComment`, `agentSessionUpdate`
+- `agentActivityCreate`
+
+Connections use Relay-style cursors with `nodes`, `edges`, and `pageInfo`.
+
+## Auth
+
+GraphQL accepts `Authorization: Bearer <token>` or a bare personal API key value. The default seeded token is `lin_test_admin`.
+
+Scope checks are relaxed by default. Set `linear.strict_scopes: true` to require supported operation scopes such as `read`, `write`, `issues:create`, `comments:create`, and `admin`.
+
+## OAuth
+
+- `GET /oauth/authorize` - authorization endpoint with local user picker
+- `POST /oauth/authorize/callback` - local callback used by the user picker
+- `POST /oauth/token` - authorization code, refresh token, and client credentials grants
+- `POST /oauth/revoke` - revoke access or refresh tokens
+
+OAuth apps can use `actor: user` or `actor: app`. The configured actor is authoritative. User actor apps use authorization code flows. App actor apps use the app install flow and can request client credentials tokens.
+
+## Seed Config
+
+```yaml
+linear:
+  organization:
+    name: Acme
+    url_key: acme
+  users:
+    - email: admin@example.com
+      name: Admin User
+      admin: true
+    - email: dev@example.com
+      name: Developer
+  teams:
+    - key: ENG
+      name: Engineering
+  issues:
+    - team: ENG
+      title: Fix local checkout test
+      state: Todo
+      assignee: dev@example.com
+  oauth_apps:
+    - client_id: lin_example_client_id
+      client_secret: example_client_secret
+      name: My Linear App
+      redirect_uris:
+        - http://localhost:3000/api/auth/callback/linear
+      scopes: [read, write, issues:create, comments:create]
+  tokens:
+    - token: lin_test_admin
+      user: admin@example.com
+      scopes: [read, write, issues:create, comments:create, admin]
+```
+
+## Webhooks
+
+Create local webhook subscriptions through `webhookCreate` or seed config. Supported writes dispatch Linear-shaped payloads with these headers:
+
+- `Linear-Delivery`
+- `Linear-Event`
+- `Linear-Signature`
+
+## Inspector
+
+- `GET /` - tabbed inspector for issues, teams, users, projects, agent sessions, OAuth apps, tokens, webhook subscriptions, and webhook deliveries
+
+## Current Limits
+
+Full Linear schema coverage, exact production rate limiting, notification inbox behavior, rich document APIs, customer APIs, initiative APIs, exact search relevance, and full production agent behavior are not implemented.

apps/web/app/docs/page.mdx

@@ -1,6 +1,6 @@
 # Getting Started
 
-Local drop-in replacement for Vercel, GitHub, Google, Slack, Apple, Microsoft, AWS, Okta, MongoDB Atlas, Resend, and Stripe APIs. Built for CI and no-network sandboxes. Fully stateful, production-fidelity API emulation. Not mocks.
+Local drop-in replacement for Vercel, GitHub, Google, Slack, Apple, Microsoft, Okta, AWS, Resend, Stripe, MongoDB Atlas, Clerk, and Linear APIs. Built for CI and no-network sandboxes. Fully stateful, production-fidelity API emulation. Not mocks.
 
 ## Quick Start
 
@@ -16,11 +16,13 @@ All services start with sensible defaults. No config file needed:
 - **Slack** on `http://localhost:4003`
 - **Apple** on `http://localhost:4004`
 - **Microsoft** on `http://localhost:4005`
-- **AWS** on `http://localhost:4006`
-- **Okta** on `http://localhost:4007`
-- **MongoDB Atlas** on `http://localhost:4008`
-- **Resend** on `http://localhost:4009`
-- **Stripe** on `http://localhost:4010`
+- **Okta** on `http://localhost:4006`
+- **AWS** on `http://localhost:4007`
+- **Resend** on `http://localhost:4008`
+- **Stripe** on `http://localhost:4009`
+- **MongoDB Atlas** on `http://localhost:4010`
+- **Clerk** on `http://localhost:4011`
+- **Linear** on `http://localhost:4012`
 
 ## CLI
 

apps/web/app/docs/programmatic-api/page.mdx

@@ -59,7 +59,7 @@ afterAll(() => Promise.all([github.close(), vercel.close()]))
     <tr>
       <td><code>service</code></td>
       <td><em>(required)</em></td>
-      <td>Service name: <code>'vercel'</code>, <code>'github'</code>, <code>'google'</code>, <code>'slack'</code>, <code>'apple'</code>, <code>'microsoft'</code>, <code>'aws'</code>, <code>'okta'</code>, <code>'mongoatlas'</code>, <code>'resend'</code>, or <code>'stripe'</code></td>
+      <td>Service name: <code>'vercel'</code>, <code>'github'</code>, <code>'google'</code>, <code>'slack'</code>, <code>'apple'</code>, <code>'microsoft'</code>, <code>'okta'</code>, <code>'aws'</code>, <code>'resend'</code>, <code>'stripe'</code>, <code>'mongoatlas'</code>, <code>'clerk'</code>, or <code>'linear'</code></td>
     </tr>
     <tr>
       <td><code>port</code></td>
@@ -109,7 +109,7 @@ afterAll(() => Promise.all([github.close(), vercel.close()]))
 Each emulator is published as its own `@emulators/*` package. Install only the ones you need:
 
 ```bash
-npm install @emulators/github @emulators/google @emulators/stripe
+npm install @emulators/github @emulators/google @emulators/linear
 ```
 
 ### Available packages
@@ -126,13 +126,15 @@ npm install @emulators/github @emulators/google @emulators/stripe
     <tr><td><code>@emulators/github</code></td><td>GitHub API</td></tr>
     <tr><td><code>@emulators/google</code></td><td>Google OAuth, Gmail, Calendar, Drive</td></tr>
     <tr><td><code>@emulators/slack</code></td><td>Slack Web API, OAuth v2, webhooks</td></tr>
+    <tr><td><code>@emulators/linear</code></td><td>Linear GraphQL API, OAuth, webhooks</td></tr>
     <tr><td><code>@emulators/apple</code></td><td>Apple Sign In / OIDC</td></tr>
     <tr><td><code>@emulators/microsoft</code></td><td>Microsoft Entra ID, Graph API</td></tr>
     <tr><td><code>@emulators/aws</code></td><td>AWS S3, SQS, IAM, STS</td></tr>
     <tr><td><code>@emulators/okta</code></td><td>Okta identity provider / OIDC</td></tr>
     <tr><td><code>@emulators/mongoatlas</code></td><td>MongoDB Atlas Admin API + Data API</td></tr>
     <tr><td><code>@emulators/resend</code></td><td>Resend email API</td></tr>
     <tr><td><code>@emulators/stripe</code></td><td>Stripe billing and payments API</td></tr>
+    <tr><td><code>@emulators/clerk</code></td><td>Clerk Backend API and OAuth</td></tr>
     <tr><td><code>@emulators/core</code></td><td>Shared store, middleware, and utilities</td></tr>
     <tr><td><code>@emulators/adapter-next</code></td><td>Next.js App Router integration</td></tr>
   </tbody>

apps/web/components/docs-mobile-nav.tsx

@@ -26,6 +26,7 @@ const sections: NavSection[] = [
       { href: "/docs/github", label: "GitHub" },
       { href: "/docs/google", label: "Google" },
       { href: "/docs/slack", label: "Slack" },
+      { href: "/docs/linear", label: "Linear" },
       { href: "/docs/apple", label: "Apple" },
       { href: "/docs/microsoft", label: "Microsoft Entra ID" },
       { href: "/docs/aws", label: "AWS" },

apps/web/components/docs-nav.tsx

@@ -24,6 +24,7 @@ const sections: NavSection[] = [
       { href: "/docs/github", label: "GitHub" },
       { href: "/docs/google", label: "Google" },
       { href: "/docs/slack", label: "Slack" },
+      { href: "/docs/linear", label: "Linear" },
       { href: "/docs/apple", label: "Apple" },
       { href: "/docs/microsoft", label: "Microsoft Entra ID" },
       { href: "/docs/aws", label: "AWS" },

apps/web/lib/docs-navigation.ts

@@ -12,6 +12,7 @@ export const allDocsPages: NavItem[] = [
   { name: "GitHub API", href: "/docs/github" },
   { name: "Google API", href: "/docs/google" },
   { name: "Slack API", href: "/docs/slack" },
+  { name: "Linear API", href: "/docs/linear" },
   { name: "Apple Sign In", href: "/docs/apple" },
   { name: "Microsoft Entra ID", href: "/docs/microsoft" },
   { name: "AWS", href: "/docs/aws" },