@specbook/vite 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@specbook/vite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "The Specbook plugin for Vite: the registry, the docs UI hooks and the dev server credential proxy.",
+  "keywords": [
+    "specbook",
+    "vite",
+    "vite-plugin",
+    "openapi",
+    "api-explorer"
+  ],
+  "license": "FSL-1.1-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/vite"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@specbook/codegen": "0.2.0",
+    "@specbook/core": "0.2.0",
+    "fast-glob": "3.3.2",
+    "marked": "^18.1.1"
+  },
+  "peerDependencies": {
+    "vite": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "tsup": "8.5.1",
+    "typescript": "7.0.2",
+    "vite": "8.3.4"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!**/*.test.*"
+  ],
+  "scripts": {
+    "build": "tsup && tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }

package/src/discovery.ts

@@ -0,0 +1,60 @@
+import { parseDiscovery } from '@specbook/core'
+
+const FETCH_TIMEOUT_MS = 5_000
+
+/**
+ * Learns, on the server, where an OpenID Connect provider's token endpoint is. The page needs the proxy to
+ * forward its code exchange there, and the proxy only forwards to origins it was told about by the
+ * project's own config; a discovery document is the config's pointer to that origin. Successes are kept
+ * for the life of the dev server; a failure is not retried for a short while, so a provider that is down
+ * costs one slow request, not one per call.
+ */
+export function createDiscovery(
+  opts: {
+    fetch?: typeof fetch
+    retryAfterMs?: number
+    now?: () => number
+    warn?: (message: string) => void
+  } = {},
+) {
+  const f = opts.fetch ?? fetch
+  const now = opts.now ?? Date.now
+  const retryAfter = opts.retryAfterMs ?? 30_000
+  const found = new Map<string, string>()
+  const failedAt = new Map<string, number>()
+  const inFlight = new Map<string, Promise<string | undefined>>()
+
+  async function look(url: string): Promise<string | undefined> {
+    try {
+      const res = await f(url, {
+        headers: { accept: 'application/json' },
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      })
+      if (!res.ok) throw new Error(`answered ${res.status}`)
+      const origin = new URL(parseDiscovery(await res.json()).tokenUrl).origin
+      found.set(url, origin)
+      failedAt.delete(url)
+      return origin
+    } catch (e) {
+      failedAt.set(url, now())
+      opts.warn?.(
+        `Could not read the OpenID Connect discovery document at ${url} (${e instanceof Error ? e.message : String(e)}). Sign in is unavailable until it can; pasting a token still works.`,
+      )
+      return undefined
+    }
+  }
+
+  /** The origin of the provider's token endpoint, or `undefined` when discovery has failed. */
+  return function tokenOrigin(url: string): Promise<string | undefined> {
+    const known = found.get(url)
+    if (known) return Promise.resolve(known)
+    const failed = failedAt.get(url)
+    if (failed !== undefined && now() - failed < retryAfter) return Promise.resolve(undefined)
+    let pending = inFlight.get(url)
+    if (!pending) {
+      pending = look(url).finally(() => inFlight.delete(url))
+      inFlight.set(url, pending)
+    }
+    return pending
+  }
+}

package/src/docs.ts

@@ -0,0 +1,102 @@
+import { readFile } from 'node:fs/promises'
+import { relative, sep } from 'node:path'
+import fg from 'fast-glob'
+import { marked } from 'marked'
+
+export interface DocPage {
+  file: string
+  /** `service/OperationId` */
+  operation?: string
+  sequence?: string
+  /** project-relative `.seq.ts` that sits beside a `<name>.seq.md` */
+  sequenceFile?: string
+  /** project-relative `.req.ts` that sits beside a `<name>.req.md` */
+  requestFile?: string
+  /** frontmatter `replace: true`: the page stands in for the spec's own description */
+  replace?: boolean
+  title?: string
+  html: string
+}
+
+export function frontmatter(src: string): { meta: Record<string, string>; body: string } {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(src)
+  if (!m) return { meta: {}, body: src }
+  const meta: Record<string, string> = {}
+  for (const line of (m[1] as string).split(/\r?\n/)) {
+    const i = line.indexOf(':')
+    if (i > 0)
+      meta[line.slice(0, i).trim()] = line
+        .slice(i + 1)
+        .trim()
+        .replace(/^["']|["']$/g, '')
+  }
+  return { meta, body: src.slice(m[0].length) }
+}
+
+const OP_FOLDER = /(?:^|\/)(?:requests|apis)\/([^/]+)\/([^/]+)\/(?:readme|index)\.md$/i
+/** `requests/<service>/docs/<Operation>.md`: one folder per service, instead of one per operation. */
+const OP_FLAT = /(?:^|\/)(?:requests|apis)\/([^/]+)\/docs\/([^/]+)\.md$/i
+/** Names that are about the folder, not an operation. */
+const NOT_AN_OPERATION = /^(readme|index)$/i
+
+/**
+ * Where a page belongs, from its place on disk: `<name>.seq.md` beside `<name>.seq.ts`,
+ * `<name>.req.md` beside `<name>.req.ts`, `requests/<service>/<Operation>/README.md`, or the flat
+ * `requests/<service>/docs/<Operation>.md`.
+ */
+export function colocated(
+  file: string,
+): Pick<DocPage, 'operation' | 'sequenceFile' | 'requestFile'> | undefined {
+  if (/\.seq\.md$/.test(file)) return { sequenceFile: file.replace(/\.md$/, '.ts') }
+  if (/\.req\.md$/.test(file)) return { requestFile: file.replace(/\.md$/, '.ts') }
+  // `docs` is the flat folder, not an operation named "docs"
+  const folder = OP_FOLDER.exec(file)
+  if (folder && folder[2] !== 'docs') return { operation: `${folder[1]}/${folder[2]}` }
+  const flat = OP_FLAT.exec(file)
+  if (flat && !NOT_AN_OPERATION.test(flat[2] as string))
+    return { operation: `${flat[1]}/${flat[2]}` }
+  return undefined
+}
+
+/**
+ * Markdown pages that belong to something: by place on disk (see `colocated`), or by naming an
+ * `operation:` / `sequence:` (or `page:`) in their frontmatter.
+ */
+export async function scanDocs(root: string): Promise<DocPage[]> {
+  const files = await fg('**/*.md', {
+    cwd: root,
+    absolute: true,
+    ignore: ['**/node_modules/**', '**/.generated/**', '**/dist/**', '**/.git/**'],
+  })
+  const pages: DocPage[] = []
+  const claimed = new Map<string, string>()
+  for (const abs of files.sort()) {
+    const { meta, body } = frontmatter(await readFile(abs, 'utf8'))
+    const file = relative(root, abs).split(sep).join('/')
+    const near = colocated(file)
+    if (!near && !meta.operation && !meta.sequence && !meta.page) continue
+    const operation = meta.operation ?? near?.operation
+    if (operation) {
+      const first = claimed.get(operation)
+      if (first) {
+        // two pages for one operation: the first (by path) is used, and the other would be silently ignored
+        console.warn(
+          `[specbook] ${file} documents ${operation}, which ${first} already does; ignored`,
+        )
+        continue
+      }
+      claimed.set(operation, file)
+    }
+    pages.push({
+      file,
+      operation,
+      sequence: meta.sequence,
+      sequenceFile: near?.sequenceFile,
+      requestFile: near?.requestFile,
+      replace: meta.replace === 'true' || undefined,
+      title: meta.title ?? meta.page,
+      html: marked.parse(body, { async: false }) as string,
+    })
+  }
+  return pages
+}

package/src/environments.ts

@@ -0,0 +1,114 @@
+import { existsSync } from 'node:fs'
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { parseDotenv } from '@specbook/core'
+
+/**
+ * Per-environment values live in `.specbook/environments/`:
+ *   staging.env          non-secret variables, committed
+ *   staging.secrets.env  secrets, gitignored by the folder's own .gitignore
+ * `.specbook/secrets.local.env` stays as the shared, all-environments fallback for secrets.
+ */
+export const ENV_NAME = /^[A-Za-z0-9_-]+$/
+const VAR_NAME = /^[A-Za-z_][\w.-]*$/
+
+export const environmentsDir = (root: string) => join(root, '.specbook', 'environments')
+export const varsFile = (root: string, env: string) => join(environmentsDir(root), `${env}.env`)
+export const secretsFileFor = (root: string, env: string) =>
+  join(environmentsDir(root), `${env}.secrets.env`)
+export const sharedSecretsFile = (root: string) => join(root, '.specbook', 'secrets.local.env')
+
+export const isEnvName = (s: unknown): s is string => typeof s === 'string' && ENV_NAME.test(s)
+export const isVarName = (s: unknown): s is string => typeof s === 'string' && VAR_NAME.test(s)
+
+async function readParsed(file: string): Promise<Record<string, string>> {
+  return existsSync(file) ? parseDotenv(await readFile(file, 'utf8')) : {}
+}
+
+export interface EnvironmentValues {
+  /** non-secret variables from `<env>.env` */
+  vars: Record<string, string>
+  /** secrets from `<env>.secrets.env` */
+  secrets: Record<string, string>
+  /** secrets shared by every environment (`secrets.local.env`) */
+  shared: Record<string, string>
+}
+
+export async function readEnvironment(root: string, env: string): Promise<EnvironmentValues> {
+  if (!isEnvName(env))
+    return { vars: {}, secrets: {}, shared: await readParsed(sharedSecretsFile(root)) }
+  const [vars, secrets, shared] = await Promise.all([
+    readParsed(varsFile(root, env)),
+    readParsed(secretsFileFor(root, env)),
+    readParsed(sharedSecretsFile(root)),
+  ])
+  return { vars, secrets, shared }
+}
+
+/** Names of environments that have a file, from `<name>.env` and `<name>.secrets.env`. */
+export async function listEnvironmentFiles(root: string): Promise<string[]> {
+  const dir = environmentsDir(root)
+  if (!existsSync(dir)) return []
+  const names = new Set<string>()
+  for (const f of await readdir(dir)) {
+    const m = /^([A-Za-z0-9_-]+)(\.secrets)?\.env$/.exec(f)
+    if (m) names.add(m[1] as string)
+  }
+  return [...names].sort()
+}
+
+/** The committed variable files, for the registry and static builds. */
+export async function readAllVars(root: string): Promise<Record<string, Record<string, string>>> {
+  const out: Record<string, Record<string, string>> = {}
+  const dir = environmentsDir(root)
+  if (!existsSync(dir)) return out
+  for (const f of await readdir(dir)) {
+    const m = /^([A-Za-z0-9_-]+)\.env$/.exec(f)
+    if (m) out[m[1] as string] = parseDotenv(await readFile(join(dir, f), 'utf8'))
+  }
+  return out
+}
+
+const quote = (v: string) => {
+  if (/[\r\n]/.test(v)) throw new Error('values must be a single line')
+  if (!/[\s#"'\\]/.test(v)) return v
+  if (!v.includes('"')) return `"${v}"`
+  if (!v.includes("'")) return `'${v}'`
+  return v
+}
+
+/** Insert, replace or (with `undefined`) delete one key, leaving every other line untouched. */
+export function setDotenvKey(text: string, key: string, value: string | undefined): string {
+  const lines = text === '' ? [] : text.split('\n')
+  const at = lines.findIndex((l) => new RegExp(`^\\s*(?:export\\s+)?${escapeRe(key)}\\s*=`).test(l))
+  if (value === undefined) {
+    if (at >= 0) lines.splice(at, 1)
+  } else if (at >= 0) lines[at] = `${key}=${quote(value)}`
+  else {
+    if (lines.length && lines[lines.length - 1] === '') lines.pop()
+    lines.push(`${key}=${quote(value)}`)
+  }
+  const out = lines.join('\n')
+  return out === '' || out.endsWith('\n') ? out : `${out}\n`
+}
+
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+/** Creates `environments/` with its own .gitignore, so secrets files can never be committed by accident. */
+export async function ensureEnvironmentsDir(root: string): Promise<string> {
+  const dir = environmentsDir(root)
+  await mkdir(dir, { recursive: true })
+  const ignore = join(dir, '.gitignore')
+  if (!existsSync(ignore))
+    await writeFile(ignore, '# secrets never leave this machine\n*.secrets.env\n')
+  return dir
+}
+
+export async function writeEnvKey(
+  file: string,
+  key: string,
+  value: string | undefined,
+): Promise<void> {
+  const current = existsSync(file) ? await readFile(file, 'utf8') : ''
+  await writeFile(file, setDotenvKey(current, key, value))
+}

package/src/examples.ts

@@ -0,0 +1,77 @@
+import { relative, sep } from 'node:path'
+import fg from 'fast-glob'
+
+export interface ExampleEntry {
+  name: string
+  abs: string
+  source: 'generated' | 'project'
+  /** Key of the folder the example lives in; file-field paths are relative to it. */
+  dir: string
+}
+
+export interface ExampleScan {
+  /** `service/OperationId` -> examples, project files overriding generated ones of the same name */
+  examples: Record<string, ExampleEntry[]>
+  /** `<dir>/<file>` -> absolute path, for the non-JSON files an example may reference */
+  assets: Record<string, string>
+}
+
+const IGNORE = ['**/node_modules/**', '**/.generated/**', '**/dist/**', '**/.git/**']
+const NAME = /\.example\.json$/
+
+export async function scanExamples(
+  root: string,
+  outDir: string,
+  operations: Set<string>,
+): Promise<ExampleScan> {
+  const examples: Record<string, ExampleEntry[]> = {}
+  const assets: Record<string, string> = {}
+  const dirs = new Map<string, string>()
+
+  const add = (key: string, entry: ExampleEntry) => {
+    examples[key] ??= []
+    const list = examples[key] as ExampleEntry[]
+    const at = list.findIndex((e) => e.name === entry.name)
+    if (at >= 0) list[at] = entry
+    else list.push(entry)
+    dirs.set(entry.dir, entry.abs.slice(0, entry.abs.lastIndexOf(sep)))
+  }
+
+  const gen = `${root}/${outDir}`
+  for (const abs of await fg('*/examples/*/*.example.json', { cwd: gen, absolute: true })) {
+    const [svc, , id, file] = relative(gen, abs).split(sep) as [string, string, string, string]
+    add(`${svc}/${id}`, {
+      name: file.replace(NAME, ''),
+      abs,
+      source: 'generated',
+      dir: `${svc}/${id}@generated`,
+    })
+  }
+  for (const abs of await fg('**/*.example.json', { cwd: root, absolute: true, ignore: IGNORE })) {
+    const parts = relative(root, abs).split(sep)
+    const file = parts.pop() as string
+    const id = parts.pop()
+    const svc = parts.pop()
+    const key = `${svc}/${id}`
+    if (!svc || !id || !operations.has(key)) continue
+    add(key, {
+      name: file.replace(NAME, ''),
+      abs,
+      source: 'project',
+      dir: `${svc}/${id}@project`,
+    })
+  }
+
+  for (const [dir, abs] of dirs) {
+    for (const f of await fg('*', { cwd: abs, absolute: false, ignore: ['*.json'] })) {
+      assets[`${dir}/${f}`] = `${abs}/${f}`
+    }
+  }
+  for (const list of Object.values(examples))
+    list.sort((a, b) => order(a) - order(b) || a.name.localeCompare(b.name))
+  return { examples, assets }
+}
+
+/** Spec and project examples first, then the generated default and dynamic ones. */
+const order = (e: ExampleEntry) =>
+  e.source === 'project' ? 0 : e.name === 'default' ? 2 : e.name === 'dynamic' ? 3 : 1

package/src/files.ts

@@ -0,0 +1,59 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join, relative, resolve, sep } from 'node:path'
+import fg from 'fast-glob'
+
+const IGNORE = ['**/node_modules/**', '**/.generated/**', '**/dist/**', '**/.git/**']
+
+export interface ProjectFiles {
+  requests: string[]
+  sequences: string[]
+  /** every .ts/.json file the editor may need for typings (relative to root) */
+  sources: string[]
+}
+
+export async function scanProject(root: string): Promise<ProjectFiles> {
+  const rel = (e: string[]) => e.map((f) => relative(root, f).split(sep).join('/')).sort()
+  const [requests, sequences, sources] = await Promise.all([
+    fg('**/*.req.ts', { cwd: root, absolute: true, ignore: IGNORE }),
+    fg('**/*.seq.ts', { cwd: root, absolute: true, ignore: IGNORE }),
+    fg(['**/*.ts', '**/*.json'], {
+      cwd: root,
+      absolute: true,
+      ignore: [
+        ...IGNORE,
+        '**/package.json',
+        '**/tsconfig*.json',
+        '**/openapi/**',
+        '**/*.d.ts',
+        '**/*.example.json',
+      ],
+    }),
+  ])
+  return { requests: rel(requests), sequences: rel(sequences), sources: rel(sources) }
+}
+
+/** Sources, plus the sample files an example may upload. */
+const WRITABLE = /\.(ts|json|txt|csv|png|jpe?g|gif|webp|pdf|zip|bin)$/
+const BLOCKED = /(^|\/)(node_modules|\.generated|\.git|dist)(\/|$)|secrets\.local\.env/
+
+/** Resolve a project-relative path for reading/writing, or undefined when not allowed. */
+export function safeProjectPath(root: string, relPath: string): string | undefined {
+  if (typeof relPath !== 'string' || relPath.includes('\0')) return undefined
+  const abs = resolve(root, relPath)
+  const rel = relative(root, abs).split(sep).join('/')
+  if (rel.startsWith('..') || rel === '' || resolve(rel) === rel) return undefined
+  if (BLOCKED.test(rel) || !WRITABLE.test(rel)) return undefined
+  return abs
+}
+
+export async function readDotenvFile(path: string): Promise<string> {
+  return existsSync(path) ? readFile(path, 'utf8') : ''
+}
+
+export const secretsFile = (root: string) => join(root, '.specbook', 'secrets.local.env')
+
+/** Where new example files go: `requests/`, or `apis/` for projects that already use that folder name. */
+export function requestsDirFor(root: string): 'requests' | 'apis' {
+  return existsSync(join(root, 'apis')) && !existsSync(join(root, 'requests')) ? 'apis' : 'requests'
+}