@specbook/ui 0.0.0-stage → 0.1.0

package/src/embed/styles.ts

@@ -0,0 +1,27 @@
+import complete from 'prism-code-editor/autocomplete.css?inline'
+import completeIcons from 'prism-code-editor/autocomplete-icons.css?inline'
+import layout from 'prism-code-editor/layout.css?inline'
+import app from '../styles/app.css?inline'
+import panel from '../styles/panel.css?inline'
+import tokens from '../styles/tokens.css?inline'
+
+const sheet = (css: string) => {
+  const s = new CSSStyleSheet()
+  s.replaceSync(css)
+  return s
+}
+
+/** `tokens` first so its layer order wins; the host page's CSS can't reach in, ours can't leak out. */
+export const playSheets = (css: string) => [sheet(tokens), sheet(css)]
+export const panelSheets = () => [
+  sheet(tokens),
+  sheet(layout),
+  sheet(complete),
+  sheet(completeIcons),
+  sheet(app),
+  sheet(panel),
+  sheet(root),
+]
+
+/** Inline `color`/`font` on the host would be beaten by host-page rules, so the root element sets them. */
+const root = '.sb-root{font:14px/1.5 var(--sb-font-sans);color:var(--sb-text)}'

package/src/embed.ts

@@ -0,0 +1,65 @@
+import type { Target } from './embed/panel'
+import tokens from './styles/tokens.css?inline'
+
+const css = `button {
+  font: 13px/1.4 var(--sb-font-sans);
+  margin-inline: 0.5em;
+  padding: 0 0.6em;
+  cursor: pointer;
+  border: 1px solid var(--sb-border);
+  border-radius: var(--sb-radius-control);
+  background: var(--sb-surface);
+  color: var(--sb-accent);
+}
+button:hover { background: var(--sb-surface-raised); }
+button:focus-visible { outline: 2px solid var(--sb-focus-ring); }`
+
+/** The panel (editor, grammars, runner) is a separate chunk fetched on first click. */
+async function open(target: Target) {
+  const { show } = await import('./embed/panel')
+  show(target)
+}
+
+class SpecbookPlay extends HTMLElement {
+  target: Target = {}
+
+  connectedCallback() {
+    if (this.shadowRoot) return
+    const root = this.attachShadow({ mode: 'open' })
+    const sheet = new CSSStyleSheet()
+    sheet.replaceSync(`${tokens}\n@layer base{${css}}`)
+    root.adoptedStyleSheets = [sheet]
+    const b = document.createElement('button')
+    b.type = 'button'
+    b.part.add('play')
+    b.textContent = '▶ Play'
+    b.addEventListener('click', () => open(this.target))
+    root.append(b)
+  }
+}
+
+customElements.define('specbook-play', SpecbookPlay)
+
+function attach(el: HTMLElement) {
+  if (el.dataset.specbookReady) return
+  el.dataset.specbookReady = ''
+  const play = document.createElement('specbook-play') as SpecbookPlay
+  play.target = {
+    service: el.dataset.specbook || undefined,
+    operation: el.dataset.operation,
+    sequence: el.dataset.sequence,
+    example: el.dataset.example,
+    tab: el.dataset.tab === 'docs' ? 'docs' : undefined,
+  }
+  el.append(play)
+}
+
+const scan = (root: ParentNode) =>
+  root.querySelectorAll<HTMLElement>('[data-specbook]:not([data-specbook-ready])').forEach(attach)
+
+scan(document)
+// SPA docs add content after load
+new MutationObserver(() => scan(document)).observe(document.documentElement, {
+  childList: true,
+  subtree: true,
+})

package/src/engine.ts

