@specbook/core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ajai Shankar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# @specbook/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The runner, mock engine, template engine and shared proxy behind Specbook: Storybook for APIs.
+
+Part of [Specbook](https://github.com/specbook-dev/specbook), Storybook for APIs. See the repository for documentation.
+
+MIT licensed.

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@specbook/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The runner, mock engine, template engine and shared proxy behind Specbook: Storybook for APIs.",
+  "keywords": [
+    "specbook",
+    "openapi",
+    "api-mocking",
+    "api-testing",
+    "mock-server"
+  ],
+  "license": "MIT",
+  "homepage": "https://ui.specbook.dev",
+  "bugs": {
+    "url": "https://github.com/specbook-dev/specbook/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/specbook-dev/specbook.git",
+    "directory": "packages/core"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./assert": {
+      "types": "./src/assert.ts",
+      "default": "./src/assert.ts"
+    },
+    "./runner": {
+      "types": "./src/runner/index.ts",
+      "default": "./src/runner/index.ts"
+    },
+    "./reporters": {
+      "types": "./src/reporters/index.ts",
+      "default": "./src/reporters/index.ts"
+    },
+    "./faker": {
+      "types": "./src/faker.ts",
+      "default": "./src/faker.ts"
+    }
+  },
+  "dependencies": {
+    "uvu": "0.5.6"
+  },
+  "files": [
+    "src",
+    "!**/*.test.*"
+  ],
+  "scripts": {
+    "build": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }

package/src/assert.ts

