@nifrajs/cli 2.10.0 → 2.12.0

package/src/contract-proof.ts

@@ -0,0 +1,194 @@
+import { existsSync, realpathSync } from "node:fs"
+import { resolve, sep } from "node:path"
+import type { AssuranceFinding, AssuranceReport, AssuredRoute } from "@nifrajs/core/assurance"
+import type {
+  AssuredCapabilityRoute,
+  CapabilityAssuranceReport,
+  CapabilityFinding,
+} from "@nifrajs/core/capabilities"
+import { diffRouteSnapshots, type RouteChange, type RoutesDiff } from "@nifrajs/core/diff"
+import type { CheckResult } from "./check.ts"
+import { DEFAULT_SNAPSHOT_FILE, parseSnapshotFile, snapshotBackend } from "./diff-tool.ts"
+import { collectProjectVerification } from "./verification.ts"
+
+const routeKey = (method: string, path: string): string => `${method.toUpperCase()}\n${path}`
+
+export interface ContractProofRoute {
+  readonly method: string
+  readonly path: string
+  readonly changes: readonly RouteChange[]
+  readonly assurance?: {
+    readonly route?: AssuredRoute
+    readonly findings: readonly AssuranceFinding[]
+  }
+  readonly capability?: {
+    readonly route?: AssuredCapabilityRoute
+    readonly findings: readonly CapabilityFinding[]
+  }
+}
+
+export interface ContractProofVerification {
+  readonly assuranceConfigPresent: boolean
+  readonly configError?: string
+  readonly assurance?: {
+    readonly ok: boolean
+    readonly routeCount: number
+    readonly findings: readonly AssuranceFinding[]
+  }
+  readonly capability?: {
+    readonly ok: boolean
+    readonly routeCount: number
+    readonly findings: readonly CapabilityFinding[]
+  }
+  readonly check?: CheckResult
+}
+
+export interface ContractProofReport {
+  readonly baseline: string
+  readonly hasBreaking: boolean
+  readonly changes: readonly RouteChange[]
+  readonly routes: readonly ContractProofRoute[]
+  readonly verification: ContractProofVerification
+}
+
+export interface ContractProofOptions {
+  /** Baseline path relative to the project directory. Defaults to api-snapshot.json. */
+  readonly baselinePath?: string
+  /** Run the lazy typed-contract check only when explicitly requested. */
+  readonly check?: boolean
+  readonly signal?: AbortSignal
+}
+
+function safeBaselinePath(cwd: string, baselinePath: string): string {
+  const root = resolve(cwd)
+  const target = resolve(root, baselinePath)
+  if (target !== root && !target.startsWith(`${root}${sep}`)) {
+    throw new Error("contract proof baseline must stay inside the project directory")
+  }
+  return target
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function changedRoutes(
+  diff: RoutesDiff,
+  assurance: AssuranceReport | undefined,
+  capability: CapabilityAssuranceReport | undefined,
+): readonly ContractProofRoute[] {
+  const changes = new Map<string, RouteChange[]>()
+  for (const change of diff.changes) {
+    const key = routeKey(change.method, change.path)
+    const current = changes.get(key)
+    if (current === undefined) changes.set(key, [change])
+    else current.push(change)
+  }
+
+  const assured = new Map(
+    (assurance?.routes ?? []).map((route) => [routeKey(route.method, route.path), route]),
+  )
+  const assuranceFindings = new Map<string, AssuranceFinding[]>()
+  for (const finding of assurance?.findings ?? []) {
+    const key = routeKey(finding.method, finding.path)
+    const current = assuranceFindings.get(key)
+    if (current === undefined) assuranceFindings.set(key, [finding])
+    else current.push(finding)
+  }
+
+  const capable = new Map(
+    (capability?.routes ?? []).map((route) => [routeKey(route.method, route.path), route]),
+  )
+  const capabilityFindings = new Map<string, CapabilityFinding[]>()
+  for (const finding of capability?.findings ?? []) {
+    const key = routeKey(finding.method, finding.path)
+    const current = capabilityFindings.get(key)
+    if (current === undefined) capabilityFindings.set(key, [finding])
+    else current.push(finding)
+  }
+
+  return Object.freeze(
+    [...changes].map(([key, routeChanges]) => {
+      const first = routeChanges[0]
+      if (first === undefined) throw new Error("contract proof: missing route change")
+      const assuredRoute = assured.get(key)
+      const capableRoute = capable.get(key)
+      return {
+        method: first.method,
+        path: first.path,
+        changes: Object.freeze([...routeChanges]),
+        ...(assurance === undefined
+          ? {}
+          : {
+              assurance: {
+                ...(assuredRoute === undefined ? {} : { route: assuredRoute }),
+                findings: Object.freeze([...(assuranceFindings.get(key) ?? [])]),
+              },
+            }),
+        ...(capability === undefined
+          ? {}
+          : {
+              capability: {
+                ...(capableRoute === undefined ? {} : { route: capableRoute }),
+                findings: Object.freeze([...(capabilityFindings.get(key) ?? [])]),
+              },
+            }),
+      }
+    }),
+  )
+}
+
+/** Compose route diff, route assurance, capability evidence, and an optional check result. */
+export async function collectContractProof(
+  cwd: string,
+  options: ContractProofOptions = {},
+): Promise<ContractProofReport> {
+  const baselinePath = options.baselinePath ?? DEFAULT_SNAPSHOT_FILE
+  const resolvedBaseline = safeBaselinePath(cwd, baselinePath)
+  if (!existsSync(resolvedBaseline)) {
+    throw new Error(`contract proof baseline not found: ${resolvedBaseline}`)
+  }
+  const realRoot = realpathSync(resolve(cwd))
+  const realBaseline = realpathSync(resolvedBaseline)
+  if (realBaseline !== realRoot && !realBaseline.startsWith(`${realRoot}${sep}`)) {
+    throw new Error("contract proof baseline must stay inside the project directory")
+  }
+  const baseline = parseSnapshotFile(await Bun.file(resolvedBaseline).text(), baselinePath)
+  const current = await snapshotBackend(cwd)
+  const diff = diffRouteSnapshots(baseline.routes, current)
+  const verification = await collectProjectVerification(cwd, {
+    ...(options.signal === undefined ? {} : { signal: options.signal }),
+  })
+  const proof: ContractProofVerification = {
+    assuranceConfigPresent: verification.assuranceConfigPresent,
+    ...(verification.configError === undefined
+      ? {}
+      : { configError: errorMessage(verification.configError) }),
+    ...(verification.routeAssurance === undefined
+      ? {}
+      : {
+          assurance: {
+            ok: verification.routeAssurance.ok,
+            routeCount: verification.routeAssurance.routes.length,
+            findings: verification.routeAssurance.findings,
+          },
+        }),
+    ...(verification.capability === undefined
+      ? {}
+      : {
+          capability: {
+            ok: verification.capability.report.ok,
+            routeCount: verification.capability.report.routes.length,
+            findings: verification.capability.report.findings,
+          },
+        }),
+    ...(options.check === true ? { check: await verification.check() } : {}),
+  }
+  return Object.freeze({
+    baseline: baselinePath,
+    hasBreaking: diff.hasBreaking,
+    changes: diff.changes,
+    routes: changedRoutes(diff, verification.routeAssurance, verification.capability?.report),
+    verification: proof,
+  })
+}

package/src/contracts.ts

@@ -0,0 +1,157 @@
+import { existsSync } from "node:fs"
+import { resolve } from "node:path"
+import { type ReflectedRoute, reflectRoutes } from "@nifrajs/core/reflection"
+
+export interface ContractDigest {
+  readonly request: string
+  readonly response: string
+}
+
+export interface ContractsLock {
+  readonly version: 1
+  readonly routes: Readonly<Record<string, ContractDigest>>
+}
+
+export const DEFAULT_CONTRACTS_LOCK = "contracts.lock.json"
+const DIGEST = /^[a-f0-9]{64}$/
+
+function recordOf(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? Object.fromEntries(Object.entries(value))
+    : undefined
+}
+
+function canonical(value: unknown, key?: string): unknown {
+  if (["description", "title", "default", "example", "examples"].includes(key ?? ""))
+    return undefined
+  if (Array.isArray(value)) return value.map((item) => canonical(item))
+  const record = recordOf(value)
+  if (record === undefined) return value
+  const out: Record<string, unknown> = {}
+  for (const name of Object.keys(record).sort()) {
+    const item = canonical(record[name], name)
+    if (item !== undefined) out[name] = item
+  }
+  return out
+}
+
+async function sha256(value: string): Promise<string> {
+  const bytes = new TextEncoder().encode(value)
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes))
+  return [...digest].map((item) => item.toString(16).padStart(2, "0")).join("")
+}
+
+function schemaValue(route: ReflectedRoute, side: "request" | "response"): unknown {
+  const schema = route.schema
+  if (schema === undefined) return {}
+  if (side === "request") {
+    return {
+      body: schema.body?.jsonSchema ?? schema.body?.fields ?? null,
+      query: schema.query?.jsonSchema ?? schema.query?.fields ?? null,
+      params: schema.params?.jsonSchema ?? schema.params?.fields ?? null,
+    }
+  }
+  return {
+    response: schema.response?.jsonSchema ?? schema.response?.fields ?? null,
+    sse: schema.sse?.jsonSchema ?? schema.sse?.fields ?? null,
+    errors: Object.fromEntries(
+      Object.entries(schema.errors ?? {}).map(([status, value]) => [
+        status,
+        value.jsonSchema ?? value.fields ?? null,
+      ]),
+    ),
+  }
+}
+
+export async function digestRoute(route: ReflectedRoute): Promise<ContractDigest> {
+  const request = JSON.stringify(canonical(schemaValue(route, "request")))
+  const response = JSON.stringify(canonical(schemaValue(route, "response")))
+  return { request: await sha256(request), response: await sha256(response) }
+}
+
+export async function buildContractsLock(source: unknown): Promise<ContractsLock> {
+  const routes = Object.fromEntries(
+    await Promise.all(
+      reflectRoutes(source).map(
+        async (route) => [`${route.method} ${route.path}`, await digestRoute(route)] as const,
+      ),
+    ),
+  )
+  return {
+    version: 1,
+    routes: Object.fromEntries(Object.entries(routes).sort(([a], [b]) => a.localeCompare(b))),
+  }
+}
+
+async function loadBackend(cwd: string): Promise<unknown> {
+  const backendPath = resolve(cwd, "backend.ts")
+  if (!existsSync(backendPath)) throw new Error(`[nifra] no backend.ts in ${cwd}`)
+  const loadedValue: unknown = await import(backendPath)
+  const loaded = recordOf(loadedValue)
+  if (loaded?.backend === undefined)
+    throw new Error(`[nifra] ${backendPath} does not export backend`)
+  return loaded.backend
+}
+
+export async function snapshotContracts(
+  cwd: string,
+  out = DEFAULT_CONTRACTS_LOCK,
+): Promise<ContractsLock> {
+  const lock = await buildContractsLock(await loadBackend(cwd))
+  await Bun.write(resolve(cwd, out), `${JSON.stringify(lock, null, 2)}\n`)
+  return lock
+}
+
+export function parseContractsLock(value: unknown): ContractsLock {
+  const record = recordOf(value)
+  if (record === undefined) throw new TypeError("contracts lock must be an object")
+  const routesValue = record.routes
+  const routesRecord = recordOf(routesValue)
+  if (record.version !== 1 || routesRecord === undefined)
+    throw new TypeError("contracts lock must have version 1 and routes")
+  const routes: Record<string, ContractDigest> = {}
+  for (const [key, raw] of Object.entries(routesRecord)) {
+    const item = recordOf(raw)
+    const request = item?.request
+    const response = item?.response
+    if (
+      request === undefined ||
+      typeof request !== "string" ||
+      response === undefined ||
+      typeof response !== "string" ||
+      !DIGEST.test(request) ||
+      !DIGEST.test(response)
+    )
+      throw new TypeError(`invalid contract ${key}`)
+    routes[key] = { request, response }
+  }
+  return { version: 1, routes }
+}
+
+export async function checkContractsLock(
+  cwd: string,
+  file = DEFAULT_CONTRACTS_LOCK,
+): Promise<{ present: boolean; diagnostics: Array<{ route?: string; message: string }> }> {
+  const path = resolve(cwd, file)
+  if (!existsSync(path)) return { present: false, diagnostics: [] }
+  const parsed = parseContractsLock(JSON.parse(await Bun.file(path).text()))
+  const current = await buildContractsLock(await loadBackend(cwd))
+  const diagnostics: Array<{ route?: string; message: string }> = []
+  const keys = new Set([...Object.keys(parsed.routes), ...Object.keys(current.routes)])
+  for (const key of [...keys].sort()) {
+    const before = parsed.routes[key]
+    const after = current.routes[key]
+    if (
+      before === undefined ||
+      after === undefined ||
+      before.request !== after.request ||
+      before.response !== after.response
+    ) {
+      diagnostics.push({
+        route: key,
+        message: `contract changed for ${key}; if intentional run \`nifra contracts snapshot\` and include the lock update in the same change.`,
+      })
+    }
+  }
+  return { present: true, diagnostics }
+}

