@nifrajs/cli 3.5.0 → 4.0.0

package/src/introspect.ts

@@ -12,9 +12,12 @@ import {
   reflectedRoutesFromEvidence,
   snapshotProjectEvidence,
 } from "@nifrajs/core/evidence"
+import { compileRoutePattern, type RoutePatternSegment } from "@nifrajs/core/pattern"
 import type { ReflectedRoute } from "@nifrajs/core/reflection"
 import type { Manifest } from "@nifrajs/web"
 import { discoverRoutes } from "@nifrajs/web/fs"
+import { normalizeMountPath } from "@nifrajs/web/route-manifest"
+import { codeUnitOrder } from "./internal/code-unit-order.ts"
 import type { LoadedApp } from "./load.ts"
 import { chooseBuildPipeline, describePipeline } from "./pipeline-guard.ts"
 
@@ -102,6 +105,44 @@ function schemaLines(schema: ReflectedRoute["schema"]): string[] {
 
 const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/
 
+/** The verbs the typed client has a terminal call for. */
+const TYPED_VERBS: ReadonlySet<string> = new Set([
+  "get",
+  "post",
+  "put",
+  "patch",
+  "delete",
+  "head",
+  "options",
+])
+
+/**
+ * The call a non-static segment adds to the chain, or `undefined` for a static one. The segment is
+ * read by the router's own grammar, so the spelling matches what the typed client accepts:
+ *   - a whole param or a wildcard is called by its name - `:id` and `:id{[0-9]+}` are `({ id })`;
+ *   - a segment that is part literal, part parameter is called with the segment text -
+ *     `:name.json` is ``(`${name}.json`)``.
+ */
+function paramCall(seg: string): string | undefined {
+  let segment: RoutePatternSegment | undefined
+  try {
+    segment = compileRoutePattern(`/${seg}`).segments[0]
+  } catch {
+    return undefined
+  }
+  if (segment === undefined || segment.kind === "static") return undefined
+  if (segment.kind === "param") return `({ ${segment.name} })`
+  if (segment.kind === "wildcard") {
+    return segment.name === "*" ? '({ "*": rest })' : `({ ${segment.name} })`
+  }
+  const [only] = segment.parts
+  if (segment.parts.length === 1 && only?.t === "param") return `({ ${only.name} })`
+  const text = segment.parts
+    .map((part) => (part.t === "lit" ? part.v.replace(/[`\\]|\$\{/g, "\\$&") : `\${${part.name}}`))
+    .join("")
+  return `(\`${text}\`)`
+}
+
 /**
  * The typed-client proxy chain for a path, without the terminal verb call. Shared by `clientCall`
  * and the `nifra routes` collision annotation so both teach exactly one spelling.
@@ -111,10 +152,9 @@ function clientChain(path: string): string {
   if (segs.length === 0) return "api.index"
   let chain = "api"
   for (const seg of segs) {
-    if (seg.startsWith(":") || seg.startsWith("*")) {
-      const name = seg.replace(/^[:*]/, "") || "value"
-      chain += `({ ${name} })`
-    } else if (reservedKeyFor(seg) !== undefined) chain += `(${JSON.stringify(seg)})`
+    const call = paramCall(seg)
+    if (call !== undefined) chain += call
+    else if (reservedKeyFor(seg) !== undefined) chain += `(${JSON.stringify(seg)})`
     else chain += IDENT.test(seg) ? `.${seg}` : `[${JSON.stringify(seg)}]`
   }
   return chain
@@ -124,7 +164,8 @@ function clientChain(path: string): string {
  * The typed-client call form for a route - the exact `client<typeof app>` proxy chain an agent should
  * write, derived from the same convention `@nifrajs/client` implements (so it never has to read the
  * client tests to learn it): a static segment is a property (`.users`), a path param/wildcard is a call
- * that appends the value (`({ id })`), the root path is `.index`, and the HTTP verb is the terminal call.
+ * that appends the value (`({ id })`), a segment that is part literal, part parameter is a call with
+ * the segment text (``(`${name}.json`)``), the root path is `.index`, and the HTTP verb is the terminal call.
  * Body verbs (POST/PUT/PATCH) take the body first then call-options; other verbs take call-options first -
  * so the `{ query }` argument lands in the right slot for each.
  *
@@ -136,6 +177,9 @@ function clientChain(path: string): string {
 export function clientCall(method: string, path: string, schema: unknown): string {
   const s = schema as { body?: unknown; query?: unknown } | undefined
   const verb = method.toLowerCase()
+  // The typed client has a call for the standard methods only; any other method goes out through
+  // `fetch`, against the route's own path.
+  if (!TYPED_VERBS.has(verb)) return `await fetch(url, { method: ${JSON.stringify(method)} })`
   const chain = clientChain(path)
   const isBodyVerb = verb === "post" || verb === "put" || verb === "patch"
   let call: string
@@ -153,16 +197,18 @@ export function clientCall(method: string, path: string, schema: unknown): strin
 /** Markdown section listing the backend's API routes with their request + response field shapes. */
 export function apiRoutesSection(routes: readonly ReflectedRoute[]): string {
   if (routes.length === 0) {
-    return "## API routes\n\nNo `backend.ts` server routes found (this app may be frontend-only)."
+    return "## API routes\n\nNo `backend/app.ts` server routes found (this app may be frontend-only)."
   }
   const lines = [...routes]
-    .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method))
+    .sort((a, b) => codeUnitOrder(a.path, b.path) || codeUnitOrder(a.method, b.method))
     .flatMap((r) => [
       `- \`${r.method} ${r.path}\``,
       ...schemaLines(r.schema),
-      `    - call: \`${clientCall(r.method, r.path, r.schema)}\` → \`{ ok, status, data, error }\``,
+      TYPED_VERBS.has(r.method.toLowerCase())
+        ? `    - call: \`${clientCall(r.method, r.path, r.schema)}\` → \`{ ok, status, data, error }\``
+        : `    - call: \`${clientCall(r.method, r.path, r.schema)}\` (no typed-client call for this method; \`url\` is the path above)`,
     ])
-  return `## API routes (backend.ts)\n\nEach route's \`body\`/\`query\`/\`response\` shape is its contract - the typed client derives request inputs and \`res.data\` from these, so a screen built on \`client<typeof app>\` stays in sync automatically. The \`call\` line is the exact \`client<typeof app>\` form: static path segments are properties, a path param is a call (\`({ id })\`), the verb is the terminal call (body first for POST/PUT/PATCH), and every call returns the never-throwing \`{ ok, status, data, error }\` Result.\n\n${lines.join("\n")}`
+  return `## API routes (backend/app.ts)\n\nEach route's \`body\`/\`query\`/\`response\` shape is its contract - the typed client derives request inputs and \`res.data\` from these, so a screen built on \`client<typeof app>\` stays in sync automatically. The \`call\` line is the exact \`client<typeof app>\` form: static path segments are properties, a path param is a call (\`({ id })\`), the verb is the terminal call (body first for POST/PUT/PATCH), and every call returns the never-throwing \`{ ok, status, data, error }\` Result.\n\n${lines.join("\n")}`
 }
 
 /** Compact API-routes INDEX for the no-arg `nifra_context` call - `METHOD path` per route, WITHOUT the
@@ -171,12 +217,12 @@ export function apiRoutesSection(routes: readonly ReflectedRoute[]): string {
  * contract via the `path`/`kind` slice, instead of every schema up front. */
 export function apiRoutesIndexSection(routes: readonly ReflectedRoute[]): string {
   if (routes.length === 0) {
-    return "## API routes (backend.ts)\n\nNo `backend.ts` server routes found (this app may be frontend-only)."
+    return "## API routes (backend/app.ts)\n\nNo `backend/app.ts` server routes found (this app may be frontend-only)."
   }
   const lines = [...routes]
-    .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method))
+    .sort((a, b) => codeUnitOrder(a.path, b.path) || codeUnitOrder(a.method, b.method))
     .map((r) => `- \`${r.method} ${r.path}\``)
-  return `## API routes (backend.ts)\n\n${routes.length} route${routes.length === 1 ? "" : "s"}. Call \`nifra_context\` again with \`path\` (a route prefix) and/or \`kind: "api"\` for the body/query/response contracts + the exact \`client<typeof app>\` call form - or \`nifra_routes\` for the same as structured JSON.\n\n${lines.join("\n")}`
+  return `## API routes (backend/app.ts)\n\n${routes.length} route${routes.length === 1 ? "" : "s"}. Call \`nifra_context\` again with \`path\` (a route prefix) and/or \`kind: "api"\` for the body/query/response contracts + the exact \`client<typeof app>\` call form - or \`nifra_routes\` for the same as structured JSON.\n\n${lines.join("\n")}`
 }
 
 /** Markdown section listing the file-routed pages (URL pattern → source file). */
@@ -185,7 +231,7 @@ export function pageRoutesSection(manifest: Manifest | undefined): string {
     return "## Page routes\n\nNo file routes found under `routes/`."
   }
   const lines = [...manifest.routes]
-    .sort((a, b) => a.pattern.localeCompare(b.pattern))
+    .sort((a, b) => codeUnitOrder(a.pattern, b.pattern))
     .map((r) => `- \`${r.pattern}\` → \`${r.file}\``)
   return `## Page routes (routes/)\n\n${lines.join("\n")}`
 }
@@ -207,9 +253,9 @@ const CONVENTIONS = `## Conventions (summary)
   \`res.data\` from the backend's route types, so the compiler catches any frontend/backend drift. Never
   hand-roll \`fetch\` + ad-hoc response types for an internal API - that's exactly how screens drift. It
   never throws: branch on \`res.ok ? res.data : res.error\`.
-- **Pages:** file-routed under \`routes/\`; \`loader\`/\`action\` are server-only but the module is also bundled
-  for the browser - **never top-level-import server-only code** (DB, secrets, \`process.env\`) into a route
-  file; reach it via \`ctx.api\` / \`ctx.env\`.
+- **Pages:** file-routed under \`routes/\`. A route is two files: \`x.tsx\` (browser) and \`x.backend.ts\`
+  (\`loader\`, \`action\`, \`middleware\`; server only). Server code lives under \`backend/\`, code both sides
+  use under \`shared/\`, components under \`frontend/\`; the browser build refuses backend code outright.
 - \`app.fetch(Request)\` is the universal entry. Full reference: this repo's \`AGENTS.md\`, or \`llms-full.txt\`.`
 
 /** Optional narrowing for {@link describeProject} - a path prefix and/or one section. A filtered
@@ -303,7 +349,7 @@ export function routesToJsonFromEvidence(
     routes = routes.filter((r) => r.path.startsWith(pathPrefix))
   }
   return [...routes]
-    .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method))
+    .sort((a, b) => codeUnitOrder(a.path, b.path) || codeUnitOrder(a.method, b.method))
     .map((r) => {
       const s = r.schema
       const body = shape(s?.body)
@@ -373,12 +419,16 @@ export interface RouteTableInput {
   /** The page router's `apiPrefix` (default `/api`); an API route at/under it is auto-mounted. `""`
    * disables the auto-mount, so no API route is marked auto-mounted. */
   readonly apiPrefix?: string
+  /** The backend declares its routes without the prefix and is served at `apiPrefix + path`: every API
+   * route is auto-mounted, listed at the path a request uses. */
+  readonly apiStrip?: boolean
 }
 
 /** True when `path` is at or under `prefix` as a path segment boundary (`/api` matches `/api` and
  * `/api/x`, but not `/apiary`). An empty prefix matches nothing (auto-mount disabled). */
 function isUnderPrefix(path: string, prefix: string): boolean {
   if (prefix === "") return false
+  if (prefix === "/") return true
   return path === prefix || path.startsWith(`${prefix}/`)
 }
 