@@ -0,0 +1,81 @@
+// Instrumented uvu/assert: every call is recorded as pass/fail. Soft mode swallows failures.
+import * as uvu from 'uvu/assert'
+import type { Assert, AssertionResult, AssertMode } from './types'
+
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching ANSI escape sequences
+const ANSI = /\u001b\[[0-9;]*m/g
+export const stripAnsi = (s: string) => s.replace(ANSI, '')
+
+/** Plain uvu/assert, for use outside a run. */
+export const assert = uvu as unknown as Assert
+
+function locate(stack: string | undefined): AssertionResult['location'] {
+  if (!stack) return undefined
+  const lines = stack.split('\n').slice(1)
+  for (const line of lines) {
+    if (line.includes('/core/src/assert') || line.includes('node_modules')) continue
+    const m = /(?:\(|at )?([^\s()]+):(\d+):(\d+)\)?\s*$/.exec(line)
+    if (m) return { file: m[1] as string, line: Number(m[2]), column: Number(m[3]) }
+  }
+  return undefined
+}
+
+export interface Asserter {
+  assert: Assert
+  results: AssertionResult[]
+}
+
+export function createAsserter(mode: AssertMode = 'soft'): Asserter {
+  const results: AssertionResult[] = []
+
+  const wrap = (name: string, fn: (...a: any[]) => void) => {
+    const msgIndex = fn.length - 1
+    return (...args: any[]) => {
+      const given = typeof args[msgIndex] === 'string' ? (args[msgIndex] as string) : undefined
+      try {
+        fn(...args)
+        results.push({
+          label: given ?? name,
+          operator: name,
+          pass: true,
+          location: locate(new Error().stack),
+        })
+      } catch (e: any) {
+        if (e?.name !== 'Assertion') throw e
+        results.push({
+          label: stripAnsi(String(e.message ?? given ?? name)),
+          operator: name,
+          pass: false,
+          actual: e.actual,
+          expected: e.expects,
+          diff: e.details ? stripAnsi(String(e.details)) : undefined,
+          location: locate(new Error().stack),
+        })
+        if (mode === 'hard') throw e
+      }
+    }
+  }
+
+  const u = uvu as unknown as Record<string, any>
+  const out: Record<string, any> = {}
+  for (const key of [
+    'ok',
+    'is',
+    'equal',
+    'type',
+    'instance',
+    'match',
+    'throws',
+    'unreachable',
+    'snapshot',
+    'fixture',
+  ]) {
+    if (typeof u[key] === 'function') out[key] = wrap(key, u[key])
+  }
+  const not = wrap('not', u.not)
+  for (const key of Object.keys(u.not ?? {})) {
+    if (typeof u.not[key] === 'function') (not as any)[key] = wrap(`not.${key}`, u.not[key])
+  }
+  out.not = not
+  return { assert: out as Assert, results }
+}

package/src/config.ts

@@ -0,0 +1,69 @@
+import type { FakerConfig } from './faker'
+import type { AuthProfile } from './runner/run'
+import type { SecretProvider, SecretRef } from './secrets'
+
+/** What the UI shows for an environment beyond its variables. */
+export interface EnvironmentConfig {
+  vars?: Record<string, unknown>
+  /**
+   * How careful the UI should look. `production` shows the environment in red wherever it is named;
+   * `sandbox` keeps it amber even when the name contains "prod". Unset: red if the name contains
+   * "prod", amber otherwise (`mock` is always neutral).
+   */
+  risk?: 'production' | 'sandbox'
+}
+
+export interface ServiceConfig<E extends string = string> {
+  /** Path to an OpenAPI/Swagger file (relative to the config's project root). */
+  spec: string
+  baseUrl: Partial<Record<E | 'live', string>>
+  /** Default auth profile for this service. */
+  auth?: string
+}
+
+/** How the docs site presents itself. Everything is optional; unset fields fall back to the API's own title. */
+export interface BrandingConfig {
+  /** Header, overview and browser-tab title. */
+  name?: string
+  /** The overview's headline, under the logo: what this site is for. The name stays in the header and tab. */
+  title?: string
+  tagline?: string
+  /** Accent colour for buttons, selection and links (any hex colour). */
+  accent?: string
+  /** Accent in dark mode, when the light one needs to differ. */
+  accentDark?: string
+  /**
+   * Logo and favicon as URLs. Without these, drop `logo.svg` / `favicon.svg` (or png, jpg, webp)
+   * into `.specbook/branding/` and they are picked up.
+   */
+  logo?: string
+  favicon?: string
+  /** Links shown under the overview text. */
+  links?: { label: string; href: string }[]
+  /**
+   * Show "Powered by Specbook" under the overview of a published site (default). Set `false` to hide it.
+   * It is never shown by the dev server, or on a `*.specbook.dev` page.
+   */
+  badge?: boolean
+}
+
+export interface SpecbookConfig<E extends string = string> {
+  project: string
+  /** Non-sensitive variables, safe to commit. */
+  vars?: Record<string, unknown>
+  environments?: Partial<Record<E, EnvironmentConfig>>
+  /** Secret references; OSS resolves them from env vars / dotenv files. */
+  secrets?: Record<string, SecretRef>
+  services: Record<string, ServiceConfig<E>>
+  auth?: Record<string, AuthProfile>
+  secretProviders?: SecretProvider[]
+  faker?: FakerConfig
+  codegen?: { outDir?: string; importPrefix?: string }
+  branding?: BrandingConfig
+}
+
+export function defineConfig<const E extends string = string>(
+  c: SpecbookConfig<E>,
+): SpecbookConfig<E> {
+  return c
+}

package/src/controls.ts

@@ -0,0 +1,167 @@
+// Tiny Storybook-style controls DSL: runtime descriptors + inferred value types.
+
+export interface Control<T = unknown> {
+  readonly kind:
+    | 'text'
+    | 'number'
+    | 'boolean'
+    | 'date'
+    | 'select'
+    | 'multiselect'
+    | 'object'
+    | 'array'
+  readonly opts: Record<string, any>
+  /** Phantom type carrier. */
+  readonly _type?: T
+}
+
+export type Controls = Record<string, Control<any>>
+export type InferControls<P> = { [K in keyof P]: P[K] extends Control<infer T> ? T : never }
+
+interface SelectOpts<O, V> {
+  /** shown beside the control in the UI */
+  description?: string
+  label?: (o: O) => string
+  value?: (o: O) => V
+  default?: number | V | ((options: readonly O[]) => V)
+}
+
+export const c = {
+  text: (o: { default?: string; label?: string; description?: string } = {}): Control<string> => ({
+    kind: 'text',
+    opts: o,
+  }),
+  number: (
+    o: { default?: number; min?: number; max?: number; label?: string; description?: string } = {},
+  ): Control<number> => ({
+    kind: 'number',
+    opts: o,
+  }),
+  boolean: (
+    o: { default?: boolean; label?: string; description?: string } = {},
+  ): Control<boolean> => ({
+    kind: 'boolean',
+    opts: o,
+  }),
+  date: (o: { default?: string; label?: string; description?: string } = {}): Control<string> => ({
+    kind: 'date',
+    opts: o,
+  }),
+  select: <const O, V = O>(
+    options: readonly O[],
+    o: SelectOpts<O, V> = {},
+  ): Control<NoInfer<V>> => ({
+    kind: 'select',
+    opts: { ...o, options },
+  }),
+  multiselect: <const O, V = O>(
+    options: readonly O[],
+    o: SelectOpts<O, V> = {},
+  ): Control<NoInfer<V>[]> => ({
+    kind: 'multiselect',
+    opts: { ...o, options },
+  }),
+  object: <S extends Controls>(shape: S): Control<InferControls<S>> => ({
+    kind: 'object',
+    opts: { shape },
+  }),
+  array: <T>(
+    item: Control<T>,
+    o: { default?: T[]; min?: number; max?: number } = {},
+  ): Control<T[]> => ({ kind: 'array', opts: { ...o, item } }),
+}
+
+export class ControlError extends Error {}
+
+function optionValue(ctl: Control, option: unknown): unknown {
+  const fn = ctl.opts.value as ((o: unknown) => unknown) | undefined
+  return fn ? fn(option) : option
+}
+
+function same(a: unknown, b: unknown): boolean {
+  return a === b || JSON.stringify(a) === JSON.stringify(b)
+}
+
+/** Resolve one control to a value: given > default > first option / empty. */
+export function resolveControl(name: string, ctl: Control, given: unknown): unknown {
+  switch (ctl.kind) {
+    case 'select': {
+      const options = ctl.opts.options as unknown[]
+      if (options.length === 0) throw new ControlError(`No options available for "${name}"`)
+      const values = options.map((o) => optionValue(ctl, o))
+      if (given !== undefined) {
+        if (!values.some((v) => same(v, given))) {
+          throw new ControlError(`Value for "${name}" is not one of the available options`)
+        }
+        return given
+      }
+      const d = ctl.opts.default
+      if (
+        typeof d === 'number' &&
+        Number.isInteger(d) &&
+        d >= 0 &&
+        d < values.length &&
+        !(typeof values[0] === 'number')
+      )
+        return values[d]
+      if (typeof d === 'function') return d(options)
+      if (d !== undefined) return d
+      return values[0]
+    }
+    case 'multiselect': {
+      const options = ctl.opts.options as unknown[]
+      if (given !== undefined) return given
+      const d = ctl.opts.default
+      if (typeof d === 'function') return d(options)
+      return d ?? []
+    }
+    case 'object': {
+      const shape = ctl.opts.shape as Controls
+      const g = (given ?? {}) as Record<string, unknown>
+      return Object.fromEntries(
+        Object.entries(shape).map(([k, v]) => [k, resolveControl(k, v, g[k])]),
+      )
+    }
+    case 'array': {
+      const v = (given ?? ctl.opts.default ?? []) as unknown[]
+      const { min, max } = ctl.opts
+      if (min !== undefined && v.length < min)
+        throw new ControlError(`"${name}" needs at least ${min} items`)
+      if (max !== undefined && v.length > max)
+        throw new ControlError(`"${name}" allows at most ${max} items`)
+      return v.map((item) => resolveControl(name, ctl.opts.item, item))
+    }
+    case 'boolean':
+      return given ?? ctl.opts.default ?? false
+    case 'number':
+      return given ?? ctl.opts.default ?? 0
+    default:
+      return given ?? ctl.opts.default ?? ''
+  }
+}
+
+export function resolveControls(
+  controls: Controls,
+  given: Record<string, unknown> = {},
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(controls).map(([k, ctl]) => [k, resolveControl(k, ctl, given[k])]),
+  )
+}
+
+/** Serializable description for a UI to render an input step. */
+export function describeControls(controls: Controls) {
+  return Object.fromEntries(
+    Object.entries(controls).map(([k, ctl]) => {
+      if (ctl.kind === 'select' || ctl.kind === 'multiselect') {
+        const labelFn = ctl.opts.label as ((o: unknown) => string) | undefined
+        const options = (ctl.opts.options as unknown[]).map((o) => ({
+          label: labelFn ? labelFn(o) : String(optionValue(ctl, o)),
+          value: optionValue(ctl, o),
+        }))
+        return [k, { kind: ctl.kind, options }]
+      }
+      return [k, { kind: ctl.kind, default: ctl.opts.default }]
+    }),
+  )
+}