package/src/dev-bun-config.ts

@@ -7,10 +7,15 @@
  * would ship to the browser WHOLE (body, DB handles, secrets) instead of as the RPC stub the
  * production client build emits, and a `*.server` module would ship instead of being emptied.
  *
+ * The same channel is the only way an app's OWN `clientPlugins` (SFC compilers and the like) can reach
+ * that bundler: the CLI holds them as plugin OBJECTS, and bunfig accepts only module paths - so the
+ * generated module re-imports the app's config and composes them in.
+ *
  * So the CLI generates, under `.nifra/dev-bun/`:
  *   - `boundary-plugin.ts` - default-exports one plugin composing the SAME `serverFnStubPlugin` +
- *     `serverOnlyEmptyPlugin` the production build uses (imported from `@nifrajs/web/build`, resolved
- *     from the app - identical stubs, not a re-implementation);
+ *     `serverOnlyEmptyPlugin` + CSS Modules transform the production build uses (imported from
+ *     `@nifrajs/web`, resolved from the app - identical transforms, not re-implementations), plus the
+ *     app's own `clientPlugins`;
  *   - `bunfig.toml` - the app's ENTIRE bunfig carried over verbatim (jsx, loaders, defines, install
  *     settings - dropping any of them would give dev a different Bun than the app configured), with
  *     `[serve.static] plugins` merged to put the boundary plugin first and path-bearing entries
