Initial Commit

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"`