package/src/example.ts

@@ -0,0 +1,80 @@
+import { flattenForm, isBlob } from './runner/encode'
+import type { OpMeta } from './types'
+
+/** A complete request an API author (or the spec) defines for an operation. */
+export interface Example {
+  name: string
+  title?: string
+  summary?: string
+  source: 'spec' | 'generated' | 'project'
+  path?: Record<string, unknown>
+  /** Arrays send the same key repeatedly. */
+  query?: Record<string, unknown>
+  headers?: Record<string, string>
+  body?: unknown
+  /** Directory file-field paths are relative to; set by whoever loads the example. */
+  dir?: string
+}
+
+export type ExampleLoader = (op: OpMeta, name: string) => Promise<Example | undefined>
+export type FileReader = (path: string, dir?: string) => Promise<File>
+
+/** One line of an inline grid editor. Disabled rows stay visible but are not sent. */
+export interface Row {
+  key: string
+  value: string
+  enabled: boolean
+}
+
+const text = (v: unknown) =>
+  typeof v === 'string' ? v : typeof v === 'object' && v !== null ? JSON.stringify(v) : String(v)
+
+export function toRows(o: Record<string, unknown> = {}): Row[] {
+  return Object.entries(o).flatMap(([key, v]) =>
+    (Array.isArray(v) ? v : [v])
+      .filter((x) => x !== undefined && x !== null)
+      .map((x) => ({ key, value: text(x), enabled: true })),
+  )
+}
+
+export function fromRows(rows: Row[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const { key, value, enabled } of rows) {
+    if (!enabled || key === '') continue
+    const had = out[key]
+    out[key] = had === undefined ? value : [...(Array.isArray(had) ? had : [had]), value]
+  }
+  return out
+}
+
+/** Rows for a form/multipart body: nested values become bracket keys (`metadata[order]`). Files stay as values. */
+export function toFormRows(body: unknown): Row[] {
+  if (body === null || typeof body !== 'object') return []
+  return flattenForm(body).map(([key, value]) => ({ key, value, enabled: true }))
+}
+
+const SEGMENT = /[^[\]]+|\[\]/g
+
+function assign(node: any, segs: string[], value: unknown): any {
+  const [head, ...rest] = segs as [string, ...string[]]
+  if (head === '[]') {
+    const list: unknown[] = node ?? []
+    list.push(rest.length ? assign(undefined, rest, value) : value)
+    return list
+  }
+  const target = node ?? (/^\d+$/.test(head) ? [] : {})
+  const had = target[head]
+  if (rest.length) target[head] = assign(had, rest, value)
+  else target[head] = had === undefined ? value : [...([] as unknown[]).concat(had), value]
+  return target
+}
+
+/** Inverse of `toFormRows`; disabled rows are dropped and a repeated plain key becomes an array. */
+export function fromFormRows(rows: (Row & { file?: File })[]): Record<string, unknown> {
+  let out: Record<string, unknown> = {}
+  for (const { key, value, enabled, file } of rows) {
+    if (!enabled || key === '') continue
+    out = assign(out, key.match(SEGMENT) ?? [key], file && isBlob(file) ? file : value)
+  }
+  return out
+}