@@ -34,7 +39,7 @@
  */
 import { timingSafeEqual } from "node:crypto"
 import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs"
-import { resolve } from "node:path"
+import { relative, resolve } from "node:path"
 
 /** TOML string literal: basic (double-quoted) form with the two escapes it needs. */
 function tomlString(value: string): string {
@@ -132,22 +137,56 @@ export function renderDevBunfig(
   )
 }
 
-/** The generated plugin module: compose the two production boundary plugins into one default
- * export. Import specifiers are bare so they resolve from the APP's install (the module lives
- * under the app's `.nifra/`), keeping dev stubs byte-identical to production's. */
-export function renderBoundaryPluginModule(): string {
-  return `// Generated by \`nifra dev --bun\` - do not edit. Regenerated on every dev start.
-import { serverFnStubPlugin, serverOnlyEmptyPlugin } from "@nifrajs/web/build"
+/** A TS/JS import specifier for `target` as seen from `fromDir`, always `./`-prefixed and posix-slashed
+ * so it reads as a FILE path to the module loader rather than a package name. */
+function relativeSpecifier(fromDir: string, target: string): string {
+  const rel = relative(fromDir, target).replaceAll("\\", "/")
+  return rel.startsWith(".") ? rel : `./${rel}`
+}
 
+/**
+ * The generated plugin module: compose the production boundary plugins, the production CSS Modules
+ * transform, and the APP's own `clientPlugins` into one default export.
+ *
+ * The `@nifrajs/*` specifiers are bare so they resolve from the APP's install (the module lives under
+ * the app's `.nifra/`), keeping dev transforms byte-identical to production's.
+ *
+ * `configPath` is the app's `nifra.config.ts` (or `framework.ts`). Importing it here is the only way an
+ * app's `clientPlugins` can reach Bun's dev-server bundler at all: that bundler takes plugins as module
+ * PATHS via bunfig, never as the plugin objects the CLI already holds in memory. Without this an app
+ * whose transforms live in `clientPlugins` had no working Bun dev loop - its client would be bundled
+ * with the transform silently missing. `setup` is async because `clientPlugins` may be a thunk.
+ */
+export function renderBoundaryPluginModule(configPath?: string, pluginDir?: string): string {
+  const appImport =
+    configPath !== undefined && pluginDir !== undefined
+      ? `import * as appConfig from ${tomlString(relativeSpecifier(pluginDir, configPath))}\n`
+      : ""
+  const appSetup =
+    appImport === ""
+      ? ""
+      : `    // The app's OWN client transforms (SFC compilers etc.). \`clientPlugins\` may be a thunk.
+    const field = appConfig.clientPlugins
+    const appPlugins = (typeof field === "function" ? await field() : field) ?? []
+    for (const p of appPlugins) await p.setup(build)
+`
+  return `// Generated by \`nifra dev\` (Bun pipeline) - do not edit. Regenerated on every dev start.
+import { serverFnStubPlugin, serverOnlyEmptyPlugin } from "@nifrajs/web/build"
+import { cssModulesBunPlugin } from "@nifrajs/web/plugins/css-modules"
+${appImport}
 const fn = serverFnStubPlugin()
 const serverOnly = serverOnlyEmptyPlugin()
+const cssModules = cssModulesBunPlugin("dom")
 
 export default {
   name: "nifra-dev-boundary",
-  setup(build) {
+  async setup(build) {
+    // Boundary first: an app plugin must never get to transform a module that the boundary is about to
+    // empty or stub, or the transform decides what ships instead of the boundary.
     serverOnly.setup(build)
     fn.setup(build)
-  },
+    cssModules.setup(build)
+${appSetup}  },
 }
 `
 }
@@ -161,12 +200,16 @@ export interface BunDevConfig {
 const TOKEN_FILE = "launch-token"
 
 /** Write the generated config for an app; returns the bunfig path to re-exec with and the fresh
- * launch token to pass in the child's environment. */
-export async function writeBunDevConfig(appRoot: string): Promise<BunDevConfig> {
+ * launch token to pass in the child's environment. `configPath` (the app's `nifra.config.ts` /
+ * `framework.ts`) is what lets the app's own `clientPlugins` reach Bun's dev-server bundler. */
+export async function writeBunDevConfig(
+  appRoot: string,
+  configPath?: string,
+): Promise<BunDevConfig> {
   const dir = resolve(appRoot, ".nifra", "dev-bun")
   mkdirSync(dir, { recursive: true })
   const pluginPath = resolve(dir, "boundary-plugin.ts")
-  writeFileSync(pluginPath, renderBoundaryPluginModule())
+  writeFileSync(pluginPath, renderBoundaryPluginModule(configPath, dir))
   const userToml = await Bun.file(resolve(appRoot, "bunfig.toml"))
     .text()
     .catch(() => undefined)

package/src/diagnostics.ts

@@ -0,0 +1,32 @@
+/** Stable, machine-actionable diagnostics shared by CLI gates and MCP renderers. */
+
+export type Severity = "error" | "warn" | "info"
+
+export interface DiagnosticFix {
+  readonly recipe: string
+  readonly command?: string
+}
+
+export interface Diagnostic {
+  /** Stable forever. Never renumber or reuse. */
+  readonly code: string
+  readonly severity: Severity
+  readonly message: string
+  readonly file?: string
+  readonly line?: number
+  /** Short evidence strings that help an agent act without exposing payloads. */
+  readonly evidence?: readonly string[]
+  readonly fix?: DiagnosticFix
+  /** Command that proves the fix worked. */
+  readonly verify?: string
+}
+
+export const diagnostic = (value: Diagnostic): Diagnostic => Object.freeze(value)
+
+export function severityFails(severity: Severity, strict = false): boolean {
+  return severity === "error" || (strict && severity === "warn")
+}
+
+export function normalizeSeverity(value: "error" | "warning" | "warn" | "info"): Severity {
+  return value === "warning" ? "warn" : value
+}

package/src/diff-tool.ts

@@ -82,7 +82,7 @@ export function formatDiff(diff: RoutesDiff): string {
 }
 
 /** Import `backend.ts` from `cwd` and snapshot its routes. */
-async function snapshotBackend(cwd: string): Promise<readonly RouteSnapshot[]> {
+export async function snapshotBackend(cwd: string): Promise<readonly RouteSnapshot[]> {
   const backendPath = resolve(cwd, "backend.ts")
   if (!existsSync(backendPath)) {
     throw new Error(

package/src/docs-search.ts

@@ -17,6 +17,13 @@ export interface DocSection {
   readonly body: string
 }
 
+export interface PreparedDocSection extends DocSection {
+  readonly headingTokens: ReadonlySet<string>
+  readonly bodyLower: string
+}
+
+const sectionCache = new Map<string, readonly PreparedDocSection[]>()
+
 /** Split the generated doc into its `##` sections (the `# title` intro becomes "Overview"). */
 export function splitSections(markdown: string): DocSection[] {
   const out: DocSection[] = []
@@ -40,6 +47,23 @@ export function splitSections(markdown: string): DocSection[] {
   return out
 }
 
+function prepareSection(section: DocSection): PreparedDocSection {
+  return {
+    ...section,
+    headingTokens: new Set(tokenize(section.heading)),
+    bodyLower: section.body.toLowerCase(),
+  }
+}
+
+/** Return the immutable-build section parse and derived search fields from the process cache. */
+export function getCachedDocSections(markdown: string): readonly PreparedDocSection[] {
+  const cached = sectionCache.get(markdown)
+  if (cached !== undefined) return cached
+  const prepared = splitSections(markdown).map(prepareSection)
+  sectionCache.set(markdown, prepared)
+  return prepared
+}
+
 export interface ScoredSection extends DocSection {
   readonly score: number
 }
@@ -48,7 +72,7 @@ export interface ScoredSection extends DocSection {
  * (headings are curated names for exactly these lookups); body occurrences cap per term so one
  * spammy section can't drown a precisely-titled one. */
 export function searchSections(
-  sections: readonly DocSection[],
+  sections: readonly (DocSection | PreparedDocSection)[],
   query: string,
   limit: number,
 ): ScoredSection[] {
@@ -56,14 +80,14 @@ export function searchSections(
   if (terms.length === 0) return []
   const scored: ScoredSection[] = []
   for (const section of sections) {
-    const headingTokens = new Set(tokenize(section.heading))
-    const bodyLower = section.body.toLowerCase()
+    const prepared =
+      "headingTokens" in section && "bodyLower" in section ? section : prepareSection(section)
     let score = 0
     for (const term of terms) {
-      if (tokenSetHas(headingTokens, term)) score += 8
-      score += countBodyHits(bodyLower, term, 5)
+      if (tokenSetHas(prepared.headingTokens, term)) score += 8
+      score += countBodyHits(prepared.bodyLower, term, 5)
     }
-    if (score > 0) scored.push({ ...section, score })
+    if (score > 0) scored.push({ heading: section.heading, body: section.body, score })
   }
   return scored.sort((a, b) => b.score - a.score).slice(0, limit)
 }
@@ -78,7 +102,7 @@ export function renderDocsResult(
   query: string | undefined,
   limit: number,
 ): string {
-  const sections = splitSections(markdown)
+  const sections = getCachedDocSections(markdown)
   if (query === undefined || query.trim() === "") {
     const index = sections.map((s) => `- ${s.heading}`).join("\n")
     return `# nifra docs - section index (pass \`query\` to fetch matching sections)\n\n${index}`
@@ -100,12 +124,18 @@ export function renderDocsResult(
 
 /** Load the bundled corpus. Resolves relative to this module so it works from `src/` (repo dev)
  * and `dist/` (published) alike - `docs/llms-full.txt` sits at the package root next to both. */
-export async function loadDocsCorpus(): Promise<string | undefined> {
-  const url = new URL("../docs/llms-full.txt", import.meta.url)
-  try {
-    const text = await Bun.file(url).text()
-    return text.length > 0 ? text : undefined
-  } catch {
-    return undefined
-  }
+let docsCorpusPromise: Promise<string | undefined> | undefined
+
+/** The published corpus is immutable, so one read and one parsed-section cache are sufficient. */
+export function loadDocsCorpus(): Promise<string | undefined> {
+  docsCorpusPromise ??= (async () => {
+    const url = new URL("../docs/llms-full.txt", import.meta.url)
+    try {
+      const text = await Bun.file(url).text()
+      return text.length > 0 ? text : undefined
+    } catch {
+      return undefined
+    }
+  })()
+  return docsCorpusPromise
 }