@nifrajs/cli 2.11.0 → 2.12.0

package/src/examples.ts

@@ -23,6 +23,29 @@ export interface ScoredExample extends Example {
   readonly score: number
 }
 
+interface PreparedExample {
+  readonly example: Example
+  readonly labelTokens: ReadonlySet<string>
+  readonly codeLower: string
+}
+
+const preparedExamplesCache = new WeakMap<readonly Example[], readonly PreparedExample[]>()
+const prepareExamples = (examples: readonly Example[]): readonly PreparedExample[] => {
+  const cached = preparedExamplesCache.get(examples)
+  if (cached !== undefined) return cached
+  const prepared = examples.map((example) => ({
+    example,
+    labelTokens: new Set([
+      ...tokenize(example.slug),
+      ...tokenize(example.topic),
+      ...tokenize(example.name),
+    ]),
+    codeLower: example.code.toLowerCase(),
+  }))
+  preparedExamplesCache.set(examples, prepared)
+  return prepared
+}
+
 /** Score examples against the query: a term in the slug/topic/name (the curated, searchable labels)
  * is worth far more than a mention in the code body; body hits cap per term so one long snippet can't
  * outweigh a precisely-tagged one. */
@@ -34,13 +57,12 @@ export function searchExamples(
   const terms = queryTermGroups(query)
   if (terms.length === 0) return []
   const scored: ScoredExample[] = []
-  for (const ex of examples) {
-    const labelTokens = new Set([...tokenize(ex.slug), ...tokenize(ex.topic), ...tokenize(ex.name)])
-    const codeLower = ex.code.toLowerCase()
+  for (const prepared of prepareExamples(examples)) {
+    const ex = prepared.example
     let score = 0
     for (const term of terms) {
-      if (tokenSetHas(labelTokens, term)) score += 8
-      score += countBodyHits(codeLower, term, 5)
+      if (tokenSetHas(prepared.labelTokens, term)) score += 8
+      score += countBodyHits(prepared.codeLower, term, 5)
     }
     if (score > 0) scored.push({ ...ex, score })
   }
@@ -76,14 +98,20 @@ export function renderExamplesResult(
 
 /** Load the bundled example corpus. Resolves relative to this module so it works from `src/` (repo dev)
  * and `dist/` (published) alike - `docs/examples.json` sits at the package root next to both. */
-export async function loadExamplesCorpus(): Promise<Example[] | undefined> {
-  const url = new URL("../docs/examples.json", import.meta.url)
-  try {
-    const text = await Bun.file(url).text()
-    if (text.length === 0) return undefined
-    const parsed = JSON.parse(text) as Example[]
-    return Array.isArray(parsed) && parsed.length > 0 ? parsed : undefined
-  } catch {
-    return undefined
-  }
+let examplesCorpusPromise: Promise<Example[] | undefined> | undefined
+
+/** The published corpus is immutable, so keep one loaded array and its derived search fields. */
+export function loadExamplesCorpus(): Promise<Example[] | undefined> {
+  examplesCorpusPromise ??= (async () => {
+    const url = new URL("../docs/examples.json", import.meta.url)
+    try {
+      const text = await Bun.file(url).text()
+      if (text.length === 0) return undefined
+      const parsed = JSON.parse(text) as Example[]
+      return Array.isArray(parsed) && parsed.length > 0 ? parsed : undefined
+    } catch {
+      return undefined
+    }
+  })()
+  return examplesCorpusPromise
 }

package/src/fix-recipes.ts

@@ -0,0 +1,126 @@
+import { existsSync } from "node:fs"
+import { readFile, writeFile } from "node:fs/promises"
+import { join } from "node:path"
+import type { Diagnostic } from "./diagnostics.ts"
+import { resolveInsideProject } from "./project-path.ts"
+
+export interface FixRecipe {
+  readonly id: string
+  readonly description: string
+  apply(root: string, diagnostic: Diagnostic): Promise<readonly string[]>
+  readonly verify: string
+}
+
+const recipes = new Map<string, FixRecipe>()
+
+export function registerFixRecipe(recipe: FixRecipe): void {
+  if (recipes.has(recipe.id)) throw new Error(`duplicate fix recipe: ${recipe.id}`)
+  recipes.set(recipe.id, Object.freeze(recipe))
+}
+
+export function getFixRecipe(id: string): FixRecipe | undefined {
+  return recipes.get(id)
+}
+
+export function listFixRecipes(): readonly FixRecipe[] {
+  return Object.freeze([...recipes.values()])
+}
+
+registerFixRecipe({
+  id: "security.timing-safe-equal",
+  description: "Replace a direct secret comparison with a length check and timing-safe comparison.",
+  verify: "nifra check --lints-only",
+  async apply(root, diagnostic) {
+    if (diagnostic.file === undefined || diagnostic.line === undefined) return []
+    const path = await resolveInsideProject(root, diagnostic.file)
+    if (path === undefined) return []
+    const lines = (await readFile(path, "utf8")).split("\n")
+    const index = diagnostic.line - 1
+    const original = lines[index]
+    if (original === undefined || original.includes("@nifra-gate-reviewed")) return []
+    const comparison = /\b([A-Za-z_$][\w$]*)\s*(===|!==|==|!=)\s*([A-Za-z_$][\w$]*)/.exec(original)
+    if (comparison === null) return []
+    const left = comparison[1] as string
+    const operator = comparison[2] as string
+    const right = comparison[3] as string
+    const expression = `nifraTimingSafeEqual(${left}, ${right})`
+    const replacement = operator === "!==" || operator === "!=" ? `!${expression}` : expression
+    lines[index] = original.replace(comparison[0], replacement)
+    if (!lines.some((line) => line.includes("function nifraTimingSafeEqual"))) {
+      lines.unshift(
+        'import { timingSafeEqual } from "node:crypto"',
+        "",
+        "function nifraTimingSafeEqual(left: string, right: string): boolean {",
+        "  const leftBytes = Buffer.from(left)",
+        "  const rightBytes = Buffer.from(right)",
+        "  return leftBytes.length === rightBytes.length && timingSafeEqual(leftBytes, rightBytes)",
+        "}",
+        "",
+      )
+    }
+    await writeFile(path, lines.join("\n"), "utf8")
+    return [diagnostic.file]
+  },
+})
+
+registerFixRecipe({
+  id: "manifest.sync",
+  description: "Regenerate generated server manifests from the current route tree.",
+  verify: "nifra check --lints-only",
+  async apply(root) {
+    const { syncServerManifests } = await import("./sync-manifest.ts")
+    const results = await syncServerManifests(root)
+    return results.filter((result) => result.changed).map((result) => result.file)
+  },
+})
+
+registerFixRecipe({
+  id: "contracts.snapshot",
+  description: "Refresh the opt-in contract lock after reviewing an intentional route change.",
+  verify: "nifra contracts check",
+  async apply(root) {
+    const { snapshotContracts } = await import("./contracts.ts")
+    await snapshotContracts(root)
+    return ["contracts.lock.json"]
+  },
+})
+
+registerFixRecipe({
+  id: "workspace-dist.rebuild",
+  description: "Rebuild the workspace-linked package whose artifact is older than its source.",
+  verify: "nifra doctor --json",
+  async apply(root, diagnostic) {
+    const packageName = diagnostic.evidence?.[0]
+    if (packageName === undefined || !/^@?[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)?$/.test(packageName))
+      return []
+    // The segment regex above admits "." and "..", which would resolve outside node_modules.
+    if (packageName.split("/").some((segment) => segment === "." || segment === "..")) return []
+    const packageDir = await resolveInsideProject(root, join("node_modules", packageName))
+    if (packageDir === undefined) return []
+    const packageJson = await resolveInsideProject(
+      root,
+      join("node_modules", packageName, "package.json"),
+    )
+    if (packageJson === undefined || !existsSync(packageJson)) return []
+    const proc = Bun.spawn(["bun", "run", "build"], {
+      cwd: packageDir,
+      stdout: "ignore",
+      stderr: "pipe",
+    })
+    const error = await new Response(proc.stderr).text()
+    const exitCode = await proc.exited
+    if (exitCode !== 0) throw new Error(error.trim() || `build failed for ${packageName}`)
+    return [diagnostic.evidence?.[1] ?? packageName]
+  },
+})
+
+export async function applyDiagnosticRecipe(
+  root: string,
+  diagnostic: Diagnostic,
+): Promise<readonly string[]> {
+  const recipeId = diagnostic.fix?.recipe
+  if (recipeId === undefined) return []
+  const recipe = getFixRecipe(recipeId)
+  if (recipe === undefined) return []
+  return recipe.apply(root, diagnostic)
+}

package/src/init-agents.ts

@@ -18,7 +18,8 @@
  * cwd (no `..` traversal escaping the project root).
  */
 
-import { mkdir, readFile, writeFile } from "node:fs/promises"
+import type { Stats } from "node:fs"
+import { lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises"
 import { isAbsolute, relative, resolve } from "node:path"
 import {
   AGENTS_MD_PATH,
@@ -68,6 +69,44 @@ const fileExists = (path: string): Promise<boolean> =>
     .then(() => true)
     .catch(() => false)
 
+/** `lstat`, with "it isn't there" reported as `undefined` instead of a throw. Every other failure
+ * (EACCES, ELOOP, ...) still propagates - only absence is an expected outcome here. */
+async function lstatOrMissing(path: string): Promise<Stats | undefined> {
+  try {
+    return await lstat(path)
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined
+    throw error
+  }
+}
+
+/**
+ * Refuse to write through a symlinked ancestor. `safeJoin` only proves the *textual* path stays
+ * under the project root; a symlinked `.cursor` still lands the write wherever it points. The walk
+ * stops at the first missing segment - `mkdir` will create the rest, so there is nothing to check.
+ */
+async function assertSafeParents(cwd: string, abs: string): Promise<void> {
+  const rel = relative(cwd, resolve(abs, ".."))
+  let current = cwd
+  for (const part of rel.split(/[\\/]/).filter(Boolean)) {
+    current = resolve(current, part)
+    const stat = await lstatOrMissing(current)
+    if (stat === undefined) break
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      throw new Error(`[nifra] refusing unsafe parent path: ${part}`)
+    }
+  }
+}
+
+/** Refuse to write anything that is not a plain absent-or-regular file: a symlink here would
+ * redirect the write, and a directory or device node would make it fail in a confusing way. */
+async function assertRegularTarget(abs: string, rel: string): Promise<void> {
+  const stat = await lstatOrMissing(abs)
+  if (stat !== undefined && (stat.isSymbolicLink() || !stat.isFile())) {
+    throw new Error(`[nifra] refusing to write non-regular file: ${rel}`)
+  }
+}
+
 /**
  * Write a whole-file generator's output to `path` unless it already exists and `force` is false.
  * Returns the per-file result for the report.
@@ -79,15 +118,31 @@ async function writeOwned(
   force: boolean,
 ): Promise<InitAgentsFileResult> {
   const abs = safeJoin(cwd, rel)
+  await assertSafeParents(cwd, abs)
+  await assertRegularTarget(abs, rel)
   if (!force && (await fileExists(abs))) {
     return { path: rel, action: "skipped", note: "exists - pass --force to overwrite" }
   }
   // `.cursor/mcp.json` needs its parent dir; `recursive` is a no-op for the root-level files.
   await mkdir(resolve(abs, ".."), { recursive: true })
-  await writeFile(abs, content)
+  await atomicWrite(abs, content)
   return { path: rel, action: "wrote" }
 }
 
+/** Write via a sibling temp file so a crash mid-write can't leave a half-written config in place.
+ * `wx` fails rather than following an existing name, and the temp is cleaned up on any failure so a
+ * botched run doesn't litter the user's project. */
+async function atomicWrite(abs: string, content: string): Promise<void> {
+  const tmp = `${abs}.nifra-${process.pid}-${Date.now()}`
+  await writeFile(tmp, content, { flag: "wx" })
+  try {
+    await rename(tmp, abs)
+  } catch (error) {
+    await rm(tmp, { force: true })
+    throw error
+  }
+}
+
 /**
  * AGENTS.md is additive, not owned: if it exists and already has the MCP section, leave it; if it exists
  * without the section, append the section (preserving the user's conventions); if it's absent, write a
@@ -96,6 +151,8 @@ async function writeOwned(
  */
 async function ensureAgentsMd(cwd: string): Promise<InitAgentsFileResult> {
   const abs = safeJoin(cwd, AGENTS_MD_PATH)
+  await assertSafeParents(cwd, abs)
+  await assertRegularTarget(abs, AGENTS_MD_PATH)
   const section = agentsMcpSection()
   let existing: string | undefined
   try {
@@ -104,7 +161,7 @@ async function ensureAgentsMd(cwd: string): Promise<InitAgentsFileResult> {
     existing = undefined // no AGENTS.md yet
   }
   if (existing === undefined) {
-    await writeFile(
+    await atomicWrite(
       abs,
       `# AGENTS.md\n\nGuidance for AI coding agents working in this repo.\n\n${section}\n`,
     )
@@ -115,7 +172,7 @@ async function ensureAgentsMd(cwd: string): Promise<InitAgentsFileResult> {
     return { path: AGENTS_MD_PATH, action: "present", note: "already has an MCP section" }
   }
   const sep = existing.endsWith("\n") ? "\n" : "\n\n"
-  await writeFile(abs, `${existing}${sep}${section}\n`)
+  await atomicWrite(abs, `${existing}${sep}${section}\n`)
   return { path: AGENTS_MD_PATH, action: "appended" }
 }
 

package/src/internal/source-facts.ts

@@ -0,0 +1,133 @@
+import type * as TSApi from "typescript"
+import type { TypeScriptApi } from "./typescript-import.ts"
+
+/**
+ * The deliberately small AST seam used by source lints. It is not a project-wide TypeScript
+ * Program: a rule asks for a file only after its lexical fast path found a candidate. That keeps
+ * cold checks and projects without a TypeScript install on the existing conservative path.
+ */
+export interface SourceFacts {
+  parse(file: string, content: string): TSApi.SourceFile | undefined
+  isValueImportAt(
+    source: TSApi.SourceFile,
+    position: number,
+    specifier: string,
+  ): boolean | undefined
+  isRouteRegistrationAt(
+    source: TSApi.SourceFile,
+    position: number,
+    method: string,
+    path: string,
+  ): boolean | undefined
+  isResponseSyntaxAt(source: TSApi.SourceFile, position: number): boolean | undefined
+}
+
+function nodeAt(ts: TypeScriptApi, source: TSApi.SourceFile, position: number): TSApi.Node {
+  let best: TSApi.Node = source
+  const visit = (node: TSApi.Node): void => {
+    if (position < node.pos || position >= node.end) return
+    best = node
+    ts.forEachChild(node, visit)
+  }
+  visit(source)
+  return best
+}
+
+function ancestorAt(
+  ts: TypeScriptApi,
+  source: TSApi.SourceFile,
+  position: number,
+  predicate: (node: TSApi.Node) => boolean,
+): TSApi.Node | undefined {
+  let node: TSApi.Node = nodeAt(ts, source, Math.max(0, Math.min(position, source.end - 1)))
+  for (;;) {
+    if (predicate(node)) return node
+    if (node === source) return undefined
+    node = node.parent
+  }
+}
+
+function rawResponseExpression(ts: TypeScriptApi, node: TSApi.Expression): boolean {
+  if (ts.isNewExpression(node)) {
+    return ts.isIdentifier(node.expression) && node.expression.text === "Response"
+  }
+  if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) return false
+  return (
+    ts.isIdentifier(node.expression.expression) &&
+    node.expression.expression.text === "Response" &&
+    node.expression.name.text === "json"
+  )
+}
+
+export function createSourceFacts(ts: TypeScriptApi): SourceFacts {
+  const cache = new Map<string, { content: string; source: TSApi.SourceFile | undefined }>()
+
+  const parse = (file: string, content: string): TSApi.SourceFile | undefined => {
+    const cached = cache.get(file)
+    if (cached?.content === content) return cached.source
+    const kind = /\.tsx?$/.test(file) ? ts.ScriptKind.TSX : ts.ScriptKind.JS
+    const source = ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true, kind)
+    const diagnostics = (
+      source as TSApi.SourceFile & { parseDiagnostics?: readonly TSApi.Diagnostic[] }
+    ).parseDiagnostics
+    const parsed = diagnostics !== undefined && diagnostics.length > 0 ? undefined : source
+    cache.set(file, { content, source: parsed })
+    return parsed
+  }
+
+  const isValueImportAt = (
+    source: TSApi.SourceFile,
+    position: number,
+    specifier: string,
+  ): boolean | undefined => {
+    const declaration = ancestorAt(ts, source, position, ts.isImportDeclaration) as
+      | TSApi.ImportDeclaration
+      | undefined
+    if (declaration === undefined || !ts.isStringLiteral(declaration.moduleSpecifier))
+      return undefined
+    if (declaration.moduleSpecifier.text !== specifier) return undefined
+    const clause = declaration.importClause
+    if (clause === undefined) return true // side-effect import
+    if (clause.isTypeOnly) return false
+    if (clause.namedBindings !== undefined && ts.isNamedImports(clause.namedBindings)) {
+      return clause.namedBindings.elements.some((element) => !element.isTypeOnly)
+    }
+    return true // default and namespace bindings are runtime imports
+  }
+
+  const isRouteRegistrationAt = (
+    source: TSApi.SourceFile,
+    position: number,
+    method: string,
+    path: string,
+  ): boolean | undefined => {
+    const call = ancestorAt(ts, source, position, ts.isCallExpression) as
+      | TSApi.CallExpression
+      | undefined
+    if (call === undefined || !ts.isPropertyAccessExpression(call.expression)) return false
+    const name = call.expression.name.text.toUpperCase()
+    const first = call.arguments[0]
+    return (
+      name === method && first !== undefined && ts.isStringLiteralLike(first) && first.text === path
+    )
+  }
+
+  const isResponseSyntaxAt = (source: TSApi.SourceFile, position: number): boolean | undefined => {
+    const returnStatement = ancestorAt(ts, source, position, ts.isReturnStatement) as
+      | TSApi.ReturnStatement
+      | undefined
+    if (returnStatement !== undefined) {
+      return (
+        returnStatement.expression !== undefined &&
+        rawResponseExpression(ts, returnStatement.expression)
+      )
+    }
+    const arrow = ancestorAt(ts, source, position, ts.isArrowFunction) as
+      | TSApi.ArrowFunction
+      | undefined
+    if (arrow !== undefined && !ts.isBlock(arrow.body)) return rawResponseExpression(ts, arrow.body)
+    return false
+  }
+
+  return { parse, isValueImportAt, isRouteRegistrationAt, isResponseSyntaxAt }
+}

package/src/internal/typescript-import.ts

@@ -31,3 +31,32 @@ export async function importTypeScript(): Promise<TypeScriptApi | undefined> {
     throw cause
   }
 }
+
+/**
+ * Import TypeScript resolved from the PROJECT root first, falling back to the CLI's own dependency
+ * tree. A bare `import("typescript")` resolves relative to this file - the CLI's install - so a
+ * globally-installed or bunx-run CLI could miss the project's compiler (or load a different major)
+ * depending on where the CLI happened to live, while the project's own `typescript` sat unused in
+ * its node_modules. Resolving from `root` makes the verdicts a function of the project, not of how
+ * the CLI was installed - the same cwd-invariance the typecheck gate's tsc resolution has.
+ */
+export async function importProjectTypeScript(root: string): Promise<TypeScriptApi | undefined> {
+  let resolved: string
+  try {
+    resolved = Bun.resolveSync("typescript", root)
+  } catch {
+    // Unresolvable from the project (not installed there, or a non-Bun host without resolveSync):
+    // fall back to the CLI's own tree, which keeps the previous behavior as the floor.
+    return importTypeScript()
+  }
+  try {
+    return (await import(resolved)) as TypeScriptApi
+  } catch (cause) {
+    // Same contract as importTypeScript: a compiler that RESOLVES and then fails evaluating is a
+    // broken install, not a missing one - rethrow rather than silently checking with another copy.
+    const message = cause instanceof Error ? cause.message : String(cause)
+    if (/cannot find (?:package|module)|ERR_MODULE_NOT_FOUND/i.test(message))
+      return importTypeScript()
+    throw cause
+  }
+}

package/src/introspect.ts

@@ -5,7 +5,13 @@
  * *this* project's actual surface, not just generic docs.
  */
 
-import { type ReflectedRoute, reflectRoutes, type SchemaReflection } from "@nifrajs/core/reflection"
+import {
+  type ProjectEvidenceSchema,
+  type ProjectEvidenceSchemaPart,
+  type ProjectEvidenceSnapshot,
+  snapshotProjectEvidence,
+} from "@nifrajs/core/evidence"
+import type { ReflectedRoute, SchemaReflection } from "@nifrajs/core/reflection"
 import type { Manifest } from "@nifrajs/web"
 import { discoverRoutes } from "@nifrajs/web/fs"
 import type { LoadedApp } from "./load.ts"
@@ -13,7 +19,59 @@ import { chooseBuildPipeline, describePipeline } from "./pipeline-guard.ts"
 
 /** Read the backend's registered routes, if it's a `server()` with a `.routes()` method. */
 export function backendRoutes(backend: unknown): ReflectedRoute[] {
-  return [...reflectRoutes(backend)]
+  return reflectedRoutesFromEvidence(snapshotProjectEvidence(backend))
+}
+
+function schemaPartToReflection(
+  value: ProjectEvidenceSchemaPart | undefined,
+): SchemaReflection | undefined {
+  return value === undefined
+    ? undefined
+    : { standard: undefined, jsonSchema: value.jsonSchema, fields: value.fields }
+}
+
+function schemaFromEvidence(schema: ProjectEvidenceSchema | undefined): ReflectedRoute["schema"] {
+  if (schema === undefined) return undefined
+  const errors = Object.fromEntries(
+    Object.entries(schema.errors ?? {}).map(([status, value]) => [
+      status,
+      schemaPartToReflection(value) as SchemaReflection,
+    ]),
+  )
+  const headers = schemaPartToReflection(schema.headers)
+  const body = schemaPartToReflection(schema.body)
+  const query = schemaPartToReflection(schema.query)
+  const params = schemaPartToReflection(schema.params)
+  const response = schemaPartToReflection(schema.response)
+  const sse = schemaPartToReflection(schema.sse)
+  return {
+    ...(schema.bodyLimit !== undefined ? { bodyLimit: schema.bodyLimit } : {}),
+    ...(schema.bodyLimitReason !== undefined ? { bodyLimitReason: schema.bodyLimitReason } : {}),
+    ...(headers !== undefined ? { headers } : {}),
+    ...(body !== undefined ? { body } : {}),
+    ...(query !== undefined ? { query } : {}),
+    ...(params !== undefined ? { params } : {}),
+    ...(response !== undefined ? { response } : {}),
+    ...(Object.keys(errors).length > 0 ? { errors } : {}),
+    ...(sse !== undefined ? { sse } : {}),
+  }
+}
+
+/** Adapt the canonical token-only snapshot to the legacy reflection view used by Markdown helpers. */
+export function reflectedRoutesFromEvidence(evidence: ProjectEvidenceSnapshot): ReflectedRoute[] {
+  return evidence.routes.map((route) => {
+    const schema = schemaFromEvidence(route.schema)
+    return {
+      method: route.method,
+      path: route.path,
+      ...(schema !== undefined ? { schema } : {}),
+      ...(route.assurance !== undefined ? { assurance: route.assurance } : {}),
+      ...(route.capabilities !== undefined ? { capabilities: route.capabilities } : {}),
+      ...(route.family === true ? { family: true } : {}),
+      ...(route.classification !== undefined ? { classification: route.classification } : {}),
+      ...(route.tool !== undefined ? { tool: route.tool } : {}),
+    }
+  })
 }
 
 interface JsonSchemaNode {
@@ -266,15 +324,18 @@ export interface RouteJson {
  * Markdown brief. Optionally filtered to routes whose path starts with `pathPrefix`. Reuses the exact
  * same `call` form and TS-shaped contracts the Markdown brief shows.
  */
-export function routesToJson(app: LoadedApp, pathPrefix?: string): RouteJson[] {
-  const shape = (v: unknown): string | undefined => {
+export function routesToJsonFromEvidence(
+  evidence: ProjectEvidenceSnapshot,
+  pathPrefix?: string,
+): RouteJson[] {
+  const shape = (v: ProjectEvidenceSchemaPart | undefined): string | undefined => {
     if (!v) return undefined
-    const js = (v as SchemaReflection).jsonSchema
+    const js = v.jsonSchema
     return js !== undefined
       ? tsTypeOf(js)
       : "(validated; shape not introspectable from this validator)"
   }
-  let routes = backendRoutes(app.backend)
+  let routes = [...evidence.routes]
   if (pathPrefix !== undefined && pathPrefix !== "") {
     routes = routes.filter((r) => r.path.startsWith(pathPrefix))
   }
@@ -297,6 +358,14 @@ export function routesToJson(app: LoadedApp, pathPrefix?: string): RouteJson[] {
     })
 }
 
+export function routesToJson(
+  app: LoadedApp,
+  pathPrefix?: string,
+  evidence?: ProjectEvidenceSnapshot,
+): RouteJson[] {
+  return routesToJsonFromEvidence(evidence ?? snapshotProjectEvidence(app.backend), pathPrefix)
+}
+
 // ===================================================================================================
 // `nifra routes [--json]` - the focused, uniform view of every route the app serves, with methods.
 //

package/src/load.ts

@@ -38,6 +38,12 @@ export interface NifraFramework {
   readonly adapter: unknown
   /** The client runtime module providing `mountRouter`, e.g. `"@nifrajs/web-react/client"`. */
   readonly clientModule: string
+  /** App-level middleware applied to the web app before its page routes are declared -
+   * e.g. `(app) => app.use(securityHeaders())`. Runs ahead of the `api`/`mounts` hooks.
+   *
+   * MUST be exported from `framework.ts`, not `nifra.config.ts`: `nifra build` emits a
+   * server entry that imports it, and that entry is edge-bundled. See the module header. */
+  readonly use?: (app: never) => void
   /** Vite plugins for `nifra dev`'s HMR, e.g. `[react()]` / `() => import("@vitejs/plugin-vue")…`. */
   readonly vitePlugins?: PluginsField
   /** Bun build plugins that compile routes for the CLIENT bundle (`nifra build`), e.g.

package/src/manifest-tool.ts

@@ -2,7 +2,6 @@
 
 import { existsSync } from "node:fs"
 import { resolve } from "node:path"
-import { evaluateRouteAssurance } from "@nifrajs/core/assurance"
 import {
   buildNifraManifest,
   diffNifraManifests,
@@ -12,8 +11,7 @@ import {
   serializeNifraManifestSignature,
   signNifraManifest,
 } from "@nifrajs/core/manifest"
-import { loadAssuranceConfig } from "./assure.ts"
-import { collectCapabilityProjectReport } from "./capabilities-tool.ts"
+import { collectProjectVerification } from "./verification.ts"
 
 export const DEFAULT_MANIFEST_FILE = "nifra.manifest.json"
 
@@ -45,20 +43,28 @@ export async function runManifestEmit(
   cwd: string,
   options: { readonly config?: string; readonly out?: string; readonly sign?: string } = {},
 ): Promise<boolean> {
-  const config = await loadAssuranceConfig(cwd, options.config)
-  const assurance = evaluateRouteAssurance(config.source, config.policy, {
-    ...(config.capabilities !== undefined ? { definitions: config.capabilities.definitions } : {}),
+  const verification = await collectProjectVerification(cwd, {
+    ...(options.config !== undefined ? { config: options.config } : {}),
   })
-  const capabilityProject =
-    config.capabilities === undefined
-      ? undefined
-      : await collectCapabilityProjectReport(cwd, config.source, config.capabilities)
+  if (verification.config === undefined) {
+    throw (
+      verification.configError ??
+      new Error("[nifra] assurance config could not be loaded for manifest emission")
+    )
+  }
+  const config = verification.config
+  const assurance = verification.routeAssurance
+  const capabilityProject = verification.capability
+  if (assurance === undefined) {
+    throw new Error("[nifra] assurance evaluation was unavailable for manifest emission")
+  }
   if (!assurance.ok || (capabilityProject !== undefined && !capabilityProject.report.ok)) {
     console.error("[nifra] refusing to emit a manifest from failing assurance")
     return false
   }
   const manifest = await buildNifraManifest({
     source: config.source,
+    ...(verification.evidence !== undefined ? { evidence: verification.evidence } : {}),
     assurance,
     ...(capabilityProject !== undefined ? { capabilities: capabilityProject.report } : {}),
   })