package/src/faker.ts

@@ -0,0 +1,80 @@
+// Locale-aware faker proxy. `@faker-js/faker` is a peer dependency of the user's project;
+// the runtime (CLI / UI) installs the concrete instance for the selected locale before a run.
+
+type FakerLike = Record<string, any>
+
+// Held on globalThis so the CLI's bundled copy of core and the project's own import share one instance.
+const KEY = '__specbookFaker'
+const store = globalThis as unknown as Record<string, FakerLike | undefined>
+
+export const faker: FakerLike = new Proxy({} as FakerLike, {
+  get(_t, key) {
+    const current = store[KEY]
+    if (!current) {
+      throw new Error(
+        'faker is not initialised. Install "@faker-js/faker" in your project; specbook sets it up before each run.',
+      )
+    }
+    return current[key as string]
+  },
+})
+
+export function setFaker(instance: FakerLike | undefined): void {
+  store[KEY] = instance
+}
+
+export interface FakerConfig {
+  /** locale name -> fallback chain of faker locale export names, e.g. { de: ['de', 'en', 'base'] } */
+  locales?: Record<string, string[]>
+  default?: string
+}
+
+interface FakerModule {
+  Faker: new (opts: { locale: unknown[] }) => FakerLike
+  [locale: string]: unknown
+}
+
+/** The locale exports a run needs, in fallback order: the chain for `locale`, then `base`. */
+export function fakerLocaleNames(config: FakerConfig = {}, locale?: string): string[] {
+  const name = locale ?? config.default ?? 'en'
+  return [...new Set([...(config.locales?.[name] ?? [name, 'en']), 'base'])]
+}
+
+/**
+ * The module `installFaker` needs. A bundled build offers each locale as `locales[name]()` so only
+ * the ones a run falls back through are fetched; a plain faker module already has them all.
+ */
+export async function prepareFaker(
+  mod: Record<string, any>,
+  config: FakerConfig = {},
+  locale?: string,
+): Promise<FakerModule> {
+  const locales = mod.locales as Record<string, () => Promise<unknown>> | undefined
+  if (!locales) return mod as FakerModule
+  const ready: Record<string, unknown> = { Faker: mod.Faker }
+  await Promise.all(
+    fakerLocaleNames(config, locale).map(async (n) => {
+      const load = locales[n]
+      if (load) ready[n] = await load()
+    }),
+  )
+  return ready as FakerModule
+}
+
+/** Build a Faker for `locale` from the (dynamically imported) module, install it, and optionally seed it. */
+export function installFaker(
+  mod: FakerModule,
+  config: FakerConfig = {},
+  opts: { locale?: string; seed?: number } = {},
+): FakerLike {
+  const name = opts.locale ?? config.default ?? 'en'
+  const locales = fakerLocaleNames(config, name).map((n) => {
+    const l = mod[n]
+    if (!l) throw new Error(`Unknown faker locale "${n}" (from "${name}")`)
+    return l
+  })
+  const instance = new mod.Faker({ locale: locales })
+  if (opts.seed !== undefined) instance.seed(opts.seed)
+  setFaker(instance)
+  return instance
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+export { assert, createAsserter, stripAnsi } from './assert'
+export * from './config'
+export * from './controls'
+export type { Example, ExampleLoader, FileReader, Row } from './example'
+export { fromFormRows, fromRows, toFormRows, toRows } from './example'
+export type { FakerConfig } from './faker'
+export { faker, fakerLocaleNames, installFaker, prepareFaker, setFaker } from './faker'
+export * from './mock'
+export * from './proxy/index'
+export * from './reporters/index'
+export { defineOperation, request } from './request'
+export * from './runner/index'
+export * from './secrets'
+export type { Sequence, SequenceMeta, StepCtx, StepNode } from './sequence'
+export { sequence } from './sequence'
+export type { SnippetInput, SnippetLang } from './snippets'
+export { snippetLangs, toSnippet } from './snippets'
+export { authFromSpec, type JsonAuthProfile, liveBaseUrl, type SpecAuth } from './spec-config'
+export {
+  collectPlaceholders,
+  deepMerge,
+  render,
+  renderString,
+  TemplateError,
+  usesFaker,
+} from './template'
+export * from './types'