@nifrajs/cli 2.10.0 → 2.12.0

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,14 +5,73 @@
  * *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"
+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 {
@@ -232,6 +291,11 @@ export function describeProject(app: LoadedApp, filter?: ContextFilter): string
       // Point agents at the verified surface, not recalled APIs - nifra is young, so training data is the
       // wrong source. The MCP tools (nifra_docs / nifra_example) are checked against the installed version.
       "> **Build against THIS surface + the verified tools - do not write nifra APIs from memory** (the\n> framework is young; recalled APIs drift). For framework code, call `nifra_example` (snippets\n> typechecked against the installed version) or `nifra_docs`; verify edits with `nifra_run` + `nifra_check`.",
+      // The authoritative answer, not the static reading `nifra_check`/`nifra_doctor` give: this runs on
+      // the LOADED config, so it is the same decision `nifra dev` and `nifra build` make. Stated in the
+      // index because it governs where a plugin goes and which toolchain compiles a component - an edit
+      // put in the other pipeline's slot is accepted and then silently never runs.
+      `**Bundler**: ${describePipeline(chooseBuildPipeline(app.resolvedPlugins))}. \`vitePlugins\` feed Vite; \`clientPlugins\`/\`serverPlugins\` feed Bun.build. Both phases (dev and build) use the same one.`,
     )
   }
   if (filter?.kind !== "pages") {
@@ -260,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))
   }
@@ -291,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.
@@ -93,6 +99,10 @@ export interface ResolvedPlugins {
 
 export interface LoadedApp {
   readonly cwd: string
+  /** Absolute path of the config this app was loaded from - `nifra.config.ts`, or `framework.ts` as the
+   * fallback. `nifra dev`'s Bun pipeline re-imports it from a GENERATED module so the app's own
+   * `clientPlugins` reach Bun's dev-server bundler, which takes plugins only as module paths. */
+  readonly configPath: string
   readonly routesDir: string
   /** Build output dir (also where `nifra start` reads `manifest.json` + serves `/assets/*`). */
   readonly outDir: string
@@ -222,6 +232,7 @@ export async function loadApp(
 
   return {
     cwd,
+    configPath,
     routesDir: resolve(cwd, "routes"),
     outDir: resolve(cwd, outDirName),
     framework: { ...fw, clientModule } as NifraFramework,

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 } : {}),
   })

package/src/mcp-docs-tools.ts

@@ -35,6 +35,7 @@ export function docsTools(
         properties: {
           query: {
             type: "string",
+            maxLength: 256,
             description: "Keywords to match against doc sections (omit for the index).",
           },
           limit: { type: "number", description: "Max sections to return (default 3, max 5)." },
@@ -64,6 +65,7 @@ export function docsTools(
         properties: {
           query: {
             type: "string",
+            maxLength: 256,
             description: "What you want an example of (omit for the index).",
           },
           limit: { type: "number", description: "Max examples to return (default 3, max 5)." },
@@ -94,6 +96,7 @@ export function docsTools(
           },
           query: {
             type: "string",
+            maxLength: 256,
             description:
               "Keyword search over names + signatures (when you don't know the exact name).",
           },

package/src/mcp-http.ts

@@ -29,7 +29,7 @@ export { docsTools } from "./mcp-docs-tools.ts"
 export type { TypeEntry } from "./types-search.ts"
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const VERSION = "2.10.0"
+const VERSION = "2.12.0"
 const SERVER_INFO = { name: "nifra-docs", version: VERSION }
 // Derive the GET/health tool list from the tools actually served, so the line can never drift from them.
 const docsHealth = (tools: McpTool[]): string =>