@@ -0,0 +1,432 @@
+// Run orchestration for the UI. Pure TS (no DOM) so it can be unit-tested with a fake registry.
+import {
+  type AuthProfile,
+  createFetchTransport,
+  createMockTransport,
+  deepMerge,
+  type Example,
+  installFaker,
+  type OpMeta,
+  prepareFaker,
+  type RequestDef,
+  type RunEvent,
+  type RunResult,
+  runRequest,
+  runSequence,
+  type Sequence,
+  type SpecbookConfig,
+  type Transport,
+  usesFaker,
+} from '@specbook/core'
+import { type ExtensionBridge, extensionTransport } from './extension'
+import { absoluteBase, routingTransport, withPageSecrets } from './routing'
+import { originOf, type SecretStore, secretStore } from './secrets'
+
+export interface ExampleEntry {
+  name: string
+  source: 'generated' | 'project'
+  /** Folder key; upload paths in the example are relative to it. */
+  dir: string
+  load: (v: number) => Promise<{ default: unknown }>
+}
+
+export interface DocEntry {
+  file: string
+  operation?: string
+  sequence?: string
+  title?: string
+  load: () => Promise<string>
+}
+
+export interface Registry {
+  manifests: Record<string, { operations: { id: string; statuses: number[] }[] }>
+  /** response examples: `service/Op.<status|default>` */
+  examples: Record<string, (v: number) => Promise<{ default: unknown }>>
+  /** request examples by `service/Op` */
+  requestExamples: Record<string, ExampleEntry[]>
+  /** files examples may upload: `<dir>/<name>` -> URL */
+  assets: Record<string, () => Promise<string>>
+  docs: DocEntry[]
+  operations: Record<string, (v: number) => Promise<Record<string, any>>>
+  loadConfig: (v: number) => Promise<{ default: any }>
+  /** Project's @faker-js/faker (ESM), when installed. */
+  loadFaker?: ((v: number) => Promise<Record<string, any>>) | null
+  mode?: 'dev' | 'static'
+  /** variables from `.specbook/environments/<env>.env`, baked in at build time */
+  environmentVars?: Record<string, Record<string, string>>
+}
+
+export interface RunInput {
+  env: string
+  version: number
+  /** Forced mock status per run (mock env only). */
+  mockStatus?: number
+  params?: Record<string, unknown>
+  vars?: Record<string, unknown>
+  onEvent?: (e: RunEvent) => void
+  onInput?: Parameters<typeof runSequence>[1]['onInput']
+  signal?: AbortSignal
+  proxyBase?: string
+  locale?: string
+  seed?: number
+  /** Folder upload paths are relative to when the request was not built from a named example. */
+  fileDir?: string
+}
+
+export interface EngineOptions {
+  /** The bridge to the browser extension when it is installed and enabled for this page. */
+  extension?: () => Promise<ExtensionBridge | undefined>
+  /** Where the person's typed secrets are kept (the page's store by default). */
+  secrets?: SecretStore
+}
+
+export function createEngine(reg: Registry, opts: EngineOptions = {}) {
+  const mockLoader = {
+    statuses: (service: string, opId: string) =>
+      reg.manifests[service]?.operations.find((o) => o.id === opId)?.statuses ?? [],
+    async example(service: string, opId: string, status: number) {
+      const get = async (s: number | 'default') =>
+        (await reg.examples[`${service}/${opId}.${s}`]?.(0))?.default
+      return (await get(status)) ?? (await get('default'))
+    },
+  }
+
+  async function config(version: number): Promise<SpecbookConfig> {
+    return (await reg.loadConfig(version)).default as SpecbookConfig
+  }
+
+  /** Environments the config marks `production` or `sandbox`; the rest are judged by their name. */
+  async function environmentRisks(
+    version: number,
+  ): Promise<Record<string, 'production' | 'sandbox'>> {
+    const c = await config(version)
+    const out: Record<string, 'production' | 'sandbox'> = {}
+    for (const [name, e] of Object.entries(c.environments ?? {})) {
+      const risk = (e as { risk?: string } | undefined)?.risk
+      if (risk === 'production' || risk === 'sandbox') out[name] = risk
+    }
+    return out
+  }
+
+  async function environments(version: number): Promise<string[]> {
+    const c = await config(version)
+    const envs = new Set<string>(['mock'])
+    for (const s of Object.values(c.services ?? {}))
+      for (const e of Object.keys(s.baseUrl ?? {})) envs.add(e)
+    for (const e of Object.keys(reg.environmentVars ?? {})) envs.add(e)
+    for (const e of Object.keys(c.environments ?? {})) envs.add(e)
+    return [...envs]
+  }
+
+  /** The environment's own variables: read live from the dev server, baked in for static builds. */
+  async function environmentVars(env: string): Promise<Record<string, string>> {
+    if (reg.mode === 'dev') {
+      try {
+        const r = await fetch(`/__specbook/environment?env=${encodeURIComponent(env)}`)
+        if (r.ok) return ((await r.json()) as { vars: Record<string, string> }).vars
+      } catch {
+        /* fall back to what was baked in */
+      }
+    }
+    return reg.environmentVars?.[env] ?? {}
+  }
+
+  /** Names of the variables the project already supplies in `env`: config, per-environment and env files. */
+  async function knownVars(env: string, version: number): Promise<string[]> {
+    const c = await config(version)
+    return [
+      ...new Set([
+        ...Object.keys(c.vars ?? {}),
+        ...Object.keys(c.environments?.[env]?.vars ?? {}),
+        ...Object.keys(await environmentVars(env)),
+      ]),
+    ]
+  }
+
+  /**
+   * One transport per run, routing each request by its service (`routeFor`). Typed values are bound to
+   * the API's origin first; placeholders left over are filled by the dev server or reported as missing.
+   */
+  async function transportFor(env: string, proxyBase: string, version: number): Promise<Transport> {
+    if (env === 'mock') return createMockTransport({ loader: mockLoader })
+    const cfg = await config(version)
+    const pageHref = globalThis.location?.href
+    const pageOrigin = globalThis.location?.origin
+    const baseOf = (service: string) => {
+      const url = cfg.services?.[service]?.baseUrl?.[env]
+      if (!url) throw new Error(`No base URL for ${service} in the "${env}" environment`)
+      return absoluteBase(url, pageHref)
+    }
+    const hasProxy = reg.mode !== 'static'
+    const bridge = await opts.extension?.()
+    const ext = bridge ? extensionTransport(bridge, safeBase) : undefined
+    const store = opts.secrets ?? secretStore
+
+    const direct = createFetchTransport({ baseUrl: baseOf })
+    const viaProxy = hasProxy
+      ? createFetchTransport({ baseUrl: (service) => `${proxyBase}/${env}/${service}` })
+      : undefined
+    const routed = routingTransport({
+      direct: guardCors(withPageSecrets(direct, { store, originFor, unresolved: 'fail' })),
+      proxy: viaProxy
+        ? withPageSecrets(viaProxy, { store, originFor, unresolved: 'keep' })
+        : undefined,
+      extension: ext ? withPageSecrets(ext, { store, originFor, unresolved: 'keep' }) : undefined,
+      baseOf: safeBase,
+      pageOrigin,
+    })
+    return routed
+
+    function originFor(service: string) {
+      return originOf(safeBase(service))
+    }
+    // routing must not throw for a service with no base URL here: the proxy answers that with a 404
+    function safeBase(service: string) {
+      try {
+        return baseOf(service)
+      } catch {
+        return ''
+      }
+    }
+    function guardCors(inner: Transport): Transport {
+      return async (req, signal) => {
+        try {
+          return await inner(req, signal)
+        } catch (e) {
+          // a blocked cross-origin call surfaces as a bare TypeError("Failed to fetch")
+          if (e instanceof TypeError)
+            throw new Error(
+              `The browser could not reach ${req.service} in "${env}". The API probably does not allow calls from this page (CORS). It works when the viewer runs on the API's own origin: embed it in the API's docs route ("Embed the viewer" in the README). Mock data keeps working.`,
+            )
+          throw e
+        }
+      }
+    }
+  }
+
+  /** Only the dev server knows its environment files; a hosted proxy would report its own (`managedSecrets`). */
+  async function managedSecrets(env: string): Promise<Record<string, string>> {
+    if (reg.mode !== 'dev' || env === 'mock') return {}
+    try {
+      const r = await fetch(`/__specbook/environment?env=${encodeURIComponent(env)}`)
+      if (!r.ok) return {}
+      const body = (await r.json()) as { secrets?: { name: string; source?: string }[] }
+      return Object.fromEntries(
+        (body.secrets ?? []).filter((s) => s.source).map((s) => [s.name, s.source as string]),
+      )
+    } catch {
+      return {}
+    }
+  }
+
+  const norm = (p: string) => p.replace(/^\.\//, '')
+
+  /** Display order: the author's examples first, generated ones last. */
+  const examplesOf = (key: string): ExampleEntry[] => reg.requestExamples[key] ?? []
+
+  async function loadExample(
+    key: string,
+    name: string,
+    version: number,
+  ): Promise<Example | undefined> {
+    const entry = examplesOf(key).find((e) => e.name === name)
+    if (!entry) return undefined
+    const doc = (await entry.load(version)).default as Example
+    return { ...doc, source: entry.source, dir: entry.dir }
+  }
+
+  async function readFile(path: string, dir?: string): Promise<File> {
+    const url = await reg.assets[`${dir}/${norm(path)}`]?.()
+    if (!url) throw new Error(`File "${path}" not found next to the example`)
+    const res = await fetch(url)
+    if (!res.ok) throw new Error(`Could not read "${path}" (${res.status})`)
+    return new File([await res.blob()], norm(path).split('/').pop() as string, {
+      type: res.headers.get('content-type') ?? undefined,
+    })
+  }
+
+  async function baseOptions(i: RunInput) {
+    const c = await config(i.version)
+    const auth = (c.auth ?? {}) as Record<string, AuthProfile>
+    const serviceAuth = Object.fromEntries(
+      Object.entries(c.services ?? {})
+        .filter(([, s]) => s.auth)
+        .map(([n, s]) => [n, s.auth as string]),
+    )
+    return {
+      env: i.env,
+      vars: {
+        ...(c.vars ?? {}),
+        ...(c.environments?.[i.env]?.vars ?? {}),
+        ...(await environmentVars(i.env)),
+      },
+      overrides: i.vars,
+      params: i.params,
+      transport: await transportFor(i.env, i.proxyBase ?? '/__specbook/proxy', i.version),
+      // placeholders stay in the request: the dev server's proxy or a static page's transport fills them
+      deferSecrets: true,
+      auth,
+      serviceAuth,
+      onEvent: i.onEvent,
+      onInput: i.onInput,
+      signal: i.signal,
+      example: (op: { service: string; id: string }, name: string) =>
+        loadExample(`${op.service}/${op.id}`, name, i.version),
+      readFile: (path: string, dir?: string) => readFile(path, dir ?? i.fileDir),
+    }
+  }
+
+  /** Sequences and requests with init generators or lazy data may call faker; everything else is visible. */
+  async function mayUseFaker(
+    target: RequestDef<any, any, any> | Sequence<any, any>,
+    i: RunInput,
+  ): Promise<boolean> {
+    if (target.kind === 'sequence') return true
+    const { init, data, example, path, query, headers } = target.input
+    if (
+      Object.values(init ?? {}).some((v) => typeof v === 'function') ||
+      typeof data === 'function'
+    )
+      return true
+    const base = example
+      ? await loadExample(`${target.op.service}/${target.op.id}`, example, i.version)
+      : undefined
+    return usesFaker([base, data, target.dataPatches, path, query, headers, i.vars])
+  }
+
+  async function run(
+    target: RequestDef<any, any, any> | Sequence<any, any>,
+    i: RunInput,
+  ): Promise<RunResult> {
+    // `init` generators call faker, so it must be ready before any run unless we can see it isn't used.
+    if (reg.loadFaker && (await mayUseFaker(target, i))) {
+      const [mod, cfg] = await Promise.all([reg.loadFaker(i.version), config(i.version)])
+      // a bundled module offers each locale as its own chunk; fetch only the ones this run falls back through
+      const ready = await prepareFaker(mod, cfg.faker, i.locale)
+      installFaker(ready as never, cfg.faker, { locale: i.locale, seed: i.seed })
+    }
+    const o = await baseOptions(i)
+    if (target.kind === 'sequence') return runSequence(target, o)
+    const def =
+      i.mockStatus !== undefined && i.env === 'mock'
+        ? target.with({ mock: { status: i.mockStatus } })
+        : target
+    return runRequest(def, o)
+  }
+
+  /** `base` keeps its init/capture/assert/mock; `overrides` replace path/query/headers/data. */
+  async function operationRequest(
+    key: string,
+    version: number,
+    overrides: { path?: object; query?: object; headers?: Record<string, string>; data?: unknown },
+    base?: RequestDef<any, any, any>,
+  ): Promise<RequestDef<any, any, any>> {
+    const load = reg.operations[key]
+    if (!load) throw new Error(`Unknown operation ${key}`)
+    const mod = await load(version)
+    const op = mod[key.split('/')[1] as string]
+    if (!op) throw new Error(`Operation module for ${key} has no export`)
+    const defined = Object.fromEntries(Object.entries(overrides).filter(([, v]) => v !== undefined))
+    return op.request({ ...(base?.input ?? {}), ...defined })
+  }
+
+  async function operationMeta(key: string, version: number): Promise<OpMeta | undefined> {
+    const mod = await reg.operations[key]?.(version)
+    return mod?.[key.split('/')[1] as string]?.meta
+  }
+
+  /** What a saved request sends, as an example: its example (if any) with its own fields merged over. */
+  async function savedExample(def: RequestDef<any, any, any>, version: number): Promise<Example> {
+    const key = `${def.op.service}/${def.op.id}`
+    const base = def.input.example ? await loadExample(key, def.input.example, version) : undefined
+    let data: unknown = def.input.data
+    if (typeof data === 'function')
+      data = (await (data as () => Promise<{ default: unknown }>)()).default
+    let body = deepMerge<unknown>(base?.body, data)
+    for (const patch of def.dataPatches) body = deepMerge(body, patch)
+    return {
+      name: def.input.name ?? def.op.id,
+      source: 'project',
+      dir: base?.dir,
+      path: deepMerge(base?.path ?? {}, (def.input.path ?? {}) as Record<string, unknown>),
+      query: deepMerge(base?.query ?? {}, (def.input.query ?? {}) as Record<string, unknown>),
+      headers: { ...(base?.headers ?? {}), ...(def.input.headers ?? {}) },
+      body,
+    }
+  }
+
+  async function loadVariants(
+    entries: { file: string; load: (v: number) => Promise<Record<string, any>> }[],
+    version: number,
+  ): Promise<Record<string, Variant[]>> {
+    const out: Record<string, Variant[]> = {}
+    await Promise.all(
+      entries.map(async (e) => {
+        try {
+          const def = pickRunnable(await e.load(version))
+          if (def?.kind !== 'request') return
+          const key = `${def.op.service}/${def.op.id}`
+          const name = def.input.name ?? e.file.replace(/^.*\//, '').replace(/\.req\.ts$/, '')
+          out[key] ??= []
+          out[key]?.push({ file: e.file, name, def })
+        } catch {
+          /* a broken request file must not break the list */
+        }
+      }),
+    )
+    for (const list of Object.values(out)) list.sort((a, b) => a.name.localeCompare(b.name))
+    return out
+  }
+
+  async function loadSequences(
+    entries: { file: string; load: (v: number) => Promise<Record<string, any>> }[],
+    version: number,
+  ): Promise<SequenceInfo[]> {
+    const list: SequenceInfo[] = []
+    await Promise.all(
+      entries.map(async (e) => {
+        try {
+          const seq = pickRunnable(await e.load(version))
+          if (seq?.kind === 'sequence') list.push({ file: e.file, seq })
+        } catch {
+          /* ignore broken files */
+        }
+      }),
+    )
+    return list.sort((a, b) => a.seq.meta.title.localeCompare(b.seq.meta.title))
+  }
+
+  return {
+    config,
+    environments,
+    environmentRisks,
+    managedSecrets,
+    run,
+    operationRequest,
+    operationMeta,
+    examplesOf,
+    knownVars,
+    loadExample,
+    savedExample,
+    loadVariants,
+    loadSequences,
+  }
+}
+
+export interface Variant {
+  file: string
+  name: string
+  def: RequestDef<any, any, any>
+}
+
+export interface SequenceInfo {
+  file: string
+  seq: Sequence<any, any>
+}
+
+/** Default export, else the first runnable named export. */
+export function pickRunnable(mod: Record<string, any>) {
+  const isRun = (v: any) => v && (v.kind === 'request' || v.kind === 'sequence')
+  if (isRun(mod.default)) return mod.default
+  return Object.values(mod).find(isRun)
+}

package/src/extension.ts

@@ -0,0 +1,101 @@
+import {
+  createFetchTransport,
+  requestToWire,
+  type Transport,
+  WIRE_VERSION,
+  type WireCall,
+  type WireReply,
+  wireToResponse,
+} from '@specbook/core'
+
+/**
+ * The page's side of the browser extension. The extension (its own package, not built yet) makes the
+ * outbound call from its service worker with the user's grant, using `handleWireFetch` from core, so the
+ * policy and secret substitution are the ones the dev server and a hosted proxy run.
+ *
+ * A bridge is anything that can carry a `WireCall` to it and bring a `WireReply` back: a content script
+ * relaying `postMessage`, or a test double.
+ */
+export interface ExtensionBridge {
+  /** Protocol version the extension speaks. */
+  version: number
+  send(call: WireCall, signal?: AbortSignal): Promise<WireReply>
+}
+
+declare global {
+  // a content script (or a test) may place its bridge here
+  var __SPECBOOK_EXTENSION__: ExtensionBridge | undefined
+}
+
+const CHANNEL = 'specbook'
+
+/** `postMessage` to a content script that answers on the same window. */
+function windowBridge(version: number): ExtensionBridge {
+  return {
+    version,
+    send(call, signal) {
+      return new Promise<WireReply>((resolve, reject) => {
+        const id = (call as { id?: string }).id
+        const on = (e: MessageEvent) => {
+          const m = e.data as { channel?: string; reply?: WireReply } | undefined
+          if (e.source !== window || m?.channel !== `${CHANNEL}:reply` || !m.reply) return
+          const r = m.reply as { id?: string; type: string }
+          if (id !== undefined && r.id !== id) return
+          cleanup()
+          resolve(m.reply)
+        }
+        const abort = () => {
+          cleanup()
+          window.postMessage({ channel: `${CHANNEL}:call`, call: { v: 1, type: 'abort', id } }, '*')
+          reject(new DOMException('aborted', 'AbortError'))
+        }
+        const cleanup = () => {
+          window.removeEventListener('message', on)
+          signal?.removeEventListener('abort', abort)
+        }
+        window.addEventListener('message', on)
+        signal?.addEventListener('abort', abort)
+        window.postMessage({ channel: `${CHANNEL}:call`, call }, '*')
+      })
+    },
+  }
+}
+
+/** The bridge when an extension is installed and enabled for this page, within a short wait. */
+export async function detectExtension(waitMs = 250): Promise<ExtensionBridge | undefined> {
+  const injected = globalThis.__SPECBOOK_EXTENSION__
+  if (injected) return injected
+  if (typeof window === 'undefined') return undefined
+  const bridge = windowBridge(WIRE_VERSION)
+  const timeout = new Promise<undefined>((r) => setTimeout(() => r(undefined), waitMs))
+  const pong = await Promise.race([
+    bridge.send({ v: 1, type: 'ping' }).catch(() => undefined),
+    timeout,
+  ])
+  return pong?.type === 'pong' ? { ...bridge, version: pong.version } : undefined
+}
+
+let counter = 0
+
+/**
+ * A `Transport` that sends each request to the extension. Built on the ordinary fetch transport with a
+ * `fetch` that carries the request over the bridge, so bodies, query strings and response parsing are
+ * the same as for a direct call.
+ */
+export function extensionTransport(
+  bridge: ExtensionBridge,
+  baseOf: (service: string) => string,
+): Transport {
+  const carry: typeof fetch = async (input, init) => {
+    const req = new Request(input as RequestInfo, init)
+    const id = `c${Date.now().toString(36)}${counter++}`
+    const reply = await bridge.send(
+      { v: 1, type: 'fetch', id, req: await requestToWire(req) },
+      init?.signal ?? undefined,
+    )
+    if (reply.type === 'error') throw new Error(reply.message)
+    if (reply.type !== 'response') throw new Error('unexpected reply from the extension')
+    return wireToResponse(reply.res)
+  }
+  return createFetchTransport({ baseUrl: baseOf, fetch: carry })
+}