@nifrajs/cli 3.3.0 → 4.0.0

package/src/introspect.ts

@@ -7,74 +7,25 @@
 
 import { reservedKeyFor } from "@nifrajs/client"
 import {
-  type ProjectEvidenceSchema,
   type ProjectEvidenceSchemaPart,
   type ProjectEvidenceSnapshot,
+  reflectedRoutesFromEvidence,
   snapshotProjectEvidence,
 } from "@nifrajs/core/evidence"
-import type { ReflectedRoute, SchemaReflection } from "@nifrajs/core/reflection"
+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"
 
 /** Read the backend's registered routes, if it's a `server()` with a `.routes()` method. */
-export function backendRoutes(backend: unknown): ReflectedRoute[] {
+export function backendRoutes(backend: unknown): readonly ReflectedRoute[] {
   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 {
   readonly type?: unknown
   readonly properties?: Record<string, unknown>
@@ -154,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.
@@ -163,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
@@ -176,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.
  *
@@ -188,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
@@ -205,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
@@ -223,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). */
@@ -237,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")}`
 }
@@ -259,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
@@ -355,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)
@@ -425,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}/`)
 }
 
@@ -442,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"]
@@ -451,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())
   }
@@ -469,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(",")),
   )
 }
 
@@ -499,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,
@@ -595,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: "/" },
@@ -695,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)"