@@ -390,7 +440,14 @@ function isUnderPrefix(path: string, prefix: string): boolean {
  * joined methods, for stable output.
  */
 export function buildRouteTable(input: RouteTableInput): RouteTableEntry[] {
-  const apiPrefix = input.apiPrefix ?? "/api"
+  const configured = input.apiPrefix ?? "/api"
+  // Read the prefix as the server's mount table does (`/api/` and `/api/*` are `/api`).
+  const apiPrefix = configured === "" ? "" : (normalizeMountPath(configured) ?? configured)
+  const stripped = input.apiStrip === true && apiPrefix !== ""
+  const servedPath = (path: string): string => {
+    if (!stripped || apiPrefix === "/") return path
+    return path === "/" ? apiPrefix : `${apiPrefix}${path}`
+  }
   const rows: RouteTableEntry[] = []
   for (const page of input.pages) {
     const methods = page.hasAction ? ["GET", "POST"] : ["GET"]
@@ -399,11 +456,12 @@ export function buildRouteTable(input: RouteTableInput): RouteTableEntry[] {
   // Collapse API routes that share a path into one row with all its methods (a REST resource).
   const byPath = new Map<string, { methods: Set<string>; autoMounted: boolean }>()
   for (const r of input.api) {
-    const existing = byPath.get(r.path)
+    const path = servedPath(r.path)
+    const existing = byPath.get(path)
     if (existing === undefined) {
-      byPath.set(r.path, {
+      byPath.set(path, {
         methods: new Set([r.method.toUpperCase()]),
-        autoMounted: isUnderPrefix(r.path, apiPrefix),
+        autoMounted: stripped || isUnderPrefix(r.path, apiPrefix),
       })
     } else existing.methods.add(r.method.toUpperCase())
   }
@@ -417,9 +475,9 @@ export function buildRouteTable(input: RouteTableInput): RouteTableEntry[] {
   }
   return rows.sort(
     (a, b) =>
-      a.path.localeCompare(b.path) ||
-      a.kind.localeCompare(b.kind) ||
-      a.methods.join(",").localeCompare(b.methods.join(",")),
+      codeUnitOrder(a.path, b.path) ||
+      codeUnitOrder(a.kind, b.kind) ||
+      codeUnitOrder(a.methods.join(","), b.methods.join(",")),
   )
 }
 
@@ -447,7 +505,7 @@ export function clientSpellingFor(
 /** Render the route table as a terse aligned text table (the `nifra routes` default output). Pure. */
 export function renderRouteTable(rows: readonly RouteTableEntry[]): string {
   if (rows.length === 0)
-    return "No routes found (no `routes/` pages and no `backend.ts` API routes)."
+    return "No routes found (no `routes/` pages and no `backend/app.ts` API routes)."
   const display = rows.map((r) => ({
     methods: r.methods.join(", "),
     kind: r.kind,
@@ -543,7 +601,7 @@ function parentPath(path: string): string | undefined {
 /** Build a stable parent/child graph from the public route table. Pure and topology-neutral. */
 export function buildRouteGraph(rows: readonly RouteTableEntry[]): RouteGraph {
   const sorted = [...rows].sort(
-    (a, b) => a.path.localeCompare(b.path) || a.kind.localeCompare(b.kind),
+    (a, b) => codeUnitOrder(a.path, b.path) || codeUnitOrder(a.kind, b.kind),
   )
   const nodes: RouteGraphNode[] = [
     { id: "root", kind: "root", path: "/" },
@@ -643,7 +701,12 @@ async function collectRouteTable(app: LoadedApp): Promise<RouteTableEntry[]> {
     }
     pages.push({ pattern: route.pattern, file: route.file, hasAction })
   }
-  const rows = buildRouteTable({ pages, api: backendRoutes(app.backend) })
+  const rows = buildRouteTable({
+    pages,
+    api: backendRoutes(app.backend),
+    ...(app.framework.apiPrefix !== undefined ? { apiPrefix: app.framework.apiPrefix } : {}),
+    ...(app.framework.apiStrip !== undefined ? { apiStrip: app.framework.apiStrip } : {}),
+  })
   return rows
 }
 

package/src/learn.ts

@@ -39,7 +39,7 @@ export const LEARN_PATH: readonly LearnStep[] = [
     id: "page-route",
     title: "Add a page route",
     goal: "A second page, server-rendered, reachable by URL.",
-    do: "Ask nifra_scaffold for the path (e.g. /about) - it returns the exact `routes/` file and a contract-correct page stub. File-based: `routes/about.tsx` serves `/about`.",
+    do: "Ask nifra_scaffold for the path (e.g. /about) - it writes the route pair: the page `routes/about.tsx` (serves `/about`) and its backend half `routes/about.backend.ts`.",
     verify: "nifra_render /about returns the rendered HTML.",
     tools: ["nifra_scaffold", "nifra_render"],
     seeAlso: "page routes file-based routing layouts",
@@ -48,7 +48,7 @@ export const LEARN_PATH: readonly LearnStep[] = [
     id: "loader",
     title: "Load data for a page",
     goal: "A page whose data is fetched on the server before render.",
-    do: "Export a `loader` from the route and read its result in the component. Get the exact shape from nifra_example ('loader').",
+    do: "Export a `loader` and its `loaderOutput` schema from the route's `.backend.ts` half and read the result as `data` (`Route.ComponentProps`) in the page. Get the exact shape from nifra_example ('loader').",
     verify: "nifra_render the page and confirm the loaded data is in the HTML.",
     tools: ["nifra_example", "nifra_render"],
     seeAlso: "loader server data page",
@@ -57,7 +57,7 @@ export const LEARN_PATH: readonly LearnStep[] = [
     id: "api-route",
     title: "Add a typed API route",
     goal: "A backend endpoint with a typed request/response contract.",
-    do: "Add the route to `backend.ts` with an @nifrajs/schema body/query/response schema. nifra_context shows the resulting contract and the exact typed-client call form.",
+    do: "Add the route to `backend/app.ts` with an @nifrajs/schema body/query/response schema. nifra_context shows the resulting contract and the exact typed-client call form.",
     verify:
       "nifra_run { method, path, body } and check the status + parsed body; nifra_check confirms the contract typechecks.",
     tools: ["nifra_context", "nifra_run", "nifra_check"],

package/src/levels-tool.ts

@@ -36,6 +36,17 @@ export interface VerificationLevelsResult {
   /** Highest level whose whole ladder holds; -1 when even L0 fails. */
   readonly achieved: number
   readonly levels: readonly VerificationLevelStatus[]
+  /** Response/error runtime enforcement is reported separately from the cumulative L0-L4 ladder. */
+  readonly responseContracts: ResponseContractStatus
+}
+
+export interface ResponseContractStatus {
+  readonly declared: number
+  readonly enforced: number
+  readonly warnOnly: number
+  readonly typedOnly: number
+  readonly status: "none" | "partial" | "enforced"
+  readonly reasons: readonly string[]
 }
 
 export interface CollectLevelsOptions {
@@ -82,7 +93,7 @@ export async function collectVerificationLevels(
     ] as const) {
       statuses.push({ level, name, ok: false, reasons: [reason] })
     }
-    return finalize(statuses)
+    return finalize(statuses, [])
   }
   const config = verification.config
 
@@ -197,11 +208,12 @@ export async function collectVerificationLevels(
     reasons: l4Reasons,
   })
 
-  return finalize(statuses)
+  return finalize(statuses, assurance.routes)
 }
 
 function finalize(
   statuses: readonly { level: number; name: string; ok: boolean; reasons: string[] }[],
+  routes: readonly { readonly responseContract?: "enforce" | "warn" | "unchecked" }[],
 ): VerificationLevelsResult {
   // Cumulative: the achieved level is the last rung with every rung below it also holding.
   let achieved = -1
@@ -209,6 +221,31 @@ function finalize(
     if (!status.ok) break
     achieved = status.level
   }
+  const declared = routes.filter((route) => route.responseContract !== undefined)
+  const enforced = declared.filter((route) => route.responseContract === "enforce").length
+  const warnOnly = declared.filter((route) => route.responseContract === "warn").length
+  const typedOnly = declared.filter((route) => route.responseContract === "unchecked").length
+  const responseContracts: ResponseContractStatus = {
+    declared: declared.length,
+    enforced,
+    warnOnly,
+    typedOnly,
+    status:
+      declared.length === 0 ? "none" : typedOnly === 0 && warnOnly === 0 ? "enforced" : "partial",
+    reasons:
+      declared.length === 0
+        ? ["no response/error schemas declared"]
+        : [
+            ...(typedOnly > 0
+              ? [
+                  `${typedOnly} declared route(s) are typed-only; install responseContract("enforce")`,
+                ]
+              : []),
+            ...(warnOnly > 0
+              ? [`${warnOnly} declared route(s) are warn-only and still send the original payload`]
+              : []),
+          ],
+  }
   return Object.freeze({
     achieved,
     levels: Object.freeze(
@@ -216,6 +253,10 @@ function finalize(
         Object.freeze({ ...status, reasons: Object.freeze([...status.reasons]) }),
       ),
     ),
+    responseContracts: Object.freeze({
+      ...responseContracts,
+      reasons: Object.freeze([...responseContracts.reasons]),
+    }),
   })
 }
 
@@ -233,6 +274,10 @@ export async function runLevels(
       console.log(`${mark} L${status.level} ${status.name}`)
       for (const reason of status.reasons) console.log(`    - ${reason}`)
     }
+    console.log(
+      `[nifra] response contracts: ${result.responseContracts.status} (${result.responseContracts.enforced} enforced, ${result.responseContracts.warnOnly} warn-only, ${result.responseContracts.typedOnly} typed-only)`,
+    )
+    for (const reason of result.responseContracts.reasons) console.log(`    - ${reason}`)
     console.log(
       result.achieved < 0
         ? "[nifra] verification level: none (L0 failing)"

package/src/load.ts

@@ -1,38 +1,43 @@
 /**
  * Zero-config app discovery. The CLI reads a few conventions from the project root:
  *   - `routes/`         - the file-based routes (per `@nifrajs/web/fs`).
- *   - `nifra.config.ts`  - the CLI's framework wiring (see {@link NifraFramework}); `framework.ts` is
- *                         used as a fallback. One of the two is required.
- *   - `backend.ts`      - exports `backend` (a `@nifrajs/core` server, the contract). Optional.
+ *   - `nifra.config.ts`  - the CLI's framework wiring (see {@link NifraFramework});
+ * `backend/framework.ts` is                         used as a fallback. One of the two is required.
+ *   - `backend/app.ts`      - exports `backend` (a `@nifrajs/core` server, the contract). Optional.
  *
- * Why two filenames: a multi-target app's edge entry (`_worker.ts`) imports `framework.ts` for the
- * render adapter, so `framework.ts` must stay edge-bundlable - it can't reference Vite plugins or the
- * SFC compiler (Bun would pull them into the `target:"browser"` worker and fail on `child_process`).
- * `nifra.config.ts` holds that build/dev tooling instead: it's imported ONLY by this CLI (which runs on
- * Bun), so its Vite plugin + SFC-compiler imports (`@vitejs/plugin-vue`, `@nifrajs/web-vue/plugin`) never
- * reach the edge bundle. A simple single-target app with no edge build can put it all in `framework.ts`.
+ * Why two filenames: a multi-target app's edge entry (`_worker.ts`) imports `backend/framework.ts`
+ * for the render adapter, so `backend/framework.ts` must stay edge-bundlable - it can't reference
+ * Vite plugins or the SFC compiler (Bun would pull them into the `target:"browser"` worker and fail
+ * on `child_process`). `nifra.config.ts` holds that build/dev tooling instead: it's imported ONLY
+ * by this CLI (which runs on Bun), so its Vite plugin + SFC-compiler imports (`@vitejs/plugin-vue`,
+ * `@nifrajs/web-vue/plugin`) never reach the edge bundle. A simple single-target app with no edge
+ * build can put it all in `backend/framework.ts`.
  */
 import { existsSync } from "node:fs"
 import { isAbsolute, resolve } from "node:path"
-import type { CssLoadingMode } from "@nifrajs/web"
+import type { CreateWebAppOptions, CssLoadingMode } from "@nifrajs/web"
+import type { SecretExemption } from "@nifrajs/web/build"
+import { assertCurrentLayout, BACKEND_APP_FILE, CONFIG_FILE, FRAMEWORK_FILE } from "./app-files.ts"
 import { checkPipelineSeparation } from "./pipeline-guard.ts"
 
 /**
- * A plugin list - either an array, or a **thunk** that returns one (optionally async). Both forms are
- * accepted; {@link resolvePlugins} normalizes them. The thunk is just a convenience for deferring a
- * plugin's construction - it does NOT make a plugin edge-safe (Bun.build follows a dynamic `import()`
- * even from an unused export, so a Vite/compiler import in an edge-bundled file fails regardless). Edge
- * safety comes from WHERE the config lives: keep these fields in `nifra.config.ts` (CLI-only), not in
- * the edge-imported `framework.ts`. See the module header.
+ * A plugin list - either an array, or a **thunk** that returns one (optionally async). Both forms
+ * are accepted; {@link resolvePlugins} normalizes them. The thunk is just a convenience for
+ * deferring a plugin's construction - it does NOT make a plugin edge-safe (Bun.build follows a
+ * dynamic `import()` even from an unused export, so a Vite/compiler import in an edge-bundled file
+ * fails regardless). Edge safety comes from WHERE the config lives: keep these fields in
+ * `nifra.config.ts` (CLI-only), not in the edge-imported `backend/framework.ts`. See the module
+ * header.
  */
 export type PluginsField =
   | readonly unknown[]
   | (() => readonly unknown[] | Promise<readonly unknown[]>)
 
 /**
- * The CLI's framework wiring - exported from `nifra.config.ts` (or `framework.ts` as a fallback).
- * `create-nifra` generates it. Only `adapter` + `clientModule` are required; the plugin/condition
- * fields are framework-specific extras (Vue/Svelte/Solid need them; React/Preact don't).
+ * The CLI's framework wiring - exported from `nifra.config.ts` (or `backend/framework.ts` as a
+ * fallback). `create-nifra` generates it. Only `adapter` + `clientModule` are required; the
+ * plugin/condition fields are framework-specific extras (Vue/Svelte/Solid need them; React/Preact
+ * don't).
  */
 export interface NifraFramework {
   /** The render adapter, e.g. `reactAdapter` from `@nifrajs/web-react`. */
@@ -42,7 +47,7 @@ export interface NifraFramework {
   /** 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
+   * MUST be exported from `backend/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")…`. */
@@ -57,14 +62,88 @@ export interface NifraFramework {
   readonly conditions?: readonly string[]
   /** Compile-time `define` replacements, e.g. Vue's `__VUE_*` flags. */
   readonly define?: Readonly<Record<string, string>>
+  /** The deploy target `nifra build` emits without `--target` (default `"bun"`); `nifra target <t>`
+   * rewrites it. */
+  readonly target?: string
+  /** `"platform"` makes a `cloudflare` / `vercel` build read `c.clientIp` from the header that
+   * platform's edge overwrites (`cf-connecting-ip` / `x-real-ip`). Left out, an edge build has no
+   * caller address, so a per-caller `rateLimit` refuses every request. Declare it only while that edge
+   * is the sole way in: served any other way the header is whatever the client sent. Self-hosting
+   * targets use the socket peer either way. */
+  readonly clientIp?: "platform"
+  /** `nifra dev` settings. `indicator: false` turns the in-page issues badge off for every run
+   * (`nifra dev --no-indicator` does it for one); browser errors still reach `nifra errors`. */
+  readonly dev?: { readonly indicator?: boolean }
   /** Static files directory. Defaults to `<app>/public`; `false` disables it. */
   readonly publicDir?: string | false
   /** Client-visible environment prefix (default `"PUBLIC_"`; empty disables exposure). */
   readonly publicEnvPrefix?: string
+  /** Reviewed false positives of `nifra build`'s secret scan, each `{ rule, file, reason }` (or
+   * `{ rule: "private-env-value", env, reason }`). There is no exemption by value. */
+  readonly secretExemptions?: readonly SecretExemption[]
   /** Vite production CSS output policy. `false` emits one aggregate stylesheet for the whole client. */
   readonly cssCodeSplit?: boolean
   /** Framework-owned SSR stylesheet activation. Deferred mode is intended for aggregate CSS. */
   readonly cssLoading?: CssLoadingMode
+  /** Path `backend/app.ts`'s backend is served at (default `"/api"`; `""` turns the mount off). A
+   * page file under it can never render, so the app refuses to start and `nifra build` refuses to
+   * build.
+   *
+   * The fields from here down reach the generated server entry, so like `use` they MUST be exported
+   * from `backend/framework.ts` (re-export them from `nifra.config.ts` when both exist). */
+  readonly apiPrefix?: string
+  /** Strip {@link apiPrefix} before the backend sees the path, for a backend that declares its routes
+   * without it. Default `false`. */
+  readonly apiStrip?: boolean
+  /** Apps mounted ahead of page routing - an auth handler, a webhook receiver, a backend served at an
+   * extra path. See `createWebApp`'s `mounts`. */
+  readonly mounts?: CreateWebAppOptions["mounts"]
+  /** A hash-based Content-Security-Policy from `createCspPolicy`. Exclusive with {@link nonce}. */
+  readonly csp?: CreateWebAppOptions["csp"]
+  /** A per-request CSP nonce resolver. Exclusive with {@link csp}. */
+  readonly nonce?: CreateWebAppOptions["nonce"]
+}
+
+/** The {@link NifraFramework} fields forwarded to `createWebApp` and imported by the generated server
+ * entry, in one list so every command that builds the app forwards the same set. */
+export const FRAMEWORK_WEB_OPTIONS = ["apiPrefix", "apiStrip", "mounts", "csp", "nonce"] as const
+export type FrameworkWebOption = (typeof FRAMEWORK_WEB_OPTIONS)[number]
+
+/** Refuse a forwarded field of the wrong shape at load, naming the field, rather than letting it fail
+ * later inside `createWebApp` or the generated server entry. */
+function assertFrameworkWebOptions(fw: Partial<NifraFramework>, configFile: string): void {
+  const wrong = (field: string, expected: string): never => {
+    throw new Error(`[nifra] ${configFile}: \`${field}\` must be ${expected}.`)
+  }
+  if (fw.apiPrefix !== undefined && typeof fw.apiPrefix !== "string") {
+    wrong("apiPrefix", 'a path string such as "/api", or "" to turn the backend mount off')
+  }
+  if (fw.apiStrip !== undefined && typeof fw.apiStrip !== "boolean") wrong("apiStrip", "a boolean")
+  if (fw.mounts !== undefined && !Array.isArray(fw.mounts)) {
+    wrong("mounts", "an array of { path, app } entries")
+  }
+  if (fw.csp !== undefined && (typeof fw.csp !== "object" || fw.csp === null)) {
+    wrong("csp", "the policy createCspPolicy() returns")
+  }
+  if (fw.nonce !== undefined && typeof fw.nonce !== "function") {
+    wrong("nonce", "a nonce resolver function, such as createNonceResolver() returns")
+  }
+  if (fw.secretExemptions !== undefined && !Array.isArray(fw.secretExemptions)) {
+    wrong("secretExemptions", "an array of { rule, file, reason } entries")
+  }
+  if (fw.target !== undefined && typeof fw.target !== "string") {
+    wrong("target", 'a deploy target name such as "bun"')
+  }
+  if (fw.clientIp !== undefined && fw.clientIp !== "platform") {
+    wrong("clientIp", '"platform" (trust the edge platform\'s client-address header), or left out')
+  }
+  if (fw.dev !== undefined) {
+    if (typeof fw.dev !== "object" || fw.dev === null)
+      wrong("dev", "an object such as { indicator: false }")
+    const indicator: unknown = Reflect.get(fw.dev, "indicator")
+    if (indicator !== undefined && typeof indicator !== "boolean")
+      wrong("dev.indicator", "a boolean")
+  }
 }
 
 /**
@@ -104,8 +183,9 @@ 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
+  /** Absolute path of the config this app was loaded from - `nifra.config.ts`, or
+   * `backend/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
@@ -114,7 +194,7 @@ export interface LoadedApp {
   readonly framework: NifraFramework
   /** Plugin thunks resolved exactly once during app loading and reused by every command phase. */
   readonly resolvedPlugins: ResolvedPlugins
-  /** The `backend` export from `backend.ts`, or `undefined` if there's no `backend.ts`. */
+  /** The `backend` export from `backend/app.ts`, or `undefined` if there's no `backend/app.ts`. */
   readonly backend: unknown
 }
 
@@ -126,7 +206,8 @@ export interface LoadAppOptions {
 /**
  * Root-level monorepo config - exported from `nifra.config.ts` at the workspace root.
  * Each key in `apps` is the short name used to namespace MCP tools (`nifra_<name>_context` etc.);
- * each value is a path relative to the root that contains its own `nifra.config.ts` / `framework.ts`.
+ * each value is a path relative to the root that contains its own `nifra.config.ts` /
+ * `backend/framework.ts`.
  *
  * Example:
  * ```ts
@@ -177,23 +258,48 @@ const isAdapter = (v: unknown): boolean => typeof v === "object" && v !== null
 const importWithQuery = (path: string, query: string | undefined): Promise<unknown> =>
   import(query === undefined || query === "" ? path : `${path}?${query}`)
 
-/** Discover + validate the app conventions rooted at `cwd`. Prefers `nifra.config.ts`, falls back to
- * `framework.ts`. Throws a clear, actionable error if neither exists or the config is malformed. */
+/**
+ * What reads only the backend (`nifra openapi`): the whole app when it has a web config, else
+ * `backend/app.ts` alone, so an API-only app needs no adapter to describe its routes.
+ */
+export async function loadBackendApp(
+  cwd: string,
+  options: LoadAppOptions = {},
+): Promise<Pick<LoadedApp, "cwd" | "backend">> {
+  if (existsSync(resolve(cwd, CONFIG_FILE)) || existsSync(resolve(cwd, FRAMEWORK_FILE))) {
+    return loadApp(cwd, "dist", options)
+  }
+  assertCurrentLayout(cwd)
+  const backendPath = resolve(cwd, BACKEND_APP_FILE)
+  if (!existsSync(backendPath)) {
+    throw new Error(
+      `[nifra] no ${BACKEND_APP_FILE} in ${cwd}: the OpenAPI document describes its routes`,
+    )
+  }
+  const backend = (
+    (await importWithQuery(backendPath, options.importQuery)) as { backend?: unknown }
+  ).backend
+  return { cwd, backend }
+}
+
+/** Discover + validate the app conventions rooted at `cwd`. Prefers `nifra.config.ts`, falls back
+ * to
+ * `backend/framework.ts`. Throws a clear, actionable error if neither exists or the config is
+ * malformed. */
 export async function loadApp(
   cwd: string,
   outDirName = "dist",
   options: LoadAppOptions = {},
 ): Promise<LoadedApp> {
   // nifra.config.ts is the CLI's config (it may import Vite plugins / the SFC compiler, which a
-  // multi-target app keeps OUT of the edge-imported framework.ts). framework.ts is the fallback for a
-  // simple single-target app that has no edge build.
-  const configFile = existsSync(resolve(cwd, "nifra.config.ts"))
-    ? "nifra.config.ts"
-    : "framework.ts"
+  // multi-target app keeps OUT of the edge-imported backend/framework.ts). backend/framework.ts is
+  // the fallback for a simple single-target app that has no edge build.
+  assertCurrentLayout(cwd)
+  const configFile = existsSync(resolve(cwd, CONFIG_FILE)) ? CONFIG_FILE : FRAMEWORK_FILE
   const configPath = resolve(cwd, configFile)
   if (!existsSync(configPath)) {
     throw new Error(
-      `[nifra] no nifra.config.ts or framework.ts found in ${cwd}.\n` +
+      `[nifra] no ${CONFIG_FILE} or ${FRAMEWORK_FILE} found in ${cwd}.\n` +
         "      nifra is zero-config but needs one of them exporting at least:\n" +
         "        export const adapter = reactAdapter            // from @nifrajs/web-react\n" +
         '        export const clientModule = "@nifrajs/web-react/client"\n' +
@@ -211,6 +317,7 @@ export async function loadApp(
       `[nifra] ${configFile} must export \`adapter\` (a render adapter object) and \`clientModule\` (a string).`,
     )
   }
+  assertFrameworkWebOptions(fw, configFile)
   // A `clientModule` given as a RELATIVE path (a local client entry, e.g. `./src/client.tsx`) is
   // resolved to absolute here. It is embedded verbatim as an import specifier in the generated client
   // entry, and `nifra dev` and `nifra build` write that entry into DIFFERENT directories - so a relative
@@ -251,7 +358,7 @@ export async function loadApp(
   assertPipelineSeparation(resolvedPlugins, configFile)
 
   let backend: unknown
-  const backendPath = resolve(cwd, "backend.ts")
+  const backendPath = resolve(cwd, BACKEND_APP_FILE)
   if (existsSync(backendPath)) {
     backend = ((await importWithQuery(backendPath, options.importQuery)) as { backend?: unknown })
       .backend