Initial Commit

openspec/archive/2026-05-26-api-graphql-ui-altair/proposal.md

@@ -0,0 +1,50 @@
+# `@suaveplan/api-graphql-ui-altair` — Altair UI mount at `/graphql/ui`
+
+**Package**: `@suaveplan/api-graphql-ui-altair`
+**Status**: PROPOSED
+**Type**: new-package
+**Stage**: 7 (GraphQL + WebSocket / SSE engines) — see umbrella `openspec/changes/api-plugin-foundation/`
+
+## Why
+
+Per design doc §10.6 Altair is the explicit alternative GraphQL UI alongside GraphiQL: "GET /graphql/ui — GraphiQL (or Altair via `api-graphql-ui-altair`)". Altair has a richer feature set — environment management, response history, query-saving collections — preferred by teams who do heavy in-browser API development. Operators wire one OR the other; the engine adapters (`api-graphql-yoga`, `api-graphql-apollo`) return 404 at `/graphql/ui` when neither is wired.
+
+This package is the structural sibling of `api-graphql-ui-graphiql` — same plugin shape, same mount semantics, different bundled UI.
+
+## What changes
+
+Net-new package depending on `@suaveplan/api-types`, `@suaveplan/api-router`, `@suaveplan/api-graphql`, `@suaveplan/error`, `@suaveplan/logger`, and `altair-static` (peer; bundled assets).
+
+- ADDED: `createAltairUi(opts)` — factory returning a `RouterPlugin` value mounting `GET <uiEndpoint>`.
+- ADDED: `AltairUiOptions` — Zod-validated config: `uiEndpoint` (default `/graphql/ui`), `graphqlEndpoint` (default `/graphql`), `subscriptionEndpoint` (default `/graphql/ws`), `theme` (`"light"` | `"dark"` | `"system"`), `initialQuery`, `initialHeaders`, `initialEnvironments` (Altair-specific feature).
+- ADDED: Static-asset serving from package's own `dist/assets/` (no CDN).
+- ADDED: CSP headers — same posture as the GraphiQL variant.
+- ADDED: `GRAPHQL_UI_ALTAIR_*` error codes: `GRAPHQL_UI_ALTAIR_ASSET_MISSING`, `GRAPHQL_UI_ALTAIR_ENDPOINT_COLLISION`.
+- ADDED: OTel instrument: `graphql.ui.requests_total { ui: "altair" }` — same metric name as the GraphiQL variant, only the label differs, so dashboards can sum across both UIs.
+
+## Out of scope
+
+- A CDN-fetched Altair variant.
+- The GraphiQL alternative.
+- Co-mounting both UIs on the same path — host config refuses if both are wired against the same `uiEndpoint`.
+
+## Source mapping
+
+Genesis-original. Source of design intent: `docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md`.
+
+| Requirement | Design doc section |
+|---|---|
+| Altair as alternative at `/graphql/ui` | §10.6 |
+| UI as opt-in, separate package | §10.6 |
+| Bundled assets only | §10.6 + foundation security posture |
+
+## Verification approach
+
+- `src/factory/create-altair-ui.test.ts` — factory returns `RouterPlugin`; HTML response embeds configured endpoints; CSP header.
+- `src/factory/create-altair-ui.spec-conformance.test.ts` — same conformance shape as the GraphiQL spec — endpoint mount + embedded-config.
+- `src/assets/assets.test.ts` — no external host references; missing asset raises `GRAPHQL_UI_ALTAIR_ASSET_MISSING`.
+- `tests/integration/altair-end-to-end.test.ts` (30000ms) — boots `api-graphql-yoga` + this UI plugin, Playwright opens `/graphql/ui`, runs a query, asserts results render.
+
+## Migration impact
+
+None — additive only.

openspec/archive/2026-05-26-api-graphql-ui-altair/specs/api-graphql-ui-altair/spec.md

