# Tasks: enterprise-api-plugin-graphql

**Change ID**: enterprise-api-plugin-graphql
**Package**: `@suaveplan/api-plugin-graphql`
**Target path**: `api/data/api-plugin-graphql`
**Prerequisite packages on Verdaccio**: `@suaveplan/api`, `@suaveplan/api-shared`, `@suaveplan/api-plugin-auth`, `@suaveplan/events`, `@suaveplan/rate-limiter`, `@suaveplan/error`, `graphql` (external)

---

## 0. Pre-flight (non-negotiable)

- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.

## 1. Scaffold + types + errors + events

- [ ] Create directory; `package.json` v0.0.0; `graphql` in deps (catalog); standard tooling.
- [ ] Types: `GraphqlPluginConfig` (Zod), `PersistedQueryStore`, `GraphqlContext`, `OperationResult`.
- [ ] Errors: 5-code union + registration. Test + doc.
- [ ] Events: `GraphqlEventMap` (graphql:operation:completed, graphql:error).

---

## 2. Core: depth limiter

- [ ] `buildMaxDepthRule(maxDepth: number): ValidationRule` — GraphQL validation rule that rejects queries deeper than `maxDepth`. Test + doc.

---

## 3. Core: complexity analysis

- [ ] `buildComplexityRule(maxComplexity: number, fieldComplexities?: Record<string, number>): ValidationRule` — scores query and rejects over threshold. Test + doc.

---

## 4. Core: DataLoader factory

- [ ] `createDataLoader<K, V>(batchFn)` — thin wrapper ensuring all resolvers use DataLoader for N+1 prevention. Test + doc.

---

## 5. Core: persisted queries

- [ ] `PersistedQueryStore` interface: `get(hash: string): Promise<string | null>`, `set(hash, query): Promise<void>`.
- [ ] `MemoryPersistedQueryStore` default. Test + doc.

---

## 6. Auth context middleware

- [ ] Extract JWT user from `requireAuth`; make available as `ctx.user` in GraphQL execution context.
- [ ] Test + doc.

---

## 7. Routes

- [ ] `POST /graphql` — parse body; apply persisted-query lookup if `extensions.persistedQuery` present; validate (depth + complexity + auth); execute; record OTel span + counters; emit event.
- [ ] `GET /graphql` — serve GraphiQL HTML if `config.playground` and `NODE_ENV !== 'production'`.
- [ ] Rate limit per operation type on `POST /graphql`.
- [ ] Route `.test.ts` + `.md`.

---

## 8. Plugin factory + integration tests + publish

- [ ] `createGraphqlPlugin(schema, config?)`: `definePlugin`, `dependencies: ["auth"]`.
- [ ] `onInit`: register configured middleware; disable introspection in production.
- [ ] Integration: execute simple query → depth limit rejected → persisted query found + executed.
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-graphql` — green; 100% coverage.
- [ ] `bun scripts/publish.ts --package @suaveplan/api-plugin-graphql`.
- [ ] Archive → `openspec/archive/2026-04-24-enterprise-api-plugin-graphql/`.