@specbook/vite 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specbook/vite",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "The Specbook plugin for Vite: the registry, the docs UI hooks and the dev server credential proxy.",
   "keywords": [
     "specbook",
@@ -34,8 +34,8 @@
     }
   },
   "dependencies": {
-    "@specbook/codegen": "0.2.0",
-    "@specbook/core": "0.2.0",
+    "@specbook/codegen": "0.4.0",
+    "@specbook/core": "0.4.0",
     "fast-glob": "3.3.2",
     "marked": "^18.1.1"
   },

package/src/addresses.ts

@@ -0,0 +1,62 @@
+import {
+  baseUrlFor,
+  environmentNames,
+  environmentScope,
+  type OAuthSettings,
+  oauthFor,
+  type SpecbookConfig,
+} from '@specbook/core'
+import type { EnvironmentAddresses } from './proxy'
+
+export type AddressConfig = Omit<Partial<SpecbookConfig>, 'auth'> & {
+  auth?: Record<string, { oauth?: OAuthSettings }>
+}
+
+export const NO_ADDRESSES: EnvironmentAddresses = {
+  services: {},
+  tokenOrigins: {},
+  discoveryOrigins: {},
+}
+
+/**
+ * Where `env`'s calls may go, from the project's config and the environment's files alone: the page never
+ * says where to go. An environment the project does not have gets nothing (a 404 at the proxy).
+ * `tokenOriginOf` finds the token endpoint of an OpenID Connect discovery document.
+ */
+export async function addressesFor(
+  cfg: AddressConfig,
+  env: string,
+  files: { environments: string[]; vars(): Promise<Record<string, unknown>> },
+  tokenOriginOf: (discoveryUrl: string) => Promise<string | undefined>,
+): Promise<EnvironmentAddresses> {
+  const services = cfg.services ?? {}
+  const known = environmentNames({ services, environments: cfg.environments }, files.environments)
+  if (!known.includes(env)) return NO_ADDRESSES
+  const scope = environmentScope(cfg, env, await files.vars())
+  const out: EnvironmentAddresses = { services: {}, tokenOrigins: {}, discoveryOrigins: {} }
+  for (const [name, svc] of Object.entries(services)) {
+    // `mock` never leaves the page: a template's defaults are not its address
+    if (env === 'mock' && typeof svc.baseUrl === 'string') continue
+    try {
+      out.services[name] = baseUrlFor({ services }, name, env, scope)
+    } catch {
+      /* no address in this environment: a call gets a 404 saying so */
+    }
+  }
+  for (const [name, profile] of Object.entries(cfg.auth ?? {})) {
+    try {
+      if (!profile.oauth) continue
+      const oauth = oauthFor(profile.oauth, scope, name)
+      if ('tokenUrl' in oauth && oauth.tokenUrl)
+        out.tokenOrigins[name] = new URL(oauth.tokenUrl).origin
+      else if ('openIdConnectUrl' in oauth && oauth.openIdConnectUrl) {
+        out.discoveryOrigins[name] = new URL(oauth.openIdConnectUrl).origin
+        const token = await tokenOriginOf(oauth.openIdConnectUrl)
+        if (token) out.tokenOrigins[name] = token
+      }
+    } catch {
+      /* an unusable address is left out; a sign-in against it fails with a 404 */
+    }
+  }
+  return out
+}

package/src/definitions.ts