@@ -0,0 +1,83 @@
+<!-- markdownlint-disable MD024 -->
+
+# Capability Spec Delta: api-graphql-ui-altair (api-graphql-ui-altair)
+
+**Package**: `@suaveplan/api-graphql-ui-altair`
+**Status**: PROPOSED
+
+> Every requirement carries a `**Verified by:**` line.
+
+## ADDED Requirements
+
+### Requirement: Mounts Altair at the configured UI endpoint
+
+The package SHALL expose `createAltairUi(opts)` returning a `RouterPlugin` that registers `GET <uiEndpoint>` (default `/graphql/ui`). The response MUST be the Altair HTML shell embedding the configured `graphqlEndpoint`, `subscriptionEndpoint`, `initialQuery`, `initialHeaders`, and `initialEnvironments`.
+
+#### Scenario: default mount serves Altair at /graphql/ui
+
+- **WHEN** the plugin is mounted with default `opts`
+- **THEN** `GET /graphql/ui` returns 200 AND the body contains the Altair shell AND the embedded `graphqlEndpoint` reads `/graphql`
+
+#### Scenario: configured initial environments flow into the shell
+
+- **WHEN** `createAltairUi({ initialEnvironments: { production: { url: "https://api.example.com" } } })`
+- **THEN** the rendered HTML embeds those environments
+
+**Verified by:** `src/factory/create-altair-ui.test.ts::"default mount returns Altair HTML at /graphql/ui"` AND `src/factory/create-altair-ui.spec-conformance.test.ts::"initialEnvironments flow into embedded shell"`
+
+---
+
+### Requirement: Bundled assets only — no CDN fetches
+
+Every static asset SHALL be served from this package's `dist/assets/`. No external host references. Cache-busting hashes embedded. Missing asset returns 404 with `GRAPHQL_UI_ALTAIR_ASSET_MISSING`.
+
+#### Scenario: no external hosts in the shell
+
+- **WHEN** the HTML body is inspected
+- **THEN** no `src` or `href` attribute points at an external host
+
+#### Scenario: missing asset returns spec'd code
+
+- **WHEN** a request arrives for `<uiEndpoint>/assets/does-not-exist.js`
+- **THEN** the response is 404 with `code: "GRAPHQL_UI_ALTAIR_ASSET_MISSING"`
+
+**Verified by:** `src/assets/assets.test.ts::"rendered shell references no external hosts"` AND `src/assets/assets.test.ts::"missing asset returns GRAPHQL_UI_ALTAIR_ASSET_MISSING"`
+
+---
+
+### Requirement: CSP header on the HTML response
+
+The response SHALL carry `Content-Security-Policy: default-src 'self'; style-src 'self' 'unsafe-inline'`. Inline scripts MUST NOT be permitted.
+
+#### Scenario: CSP header present, scripts not 'unsafe-inline'
+
+- **WHEN** the HTML response is returned
+- **THEN** the CSP header is set AND `script-src` does NOT include `'unsafe-inline'`
+
+**Verified by:** `src/headers/csp.test.ts::"CSP header set with 'unsafe-inline' only for style-src"`
+
+---
+
+### Requirement: Endpoint-collision detection
+
+If `<uiEndpoint>` is already mounted, this package SHALL refuse with `GRAPHQL_UI_ALTAIR_ENDPOINT_COLLISION`.
+
+#### Scenario: collision refused
+
+- **WHEN** another plugin has already mounted `GET /graphql/ui`
+- **THEN** mount fails with `GRAPHQL_UI_ALTAIR_ENDPOINT_COLLISION`
+
+**Verified by:** `src/factory/create-altair-ui.test.ts::"endpoint collision refused with GRAPHQL_UI_ALTAIR_ENDPOINT_COLLISION"`
+
+---
+
+### Requirement: OTel counter shares the GraphiQL variant's metric name
+
+The package SHALL emit `graphql.ui.requests_total` counter labelled `{ ui: "altair" }` on each UI HTML request. The metric name is deliberately identical to the GraphiQL variant's so dashboards can sum across both UIs by dropping the `ui` label.
+
+#### Scenario: UI HTML request increments the counter with ui="altair"
+
+- **WHEN** `GET /graphql/ui` returns 200
+- **THEN** an in-memory `MeterProvider` observes `graphql.ui.requests_total{ui="altair"}` increment by 1
+
+**Verified by:** `src/instruments/instruments.test.ts::"UI HTML increments graphql.ui.requests_total with ui='altair' label"`