@@ -0,0 +1,26 @@
+// The shared definitions a service's schemas refer to, for a build that publishes only some of its operations.
+
+/** Names of the shared definitions a JSON text refers to (`specbook://<svc>/defs#/$defs/Name` or `#/$defs/Name`). */
+export function definitionRefs(text: string): string[] {
+  const names: string[] = []
+  for (const m of text.matchAll(/"\$ref":"(?:specbook:\/\/[^"#]*)?#\/\$defs\/([^"]+)"/g))
+    names.push((m[1] as string).replace(/~1/g, '/').replace(/~0/g, '~'))
+  return names
+}
+
+/** A service's definitions cut down to the ones `roots` refer to, directly or through each other. */
+export function pruneDefinitions(
+  defs: { $id?: string; $defs?: Record<string, unknown> },
+  roots: Set<string> | undefined,
+) {
+  const all = defs.$defs ?? {}
+  const keep = new Set<string>()
+  const queue = [...(roots ?? [])]
+  while (queue.length) {
+    const name = queue.pop() as string
+    if (keep.has(name) || !(name in all)) continue
+    keep.add(name)
+    queue.push(...definitionRefs(JSON.stringify(all[name])))
+  }
+  return { ...defs, $defs: Object.fromEntries(Object.entries(all).filter(([k]) => keep.has(k))) }
+}

package/src/examples.ts

@@ -40,6 +40,8 @@ export async function scanExamples(
   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]
+    // only operations the build knows (a minimal build lists just those it publishes)
+    if (!operations.has(`${svc}/${id}`)) continue
     add(`${svc}/${id}`, {
       name: file.replace(NAME, ''),
       abs,

package/src/index.ts

@@ -3,14 +3,18 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { createRequire } from 'node:module'
 import { basename, dirname, join, relative, resolve, sep } from 'node:path'
+import { environmentNames } from '@specbook/core'
 import fg from 'fast-glob'
 import type { Plugin, ViteDevServer } from 'vite'
+import { type AddressConfig, addressesFor, NO_ADDRESSES } from './addresses'
+import { definitionRefs, pruneDefinitions } from './definitions'
 import { createDiscovery } from './discovery'
 import { scanDocs } from './docs'
 import {
   ensureEnvironmentsDir,
   isEnvName,
   isVarName,
+  listEnvironmentFiles,
   readAllVars,
   readEnvironment,
   secretsFileFor,
@@ -20,12 +24,13 @@ import {
 } from './environments'
 import { scanExamples } from './examples'
 import { requestsDirFor, safeProjectPath, scanProject } from './files'
-import { handleProxy, type ProxyConfig } from './proxy'
+import { type EnvironmentAddresses, handleProxy, type ProxyConfig } from './proxy'
+import { scanRequests } from './requests'
 import { parseSequenceMeta, scanSequences } from './sequences'
 
 export * from './environments'
-export { safeProjectPath, scanProject } from './files'
-export type { ProxyConfig, ProxyDeps } from './proxy'
+export { requestsDirFor, safeProjectPath, scanProject } from './files'
+export type { EnvironmentAddresses, ProxyConfig, ProxyDeps } from './proxy'
 export { handleProxy } from './proxy'
 
 export interface SpecbookPluginOptions {
@@ -33,6 +38,12 @@ export interface SpecbookPluginOptions {
   projectRoot: string
   /** Generated code directory relative to the project root. Default `.generated`. */
   outDir?: string
+  /**
+   * Publish only these operations (`service/OperationId`): the ones a project's requests and flows use. The catalog,
+   * schemas, examples, docs and definitions of every other operation are left out, so the build neither carries nor
+   * reveals the rest of the API.
+   */
+  operations?: Set<string>
 }
 
 const VIRTUAL = 'virtual:specbook/registry'
@@ -43,8 +54,8 @@ const VIRTUAL_FAKER = 'virtual:specbook/faker'
 const RESOLVED_FAKER = `\0${VIRTUAL_FAKER}`
 const VIRTUAL_FAKER_LOCALE = 'virtual:specbook/faker-locale/'
 const RESOLVED_FAKER_LOCALE = `\0${VIRTUAL_FAKER_LOCALE}`
-const VIRTUAL_MANIFESTS = 'virtual:specbook/manifests'
-const RESOLVED_MANIFESTS = `\0${VIRTUAL_MANIFESTS}`
+const VIRTUAL_MANIFEST = 'virtual:specbook/manifest/'
+const RESOLVED_MANIFEST = `\0${VIRTUAL_MANIFEST}`
 const VIRTUAL_OPERATIONS = 'virtual:specbook/operations'
 const RESOLVED_OPERATIONS = `\0${VIRTUAL_OPERATIONS}`
 const VIRTUAL_DOC = 'virtual:specbook/doc/'
@@ -132,11 +143,17 @@ async function collectTypes(root: string, outDir: string) {
 export function specbook(options: SpecbookPluginOptions): Plugin {
   const root = resolve(options.projectRoot)
   const outDir = options.outDir ?? '.generated'
+  const only = options.operations
+  /** Whether an operation is part of this build. */
+  const keep = (service: string, op: string) => !only || only.has(`${service}/${op}`)
+  /** per service, the shared definitions its kept schemas refer to (a minimal build trims the rest) */
+  const neededDefs = new Map<string, Set<string>>()
   let server: ViteDevServer | undefined
   let isBuild = false
   let docHtml: string[] = []
   /** build only: parts of the registry that live in their own chunks, and the data files served as assets */
-  let manifestsCode = 'export default {}'
+  /** build: the manifest of each service, one module each */
+  let manifestCode = new Map<string, string>()
   let operationsCode = 'export const operations = {}'
   /** `service/Operation` -> the generated files that make up its data bundle */
   let bundlePlan = new Map<
@@ -167,10 +184,24 @@ export function specbook(options: SpecbookPluginOptions): Plugin {
       const parsed = JSON.parse(await readFile(m, 'utf8'))
       manifests[parsed.service] = parsed
     }
+    if (only) {
+      for (const [svc, m] of Object.entries(manifests)) {
+        const mm = m as { operations: { id: string; tags?: string[] }[]; tags?: string[] }
+        mm.operations = mm.operations.filter((o) => keep(svc, o.id))
+        if (mm.operations.length === 0) delete manifests[svc]
+        else mm.tags = [...new Set(mm.operations.flatMap((o) => o.tags ?? []))]
+      }
+    }
+    const inScope = (svc: string, op: string) => svc in manifests && keep(svc, op)
     // response examples: <svc>/examples/<Op>/<status|default>.response.json, keyed `svc/Op.<status|default>`
-    const examples = await fg('*/examples/*/*.response.json', {
-      cwd: join(root, outDir),
-      absolute: true,
+    const examples = (
+      await fg('*/examples/*/*.response.json', {
+        cwd: join(root, outDir),
+        absolute: true,
+      })
+    ).filter((abs) => {
+      const rel = relative(join(root, outDir), abs).split(sep)
+      return inScope(rel[0] as string, rel[2] as string)
     })
     // dev: cache-busted /@fs imports (files on disk are the source of truth); build: statically analysable
     const imp = (abs: string) => {
@@ -201,29 +232,32 @@ export function specbook(options: SpecbookPluginOptions): Plugin {
           `  ${JSON.stringify(`${mm.service}/${o.id}`)}: ${imp(join(root, outDir, mm.service, 'operations', `${o.id}.ts`))}`,
       )
     })
-    const schemaFiles = await fg('*/schemas/*.request.schema.json', {
-      cwd: join(root, outDir),
-      absolute: true,
-    })
-    const responseFiles = await fg('*/schemas/*.responses.schema.json', {
-      cwd: join(root, outDir),
-      absolute: true,
-    })
+    const opOf = (abs: string, suffix: RegExp) => {
+      const rel = relative(join(root, outDir), abs).split(sep)
+      return [rel[0] as string, (rel[2] as string).replace(suffix, '')] as const
+    }
+    const schemaFiles = (
+      await fg('*/schemas/*.request.schema.json', { cwd: join(root, outDir), absolute: true })
+    ).filter((abs) => inScope(...opOf(abs, /\.request\.schema\.json$/)))
+    const responseFiles = (
+      await fg('*/schemas/*.responses.schema.json', { cwd: join(root, outDir), absolute: true })
+    ).filter((abs) => inScope(...opOf(abs, /\.responses\.schema\.json$/)))
     const responseEntries = responseFiles.map((abs) => {
       const rel = relative(join(root, outDir), abs).split(sep)
       const op = (rel[2] as string).replace(/\.responses\.schema\.json$/, '')
       return `  ${JSON.stringify(`${rel[0]}/${op}`)}: ${imp(abs)}`
     })
-    const defFiles = await fg('*/schemas/definitions.schema.json', {
-      cwd: join(root, outDir),
-      absolute: true,
-    })
+    const defFiles = (
+      await fg('*/schemas/definitions.schema.json', { cwd: join(root, outDir), absolute: true })
+    ).filter((abs) => (relative(join(root, outDir), abs).split(sep)[0] as string) in manifests)
     const schemaEntries = schemaFiles.map((abs) => {
       const rel = relative(join(root, outDir), abs).split(sep)
       const op = (rel[2] as string).replace(/\.request\.schema\.json$/, '')
       return `  ${JSON.stringify(`${rel[0]}/${op}`)}: ${imp(abs)}`
     })
-    const docFiles = await fg('*/docs/*.json', { cwd: join(root, outDir), absolute: true })
+    const docFiles = (
+      await fg('*/docs/*.json', { cwd: join(root, outDir), absolute: true })
+    ).filter((abs) => inScope(...opOf(abs, /\.json$/)))
     const operationDocEntries = docFiles.map((abs) => {
       const rel = relative(join(root, outDir), abs).split(sep)
       return `  ${JSON.stringify(`${rel[0]}/${(rel[2] as string).replace(/\.json$/, '')}`)}: ${imp(abs)}`
@@ -240,11 +274,16 @@ export function specbook(options: SpecbookPluginOptions): Plugin {
     )
     // Sequence titles come from each file's literal header, so listing them imports no sequence.
     const sequenceScan = await scanSequences(root, files.sequences)
+    // which operation each request file is for, read from its text, so an embed imports only the one it opens
+    const requestScan = await scanRequests(root, files.requests, new Set(Object.keys(manifests)))
     for (const f of files.sequences) {
       const src = await readFile(join(root, f), 'utf8').catch(() => '')
       seqHeaders.set(join(root, f), JSON.stringify(parseSequenceMeta(src)))
     }
     const scanned = await scanExamples(root, outDir, known)
+    const keepExampleKey = (key: string) => !only || only.has(key)
+    for (const key of Object.keys(scanned.examples))
+      if (!keepExampleKey(key)) delete scanned.examples[key]
     const url = (abs: string) =>
       isBuild
         ? `() => import(${JSON.stringify(`${abs}?url`)}).then((m) => m.default)`
@@ -273,7 +312,10 @@ export function specbook(options: SpecbookPluginOptions): Plugin {
     const assetEntries = Object.entries(scanned.assets).map(
       ([key, abs]) => `  ${JSON.stringify(key)}: ${url(abs)}`,
     )
-    const pages = await scanDocs(root)
+    // a minimal build keeps the notes on its requests and flows, and drops the pages of operations it does not publish
+    const pages = (await scanDocs(root)).filter(
+      (p) => !only || !p.operation || only.has(p.operation),
+    )
     docHtml = pages.map((p) => p.html)
     const docEntries = pages.map(
       (p, i) =>
@@ -288,7 +330,11 @@ export function specbook(options: SpecbookPluginOptions): Plugin {
     if (isBuild) {
       // The registry stays small: manifests and the operation modules sit in their own chunks, and the
       // generated JSON (schemas, examples, docs, definitions) is served as plain files under data/.
-      manifestsCode = `export default ${JSON.stringify(slim(manifests))}`
+      // one chunk per service, so a page that opens one operation fetches one service's list
+      const slimmed = slim(manifests)
+      manifestCode = new Map(
+        Object.entries(slimmed).map(([svc, m]) => [svc, `export default ${JSON.stringify(m)}`]),
+      )
       operationsCode = `export const operations = {\n${operationEntries.join(',\n')}\n}`
       const gen = join(root, outDir)
       bundlePlan = new Map()
@@ -348,8 +394,8 @@ export function specbook(options: SpecbookPluginOptions): Plugin {
             projectLoads.push(`  ${JSON.stringify(`${key}/${e.name}`)}: ${imp(e.abs)}`)
       }
       const services = Object.keys(manifests)
-      return `import manifests from ${JSON.stringify(VIRTUAL_MANIFESTS)}
-export const mode = "static"
+      return `export const mode = "static"
+export const minimal = ${JSON.stringify(!!only)}
 export const project = ${JSON.stringify({ root, outDir, requestsDir })}
 // where the data files are: dist/data, whether this chunk is in dist/ or dist/assets/
 const dataBase = import.meta.url.replace(/(assets\\/)?[^/]*$/, '') + 'data/'
@@ -363,8 +409,13 @@ const bundle = (key) => {
 }
 const part = (pick) =>
   new Proxy({}, { get: (_, key) => (typeof key === 'string' && key.includes('/') ? () => bundle(key).then((b) => ({ default: pick(b) })) : undefined) })
-export { manifests }
+export const manifests = {}
+const manifestLoaders = {${services.map((svc) => `\n  ${JSON.stringify(svc)}: () => import(${JSON.stringify(`${VIRTUAL_MANIFEST}${svc}`)})`).join(',')}\n}
+export const loadManifests = (names = Object.keys(manifestLoaders)) =>
+  Promise.all(names.map((svc) => manifests[svc] ? undefined : manifestLoaders[svc]?.().then((m) => { manifests[svc] = m.default }))).then(() => undefined)
 export const requests = [${files.requests.map(entry).join(',\n')}]
+export const requestMeta = ${JSON.stringify(requestScan.meta)}
+export const unresolvedRequests = ${JSON.stringify(requestScan.unresolved)}
 export const sequences = [${files.sequences.map(entry).join(',\n')}]
 export const sequenceMeta = ${JSON.stringify(sequenceScan.meta)}
 export const unresolvedSequences = ${JSON.stringify(sequenceScan.unresolved)}
@@ -412,9 +463,13 @@ export const loadConfig = ${cfg ? imp(cfg) : '() => Promise.resolve({ default: {
 `
     }
     return `export const mode = ${JSON.stringify(isBuild ? 'static' : 'dev')}
+export const minimal = ${JSON.stringify(!!only)}
 export const project = ${JSON.stringify({ root, outDir, requestsDir })}
 export const manifests = ${JSON.stringify(slim(manifests))}
+export const loadManifests = () => Promise.resolve()
 export const requests = [${files.requests.map(entry).join(',\n')}]
+export const requestMeta = ${JSON.stringify(requestScan.meta)}
+export const unresolvedRequests = ${JSON.stringify(requestScan.unresolved)}
 export const sequences = [${files.sequences.map(entry).join(',\n')}]
 export const sequenceMeta = ${JSON.stringify(sequenceScan.meta)}
 export const unresolvedSequences = ${JSON.stringify(sequenceScan.unresolved)}
@@ -434,38 +489,29 @@ export const loadConfig = ${cfg ? imp(cfg) : '() => Promise.resolve({ default: {
 `
   }
 
-  async function getProxyConfig(): Promise<ProxyConfig> {
+  async function loadProjectConfig(): Promise<AddressConfig | undefined> {
     const cfgFile = findConfig(root)
-    if (!server || !cfgFile) return { services: {}, secretNames: {} }
-    const mod = await server.ssrLoadModule(cfgFile)
-    const cfg = (mod.default ?? {}) as {
-      services?: Record<string, { baseUrl?: Record<string, string> }>
-      secrets?: Record<string, { env?: string }>
-      auth?: Record<string, { oauth?: { tokenUrl?: string; openIdConnectUrl?: string } }>
-    }
-    const tokenOrigins: Record<string, string> = {}
-    const discoveryOrigins: Record<string, string> = {}
-    for (const [name, profile] of Object.entries(cfg.auth ?? {})) {
-      try {
-        const { tokenUrl, openIdConnectUrl } = profile.oauth ?? {}
-        if (tokenUrl) tokenOrigins[name] = new URL(tokenUrl).origin
-        else if (openIdConnectUrl) {
-          discoveryOrigins[name] = new URL(openIdConnectUrl).origin
-          const token = await tokenOriginOf(openIdConnectUrl)
-          if (token) tokenOrigins[name] = token
-        }
-      } catch {
-        /* an unparsable URL is left out; a sign-in against it fails with a 404 */
-      }
-    }
-    return {
-      services: Object.fromEntries(
-        Object.entries(cfg.services ?? {}).map(([k, v]) => [k, { baseUrl: v.baseUrl ?? {} }]),
-      ),
-      secretNames: cfg.secrets ?? {},
-      tokenOrigins,
-      discoveryOrigins,
-    }
+    if (!server || !cfgFile) return undefined
+    return ((await server.ssrLoadModule(cfgFile)).default ?? {}) as AddressConfig
+  }
+
+  async function getProxyConfig(): Promise<ProxyConfig> {
+    const cfg = await loadProjectConfig()
+    if (!cfg) return { secretNames: {}, resolve: async () => NO_ADDRESSES }
+    // addresses are worked out here, per environment, from config and files: the page never says where to go
+    const resolve = async (env: string): Promise<EnvironmentAddresses> =>
+      isEnvName(env)
+        ? addressesFor(
+            cfg,
+            env,
+            {
+              environments: await listEnvironmentFiles(root),
+              vars: async () => (await readEnvironment(root, env)).vars,
+            },
+            tokenOriginOf,
+          )
+        : NO_ADDRESSES
+    return { secretNames: cfg.secrets ?? {}, resolve }
   }
 
   return {
@@ -496,6 +542,13 @@ export const loadConfig = ${cfg ? imp(cfg) : '() => Promise.resolve({ default: {
             await Promise.all(statuses.map(async (n) => [n, await read(p.mock[n] as string)])),
           )
         }
+        if (only) {
+          const svc = key.slice(0, key.indexOf('/'))
+          const set = neededDefs.get(svc) ?? new Set<string>()
+          for (const name of definitionRefs(JSON.stringify([out.schema, out.responses])))
+            set.add(name)
+          neededDefs.set(svc, set)
+        }
         this.emitFile({
           type: 'asset',
           fileName: `data/${key}.json`,
@@ -506,7 +559,11 @@ export const loadConfig = ${cfg ? imp(cfg) : '() => Promise.resolve({ default: {
         this.emitFile({
           type: 'asset',
           fileName: `data/${svc}/_definitions.json`,
-          source: await readFile(abs),
+          source: only
+            ? JSON.stringify(
+                pruneDefinitions(JSON.parse(await readFile(abs, 'utf8')), neededDefs.get(svc)),
+              )
+            : await readFile(abs),
         })
     },
     config(_, env) {
@@ -518,7 +575,8 @@ export const loadConfig = ${cfg ? imp(cfg) : '() => Promise.resolve({ default: {
               // manifests are their own chunk (preloaded with the app, so no extra round trip), and
               // operation modules are grouped by tag instead of one chunk per operation
               manualChunks(id: string) {
-                if (id === RESOLVED_MANIFESTS) return 'manifests'
+                if (id.startsWith(RESOLVED_MANIFEST))
+                  return `manifest-${id.slice(RESOLVED_MANIFEST.length)}`
                 return operationChunks.get(id)
               },
             },
@@ -530,7 +588,7 @@ export const loadConfig = ${cfg ? imp(cfg) : '() => Promise.resolve({ default: {
       if (id === VIRTUAL) return RESOLVED
       if (id === VIRTUAL_TYPES) return RESOLVED_TYPES
       if (id === VIRTUAL_FAKER) return RESOLVED_FAKER
-      if (id === VIRTUAL_MANIFESTS) return RESOLVED_MANIFESTS
+      if (id.startsWith(VIRTUAL_MANIFEST)) return `\0${id}`
       if (id === VIRTUAL_OPERATIONS) return RESOLVED_OPERATIONS
       if (id.startsWith(VIRTUAL_FAKER_LOCALE)) return `\0${id}`
       if (id.startsWith(VIRTUAL_DOC)) return `\0${id}`
@@ -538,7 +596,8 @@ export const loadConfig = ${cfg ? imp(cfg) : '() => Promise.resolve({ default: {
     },
     async load(id) {
       if (id === RESOLVED) return registryCode()
-      if (id === RESOLVED_MANIFESTS) return manifestsCode
+      if (id.startsWith(RESOLVED_MANIFEST))
+        return manifestCode.get(id.slice(RESOLVED_MANIFEST.length)) ?? 'export default {}'
       if (id === RESOLVED_OPERATIONS) return operationsCode
       if (id === RESOLVED_FAKER || id.startsWith(RESOLVED_FAKER_LOCALE)) {
         // Let Vite resolve the package from the project (ESM entry, not the CJS one `require.resolve` finds).
@@ -588,6 +647,8 @@ ${names.map((n) => `  ${JSON.stringify(n)}: () => import(${JSON.stringify(`${VIR
       const relevant = (file: string) => {
         const rel = relative(root, file)
         if (rel.startsWith('..') || /node_modules/.test(rel)) return false
+        // not `.specbook/environments/*.env`: the page reads an environment's variables live, and a reload
+        // when its file is first written would blank the page under whoever is editing a variable
         return /\.(req|seq)\.ts$|\.example\.json$|\.md$/.test(rel) || rel.startsWith(outDir)
       }
       // one reload per burst of changes: a save also arrives here from the watcher
@@ -672,6 +733,40 @@ ${names.map((n) => `  ${JSON.stringify(n)}: () => import(${JSON.stringify(`${VIR
               )
             return json(res, 200, { env, vars: values.vars, secrets, warnings })
           }
+          if (url.pathname === '/__specbook/environment' && req.method === 'POST') {
+            // a new environment is a copy of another one's own variables (never its secrets)
+            const origin = req.headers.origin
+            if (origin && new URL(origin).host !== req.headers.host)
+              return json(res, 403, { error: 'cross-origin request refused' })
+            const { name, from } = JSON.parse(await readBody(req)) as {
+              name?: string
+              from?: string
+            }
+            if (!isEnvName(name) || name === 'mock' || !isEnvName(from))
+              return json(res, 400, { error: 'bad environment name' })
+            const conf = await loadProjectConfig()
+            const known = environmentNames(
+              { services: conf?.services ?? {}, environments: conf?.environments },
+              await listEnvironmentFiles(root),
+            )
+            if (known.includes(name)) return json(res, 409, { error: `"${name}" already exists` })
+            if (!known.includes(from))
+              return json(res, 400, { error: `unknown environment "${from}"` })
+            const own = {
+              ...(
+                conf?.environments as Record<string, { vars?: Record<string, unknown> }> | undefined
+              )?.[from]?.vars,
+              ...(await readEnvironment(root, from)).vars,
+            }
+            await ensureEnvironmentsDir(root)
+            const file = varsFile(root, name)
+            await writeFile(file, `# variables for ${name}, copied from ${from}\n`)
+            for (const [k, v] of Object.entries(own)) {
+              if (v === null || typeof v === 'object' || !isVarName(k)) continue
+              await writeEnvKey(file, k, String(v))
+            }
+            return json(res, 200, { ok: true, name })
+          }
           if (
             (url.pathname === '/__specbook/secret' || url.pathname === '/__specbook/var') &&
             req.method === 'POST'

package/src/proxy.ts

@@ -1,19 +1,26 @@
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { handleProxy as proxy } from '@specbook/core'
 
-export interface ProxyConfig {
-  services: Record<string, { baseUrl: Record<string, string | undefined> }>
-  secretNames: Record<string, { env?: string }>
+/** Where one environment's calls may go, worked out on the server from the project's config and files. */
+export interface EnvironmentAddresses {
+  /** each service's base URL in this environment */
+  services: Record<string, string | undefined>
   /**
-   * Origin of each OAuth profile's token endpoint, read from the project's own config. A sign-in
-   * exchanges its code through `<mount>/<env>/auth:<profile>/…`; the page chooses the path, never the host.
+   * Origin of each OAuth profile's token endpoint. A sign-in exchanges its code through
+   * `<mount>/<env>/auth:<profile>/…`; the page chooses the path, never the host.
    */
-  tokenOrigins?: Record<string, string>
+  tokenOrigins: Record<string, string>
   /**
    * Origin of each OpenID Connect profile's discovery document, addressed as
    * `<mount>/<env>/discovery:<profile>/…` (the token endpoint may be on another host).
    */
-  discoveryOrigins?: Record<string, string>
+  discoveryOrigins: Record<string, string>
+}
+
+export interface ProxyConfig {
+  secretNames: Record<string, { env?: string }>
+  /** The addresses for `env`; empty for an environment the project does not have. */
+  resolve(env: string): Promise<EnvironmentAddresses>
 }
 
 /** The reserved service name a sign-in's token exchange is addressed to. */
@@ -69,6 +76,15 @@ export async function handleProxy(
   if (!url.startsWith(`${MOUNT}/`)) return false
 
   const config = await deps.getConfig()
+  const addressesByEnv = new Map<string, Promise<EnvironmentAddresses>>()
+  const addressesFor = (env: string) => {
+    let a = addressesByEnv.get(env)
+    if (!a) {
+      a = config.resolve(env)
+      addressesByEnv.set(env, a)
+    }
+    return a
+  }
   const secretsByEnv = new Map<string, Record<string, string>>()
   const method = req.method ?? 'GET'
   const headers = new Headers()
@@ -84,12 +100,13 @@ export async function handleProxy(
   const response = await proxy(request, {
     mount: MOUNT,
     policy: {
-      upstream: (env, service) => {
+      upstream: async (env, service) => {
+        const a = await addressesFor(env)
         if (service.startsWith(AUTH_SERVICE_PREFIX))
-          return config.tokenOrigins?.[decode(service.slice(AUTH_SERVICE_PREFIX.length))]
+          return a.tokenOrigins[decode(service.slice(AUTH_SERVICE_PREFIX.length))]
         if (service.startsWith(DISCOVERY_SERVICE_PREFIX))
-          return config.discoveryOrigins?.[decode(service.slice(DISCOVERY_SERVICE_PREFIX.length))]
-        return config.services[service]?.baseUrl[env]
+          return a.discoveryOrigins[decode(service.slice(DISCOVERY_SERVICE_PREFIX.length))]
+        return a.services[service]
       },
       // a developer's own machine: their local services are the point
       allowPrivateHosts: true,

package/src/requests.ts

@@ -0,0 +1,58 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/**
+ * Which operation a request file is for, read from its text without importing it:
+ * `import { GetPetById } from '#api/petstore'` and `GetPetById.request({...})` make `petstore/GetPetById`. The panel of an
+ * embed opens one request, and with this it imports that file instead of every request in the project.
+ *
+ * `services` are the project's service names; an import counts when the last segment of its address is one of them, so any
+ * import prefix works. Anything the text does not settle (no call, two different operations, a computed one) is undefined,
+ * and the file is then imported when requests are listed.
+ */
+export function parseRequestTarget(src: string, services: ReadonlySet<string>): string | undefined {
+  const local = new Map<string, string>()
+  for (const m of src.matchAll(/import\s*(?:type\s*)?\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g)) {
+    const service = (m[2] as string).split('/').pop() as string
+    if (!services.has(service) || /^import\s*type/.test(m[0])) continue
+    for (const part of (m[1] as string).split(',')) {
+      const spec = part.trim()
+      if (!spec || spec.startsWith('type ')) continue
+      const [imported, as] = spec.split(/\s+as\s+/)
+      local.set((as ?? imported) as string, `${service}/${imported}`)
+    }
+  }
+  const used = new Set<string>()
+  for (const m of src.matchAll(/\b([A-Za-z_$][\w$]*)\s*\.\s*request\s*\(/g)) {
+    const key = local.get(m[1] as string)
+    if (key) used.add(key)
+  }
+  return used.size === 1 ? [...used][0] : undefined
+}
+
+export interface RequestScan {
+  /** project-relative request file → `service/Operation` */
+  meta: Record<string, string>
+  /** files the text does not settle; the UI imports these */
+  unresolved: string[]
+}
+
+export async function scanRequests(
+  root: string,
+  files: string[],
+  services: ReadonlySet<string>,
+): Promise<RequestScan> {
+  const meta: Record<string, string> = {}
+  const unresolved: string[] = []
+  await Promise.all(
+    files.map(async (file) => {
+      const key = parseRequestTarget(
+        await readFile(join(root, file), 'utf8').catch(() => ''),
+        services,
+      )
+      if (key) meta[file] = key
+      else unresolved.push(file)
+    }),
+  )
+  return { meta, unresolved: unresolved.sort() }
+}