openspec/archive/2026-05-26-api-graphql-ui-altair/tasks.md

@@ -0,0 +1,69 @@
+# Tasks — `@suaveplan/api-graphql-ui-altair`
+
+> Every checkbox MUST reflect work actually done in this change.
+
+## 0. Pre-flight (non-negotiable)
+
+- [x] 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)
+- [x] 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.
+- [x] 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. Spec authoring
+
+- [x] 1.1 Read design doc §10.6
+- [x] 1.2 Read umbrella Stage 7 acceptance
+- [x] 1.3 Read sibling `openspec/changes/api-graphql-ui-graphiql/` for structural parity
+- [x] 1.4 Read `openspec/AGENTS.md` Sections 13 and 14
+- [x] 1.5 Draft `proposal.md`
+- [x] 1.6 Draft `specs/api-graphql-ui-altair/spec.md`
+- [x] 1.7 Every requirement carries a `**Verified by:**` line
+
+## 2. Implementation
+
+- [x] 2.1 Scaffold `packages/api/api-graphql-ui-altair/`
+- [x] 2.2 `src/options/options.ts` — `AltairUiOptions` Zod schema
+- [x] 2.3 `src/factory/create-altair-ui.ts` — `createAltairUi(opts)` returning `RouterPlugin`
+- [x] 2.4 `src/html/render-shell.ts` — Altair HTML shell with embedded config
+- [x] 2.5 `src/assets/assets.ts` — static-asset map from `altair-static`
+- [x] 2.6 `src/headers/csp.ts` — Content-Security-Policy header
+- [x] 2.7 `src/instruments/instruments.ts` — `graphql.ui.requests_total{ ui: "altair" }` counter
+- [x] 2.8 `src/error-codes.ts` — 2 `GRAPHQL_UI_ALTAIR_*` codes
+- [x] 2.9 `src/index.ts` — explicit named re-exports
+
+## 3. Tests
+
+- [x] 3.1 Unit tests, every `it(...)` `{ timeout: 5000 }`
+- [x] 3.2 Conformance test pins mount + embedded-config
+- [x] 3.3 Asset reachability tests
+- [x] 3.4 Playwright end-to-end (`{ timeout: 30000 }`)
+- [x] 3.5 All tests import from `@suaveplan/testing/runner`
+
+## 4. Documentation
+
+- [x] 4.1 Sibling `.md` per implementation file
+- [x] 4.2 `README.md` calling out: opt-in, bundled assets only, alternative to GraphiQL
+
+## 5. Pre-archive verification
+
+- [x] 5.1 `bun run check` — 0/0/0
+- [x] 5.2 `bunx turbo lint typecheck test --filter=@suaveplan/api-graphql-ui-altair` — green
+- [x] 5.3 `bunx turbo test:coverage --filter=@suaveplan/api-graphql-ui-altair` — 100/100/100/100
+- [x] 5.4 `bun scripts/openspec-conformance.ts @suaveplan/api-graphql-ui-altair` — exit 0
+- [x] 5.5 `bunx turbo build --filter=@suaveplan/api-graphql-ui-altair` — green
+
+## 6. Pre-archive 7-row checklist
+
+- [x] 6.1 Generics where applicable; `expectTypeOf` on literal-type claims
+- [x] 6.2 Zod schema on options
+- [x] 6.3 Both error codes thrown
+- [x] 6.4 Strict-mode tested
+- [x] 6.5 OTel counter asserted with in-memory `MeterProvider`
+- [x] 6.6 Lifecycle dedup N/A
+- [x] 6.7 No retroactive tick
+
+## 7. Archive
+
+- [x] 7.1 Fold spec delta
+- [x] 7.2 Move to `openspec/archive/<yyyy-mm-dd>-api-graphql-ui-altair/`
+- [x] 7.3 Tick Stage-7 row in umbrella tasks
+- [x] 7.4 Refresh `MANIFEST.md`