@nifrajs/cli 4.0.0 → 5.0.0

package/src/introspect.ts

@@ -13,12 +13,12 @@ import {
   snapshotProjectEvidence,
 } from "@nifrajs/core/evidence"
 import { compileRoutePattern, type RoutePatternSegment } from "@nifrajs/core/pattern"
-import type { ReflectedRoute } from "@nifrajs/core/reflection"
+import type { ReflectedMount, 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 type { IntrospectedApp } 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. */
@@ -225,6 +225,22 @@ export function apiRoutesIndexSection(routes: readonly ReflectedRoute[]): string
   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")}`
 }
 
+/** The routes opaque mounts declare, under `prefix`, or `undefined` when there are none. Listed apart
+ * from the API routes: nifra serves them but never analyzed them. */
+function declaredMountRoutesSection(
+  mounts: readonly ReflectedMount[],
+  prefix: string | undefined,
+): string | undefined {
+  const lines = mounts.flatMap((mount) =>
+    (mount.routes ?? [])
+      .filter((route) => prefix === undefined || route.path.startsWith(prefix))
+      .map((route) => `- \`${route.method} ${route.path}\` - ${mount.path} (${mount.opaque})`),
+  )
+  return lines.length === 0
+    ? undefined
+    : `## Declared by opaque mounts (not analyzed)\n\n${lines.join("\n")}`
+}
+
 /** Markdown section listing the file-routed pages (URL pattern → source file). */
 export function pageRoutesSection(manifest: Manifest | undefined): string {
   if (!manifest || manifest.routes.length === 0) {
@@ -236,6 +252,10 @@ export function pageRoutesSection(manifest: Manifest | undefined): string {
   return `## Page routes (routes/)\n\n${lines.join("\n")}`
 }
 
+const PAGES_CONVENTION = `- **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.`
+
 const CONVENTIONS = `## Conventions (summary)
 
 - **Backend:** \`server()\` from \`@nifrajs/core\`; returning a value sends JSON. Validate untrusted input with
@@ -253,9 +273,7 @@ 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/\`. 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.
+${PAGES_CONVENTION}
 - \`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
@@ -274,15 +292,18 @@ export interface ContextFilter {
  * body/query/response shapes + the typed-client `call` form), and omits the conventions block (the agent
  * already has it from the index call).
  */
-export function describeProject(app: LoadedApp, filter?: ContextFilter): string {
+export function describeProject(app: IntrospectedApp, filter?: ContextFilter): string {
   let manifest: Manifest | undefined
-  try {
-    manifest = discoverRoutes(app.routesDir)
-  } catch {
-    // No (or unreadable) routes/ - the page-routes section reports that.
+  if (app.framework !== undefined) {
+    try {
+      manifest = discoverRoutes(app.routesDir)
+    } catch {
+      // No (or unreadable) routes/ - the page-routes section reports that.
+    }
   }
   const prefix = filter?.path
-  let routes = backendRoutes(app.backend)
+  const evidence = snapshotProjectEvidence(app.backend)
+  let routes = reflectedRoutesFromEvidence(evidence)
   let pages = manifest
   if (prefix !== undefined && prefix !== "") {
     routes = routes.filter((r) => r.path.startsWith(prefix))
@@ -296,20 +317,34 @@ export function describeProject(app: LoadedApp, filter?: ContextFilter): string
   const sections: string[] = [`# nifra project: ${app.cwd.slice(app.cwd.lastIndexOf("/") + 1)}`]
   if (isIndex) {
     sections.push(
-      "A full-stack nifra app - Web-standard, one app on Bun, Node, Deno, and the edge. This is the route INDEX; fetch a route's full body/query/response contract on demand (see below).",
+      app.framework === undefined
+        ? "An API-only nifra app (backend/app.ts, no web config) - Web-standard, one backend on Bun, Node, Deno, and the edge. This is the route INDEX; fetch a route's full body/query/response contract on demand (see below)."
+        : "A full-stack nifra app - Web-standard, one app on Bun, Node, Deno, and the edge. This is the route INDEX; fetch a route's full body/query/response contract on demand (see below).",
       // 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`.",
+    )
+    if (app.framework !== undefined) {
       // 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.`,
-    )
+      sections.push(
+        `**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") {
     // Index → compact `METHOD path` list; a slice → the full schema + call-form detail.
     sections.push(isIndex ? apiRoutesIndexSection(routes) : apiRoutesSection(routes))
+    const declared = declaredMountRoutesSection(evidence.mounts ?? [], prefix || undefined)
+    if (declared !== undefined) sections.push(declared)
+  }
+  if (app.framework === undefined) {
+    if (filter?.kind === "pages")
+      sections.push("## Page routes\n\nAn API-only app serves no pages.")
+    if (isIndex) sections.push(CONVENTIONS.replace(`${PAGES_CONVENTION}\n`, ""))
+    return sections.join("\n\n")
   }
   if (filter?.kind !== "api") sections.push(pageRoutesSection(pages))
   if (isIndex) sections.push(CONVENTIONS)
@@ -368,7 +403,7 @@ export function routesToJsonFromEvidence(
 }
 
 export function routesToJson(
-  app: LoadedApp,
+  app: IntrospectedApp,
   pathPrefix?: string,
   evidence?: ProjectEvidenceSnapshot,
 ): RouteJson[] {
@@ -382,7 +417,7 @@ export function routesToJson(
 // `nifra routes` answers a different question: "what does this app actually serve, and with which
 // methods?" - so an agent sees instantly that `POST /api/explain` is (or isn't) mounted, instead of
 // discovering it via a 405. It marks which backend routes are AUTO-MOUNTED under the page router's
-// `apiPrefix` (default `/api`), and `--json` makes it machine-consumable. The table-building +
+// `apiPrefix`, and `--json` makes it machine-consumable. The table-building +
 // rendering are pure (no fs / no module loads), so they're unit-tested; the cwd gathering is the thin
 // async wrapper `describeRoutes`.
 // ===================================================================================================
@@ -416,7 +451,7 @@ export interface PageRouteInput {
 export interface RouteTableInput {
   readonly pages: readonly PageRouteInput[]
   readonly api: ReadonlyArray<Pick<ReflectedRoute, "method" | "path">>
-  /** The page router's `apiPrefix` (default `/api`); an API route at/under it is auto-mounted. `""`
+  /** The page router's `apiPrefix`; an API route at/under it is auto-mounted. Unset or `""`
    * 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
@@ -440,7 +475,7 @@ function isUnderPrefix(path: string, prefix: string): boolean {
  * joined methods, for stable output.
  */
 export function buildRouteTable(input: RouteTableInput): RouteTableEntry[] {
-  const configured = input.apiPrefix ?? "/api"
+  const configured = input.apiPrefix ?? ""
   // 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 !== ""
@@ -683,12 +718,15 @@ interface MaybeActionModule {
  * text (default) or JSON (`--json`). The page-route load mirrors what SSR would do; a load failure
  * degrades to GET-only for that route (never throws the whole command).
  */
-async function collectRouteTable(app: LoadedApp): Promise<RouteTableEntry[]> {
+async function collectRouteTable(app: IntrospectedApp): Promise<RouteTableEntry[]> {
+  const { framework } = app
   let manifest: Manifest | undefined
-  try {
-    manifest = discoverRoutes(app.routesDir)
-  } catch {
-    // No (or unreadable) routes/ - fall through with no pages; the table still shows API routes.
+  if (framework !== undefined) {
+    try {
+      manifest = discoverRoutes(app.routesDir)
+    } catch {
+      // No (or unreadable) routes/ - fall through with no pages; the table still shows API routes.
+    }
   }
   const pages: PageRouteInput[] = []
   for (const route of manifest?.routes ?? []) {
@@ -704,14 +742,14 @@ async function collectRouteTable(app: LoadedApp): Promise<RouteTableEntry[]> {
   const rows = buildRouteTable({
     pages,
     api: backendRoutes(app.backend),
-    ...(app.framework.apiPrefix !== undefined ? { apiPrefix: app.framework.apiPrefix } : {}),
-    ...(app.framework.apiStrip !== undefined ? { apiStrip: app.framework.apiStrip } : {}),
+    ...(framework?.apiPrefix !== undefined ? { apiPrefix: framework.apiPrefix } : {}),
+    ...(framework?.apiStrip !== undefined ? { apiStrip: framework.apiStrip } : {}),
   })
   return rows
 }
 
 export async function describeRoutes(
-  app: LoadedApp,
+  app: IntrospectedApp,
   opts: { readonly json?: boolean } = {},
 ): Promise<string> {
   const rows = await collectRouteTable(app)
@@ -720,7 +758,7 @@ export async function describeRoutes(
 
 /** Gather and render the public route graph for `nifra routes --graph`. */
 export async function describeRouteGraph(
-  app: LoadedApp,
+  app: IntrospectedApp,
   opts: { readonly json?: boolean } = {},
 ): Promise<string> {
   const graph = buildRouteGraph(await collectRouteTable(app))

package/src/levels-tool.ts

@@ -13,10 +13,19 @@
 
 import { existsSync } from "node:fs"
 import { resolve } from "node:path"
-import type { AssuranceReport } from "@nifrajs/core/assurance"
+import type {
+  AssuranceReport,
+  InvariantSetup,
+  InvariantSetupResult,
+  InvariantsConfig,
+} from "@nifrajs/core/assurance"
 import { snapshotCapabilities } from "@nifrajs/core/capabilities"
 import { buildNifraManifest, parseNifraManifest } from "@nifrajs/core/manifest"
-import { type ContractTestApp, runAdversarialContract } from "@nifrajs/testing"
+import {
+  type AdversarialContractOptions,
+  type ContractTestApp,
+  runAdversarialContract,
+} from "@nifrajs/testing"
 import {
   type CapabilityProjectReport,
   diffCapabilitySnapshots,
@@ -176,41 +185,129 @@ export async function collectVerificationLevels(
       "no isolated invariant executor configured - add `invariants.executor` in nifra.assurance.ts",
     )
   } else {
-    const invariants = await runAdversarialContract(config.source as ContractTestApp, {
-      seed: options.seed ?? 1,
-      runtimes: [{ name: "isolated", fetch: config.invariants.executor }],
-      expectedValidationStatuses: [400, 422],
-      requireCoverage: true,
+    l4Reasons.push(...(await runInvariants(config.source, config.invariants, options.seed ?? 1)))
+  }
+  statuses.push({
+    level: 4,
+    name: "invariant-tested",
+    ok: l4Reasons.length === 0,
+    reasons: l4Reasons,
+  })
+
+  return finalize(statuses, assurance.routes)
+}
+
+/**
+ * Run L4 against the configured target. `setup` runs at most once, on the first request, and its
+ * `teardown` runs once the run ends - after a failure too - so an app can provision a throwaway target
+ * only when L4 actually exercises it.
+ */
+async function runInvariants(
+  source: unknown,
+  invariants: InvariantsConfig,
+  seed: number,
+): Promise<string[]> {
+  let provisioned: Promise<InvariantSetupResult | undefined> | undefined
+  const provision = (setup: InvariantSetup): Promise<InvariantSetupResult | undefined> => {
+    provisioned ??= Promise.resolve()
+      .then(setup)
+      .then(
+        (result) => result ?? undefined,
+        (error: unknown) => {
+          throw new Error(`invariants.setup failed: ${messageOf(error)}`)
+        },
+      )
+    return provisioned
+  }
+  const fetch = async (request: Request): Promise<Response> => {
+    const ready = invariants.setup === undefined ? undefined : await provision(invariants.setup)
+    const executor = ready?.executor ?? invariants.executor
+    if (executor === undefined) {
+      throw new Error(
+        "no invariant executor: invariants.setup returned none and invariants.executor is not set",
+      )
+    }
+    return executor(request)
+  }
+  const options: AdversarialContractOptions = {
+    seed,
+    runtimes: [{ name: "isolated", fetch }],
+    expectedValidationStatuses: [400, 422],
+    requireCoverage: true,
+  }
+  const runOptions: Record<string, unknown> = {}
+  for (const name of INVARIANT_RUN_OPTIONS) {
+    if (invariants[name] !== undefined) runOptions[name] = invariants[name]
+  }
+  const reasons: string[] = []
+  try {
+    const report = await runAdversarialContract(source as ContractTestApp, {
+      ...options,
+      ...runOptions,
     })
-    if (!invariants.ok) {
-      l4Reasons.push(
-        ...invariants.failures
+    const target = await targetFailure(provisioned, invariants)
+    if (target !== undefined) reasons.push(target)
+    else if (!report.ok) {
+      reasons.push(
+        ...report.failures
           .slice(0, 5)
           .map(
             (failure) =>
               `${failure.runtime}: ${failure.id} - ${failure.message} (replay seed ${failure.replay.seed})`,
           ),
       )
-      l4Reasons.push(
-        ...invariants.gaps
-          .slice(0, Math.max(0, 5 - l4Reasons.length))
+      reasons.push(
+        ...report.gaps
+          .slice(0, Math.max(0, 5 - reasons.length))
           .map(
             (gap) =>
               `${gap.route ?? "contract"}${gap.target ? ` ${gap.target}` : ""}: ${gap.message}`,
           ),
       )
     }
+  } catch (error) {
+    reasons.push((await targetFailure(provisioned, invariants)) ?? messageOf(error))
+  } finally {
+    const ready = await provisioned?.catch(() => undefined)
+    if (ready?.teardown !== undefined) {
+      try {
+        await ready.teardown()
+      } catch (error) {
+        reasons.push(`invariants teardown failed: ${messageOf(error)}`)
+      }
+    }
   }
-  statuses.push({
-    level: 4,
-    name: "invariant-tested",
-    ok: l4Reasons.length === 0,
-    reasons: l4Reasons,
-  })
+  return reasons
+}
 
-  return finalize(statuses, assurance.routes)
+const INVARIANT_RUN_OPTIONS = [
+  "witnesses",
+  "prepareRequest",
+  "isRejected",
+  "include",
+  "maxMutationsPerInput",
+] as const
+
+/** The setup or missing-executor failure every case hit, if the target never came up. */
+async function targetFailure(
+  provisioned: Promise<InvariantSetupResult | undefined> | undefined,
+  invariants: InvariantsConfig,
+): Promise<string | undefined> {
+  if (provisioned === undefined) return undefined
+  try {
+    const ready = await provisioned
+    if (ready?.executor === undefined && invariants.executor === undefined) {
+      return "no invariant executor: invariants.setup returned none and invariants.executor is not set"
+    }
+    return undefined
+  } catch (error) {
+    return messageOf(error)
+  }
 }
 
+const messageOf = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error)
+
 function finalize(
   statuses: readonly { level: number; name: string; ok: boolean; reasons: string[] }[],
   routes: readonly { readonly responseContract?: "enforce" | "warn" | "unchecked" }[],

package/src/load.ts

@@ -40,6 +40,12 @@ export type PluginsField =
  * don't).
  */
 export interface NifraFramework {
+  /** Optional coordinated Vite 8 component graph. Tooling stays in nifra.config.ts. */
+  readonly componentPipeline?: Omit<
+    import("@nifrajs/web/server-components/build").ComponentPipelineOptions,
+    "root" | "outDir" | "port" | "plugins"
+  >
+  readonly serverComponents?: CreateWebAppOptions["serverComponents"]
   /** The render adapter, e.g. `reactAdapter` from `@nifrajs/web-react`. */
   readonly adapter: unknown
   /** The client runtime module providing `mountRouter`, e.g. `"@nifrajs/web-react/client"`. */
@@ -72,8 +78,11 @@ export interface NifraFramework {
    * 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 }
+   * (`nifra dev --no-indicator` does it for one); browser errors still reach `nifra errors`.
+   * `allowedHosts` lists host names the Bun dev server answers besides loopback ones; it refuses
+   * every other `Host` so a DNS-rebound page cannot read it. The Vite pipeline uses Vite's own
+   * `server.allowedHosts`. */
+  readonly dev?: { readonly indicator?: boolean; readonly allowedHosts?: readonly string[] }
   /** Static files directory. Defaults to `<app>/public`; `false` disables it. */
   readonly publicDir?: string | false
   /** Client-visible environment prefix (default `"PUBLIC_"`; empty disables exposure). */
@@ -85,9 +94,9 @@ export interface NifraFramework {
   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.
+  /** Path `backend/app.ts`'s backend is served at over HTTP, such as `"/api"`; unset or `""`, it is
+   * not mounted. 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). */
@@ -106,7 +115,14 @@ export interface NifraFramework {
 
 /** 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 const FRAMEWORK_WEB_OPTIONS = [
+  "apiPrefix",
+  "apiStrip",
+  "mounts",
+  "csp",
+  "nonce",
+  "serverComponents",
+] 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
@@ -115,6 +131,24 @@ function assertFrameworkWebOptions(fw: Partial<NifraFramework>, configFile: stri
   const wrong = (field: string, expected: string): never => {
     throw new Error(`[nifra] ${configFile}: \`${field}\` must be ${expected}.`)
   }
+  if (fw.componentPipeline !== undefined) {
+    const pipeline = fw.componentPipeline
+    if (
+      typeof pipeline !== "object" ||
+      pipeline === null ||
+      !["react", "vue", "svelte", "solid", "preact"].includes(pipeline.adapter) ||
+      typeof pipeline.entries !== "object" ||
+      pipeline.entries === null ||
+      typeof pipeline.entries.client !== "string" ||
+      typeof pipeline.entries.ssr !== "string" ||
+      (pipeline.adapter === "react" && typeof pipeline.entries.rsc !== "string") ||
+      (pipeline.adapter !== "react" && pipeline.entries.rsc !== undefined)
+    )
+      wrong(
+        "componentPipeline",
+        "an adapter plus existing client/ssr entries and a React-only rsc entry",
+      )
+  }
   if (fw.apiPrefix !== undefined && typeof fw.apiPrefix !== "string") {
     wrong("apiPrefix", 'a path string such as "/api", or "" to turn the backend mount off')
   }
@@ -143,6 +177,13 @@ function assertFrameworkWebOptions(fw: Partial<NifraFramework>, configFile: stri
     const indicator: unknown = Reflect.get(fw.dev, "indicator")
     if (indicator !== undefined && typeof indicator !== "boolean")
       wrong("dev.indicator", "a boolean")
+    const allowedHosts: unknown = Reflect.get(fw.dev, "allowedHosts")
+    if (
+      allowedHosts !== undefined &&
+      (!Array.isArray(allowedHosts) ||
+        allowedHosts.some((host) => typeof host !== "string" || host.trim() === ""))
+    )
+      wrong("dev.allowedHosts", 'an array of host names such as ["app.test"]')
   }
 }
 
@@ -198,6 +239,23 @@ export interface LoadedApp {
   readonly backend: unknown
 }
 
+/** An API-only app as the backend readers see it: `backend/app.ts` and no web config. */
+export interface BackendOnlyApp {
+  readonly cwd: string
+  readonly backend: unknown
+  readonly framework?: undefined
+}
+
+/** What the backend readers (routes, context, hooks, OpenAPI, the app's MCP surface) load. */
+export type IntrospectedApp = LoadedApp | BackendOnlyApp
+
+/** How a command reaches the app. The MCP server hands out one whose calls both refuse. */
+export interface AppLoader {
+  (outDirName?: string): Promise<LoadedApp>
+  /** The whole app with a web config, else `backend/app.ts` alone. */
+  readonly backend: () => Promise<IntrospectedApp>
+}
+
 export interface LoadAppOptions {
   /** Optional dynamic-import query used by long-lived MCP processes to bust Bun's module cache. */
   readonly importQuery?: string
@@ -258,22 +316,24 @@ 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}`)
 
+/** Whether `cwd` has a web config file, the one thing that makes it more than its backend. */
+export const hasAppConfig = (cwd: string): boolean =>
+  existsSync(resolve(cwd, CONFIG_FILE)) || existsSync(resolve(cwd, FRAMEWORK_FILE))
+
 /**
- * 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.
+ * What reads only the backend: the whole app when it has a web config, else `backend/app.ts`
+ * alone, so an API-only app needs no adapter for its routes, context, hooks or OpenAPI document.
  */
 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)
-  }
+): Promise<IntrospectedApp> {
+  if (hasAppConfig(cwd)) 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`,
+      `[nifra] no ${CONFIG_FILE}, ${FRAMEWORK_FILE} or ${BACKEND_APP_FILE} in ${cwd}: a web app needs its config, an API-only app its ${BACKEND_APP_FILE}`,
     )
   }
   const backend = (
@@ -303,7 +363,11 @@ export async function loadApp(
         "      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' +
-        "      (create-nifra scaffolds this for you.)",
+        "      (create-nifra scaffolds this for you.)" +
+        (existsSync(resolve(cwd, BACKEND_APP_FILE))
+          ? `\n      With ${BACKEND_APP_FILE} and no web config this is an API-only app: \`nifra routes\`,\n` +
+            "      `nifra context`, `nifra openapi` and `nifra mcp` read its backend; pages need the config."
+          : ""),
     )
   }
   if (!existsSync(resolve(cwd, "routes"))) {

package/src/mcp-context.ts

@@ -8,7 +8,7 @@
 import { realpathSync } from "node:fs"
 import { readFile } from "node:fs/promises"
 import { basename, isAbsolute, relative, resolve } from "node:path"
-import type { LoadedApp } from "./load.ts"
+import type { AppLoader } from "./load.ts"
 import { createCachedAppLoader } from "./mcp-exec.ts"
 import { resolveMcpProjectPath } from "./mcp-path.ts"
 import type { McpPrompt, McpResource, McpServerFeatures, McpTool } from "./mcp-protocol.ts"
@@ -20,11 +20,11 @@ function openApiFormat(args: Record<string, unknown>): "json" | "yaml" {
 
 export async function openApiHandler(
   args: Record<string, unknown>,
-  loadAppCached: (outDirName?: string) => Promise<LoadedApp>,
+  loadAppCached: AppLoader,
 ): Promise<string> {
   const { renderOpenApiWithTypes } = await import("./openapi-tool.ts")
   const pathPrefix = typeof args.path === "string" ? args.path : undefined
-  return renderOpenApiWithTypes(await loadAppCached(), openApiFormat(args), pathPrefix)
+  return renderOpenApiWithTypes(await loadAppCached.backend(), openApiFormat(args), pathPrefix)
 }
 
 async function readProjectFile(
@@ -57,7 +57,7 @@ function promptText(
 
 export function projectResources(
   cwd: string,
-  loadAppCached: (outDirName?: string) => Promise<LoadedApp> = createCachedAppLoader(cwd),
+  loadAppCached: AppLoader = createCachedAppLoader(cwd),
 ): McpResource[] {
   return [
     {
@@ -68,7 +68,7 @@ export function projectResources(
       mimeType: "application/json",
       read: async () => {
         const { routesToJson } = await import("./introspect.ts")
-        return { text: JSON.stringify(routesToJson(await loadAppCached()), null, 2) }
+        return { text: JSON.stringify(routesToJson(await loadAppCached.backend()), null, 2) }
       },
     },
     {
@@ -165,7 +165,7 @@ export function projectPrompts(): McpPrompt[] {
 
 export function projectFeatures(
   cwd: string,
-  loadAppCached: (outDirName?: string) => Promise<LoadedApp> = createCachedAppLoader(cwd),
+  loadAppCached: AppLoader = createCachedAppLoader(cwd),
 ): McpServerFeatures {
   return { resources: projectResources(cwd, loadAppCached), prompts: projectPrompts() }
 }
@@ -218,7 +218,7 @@ export function dirError(dir: string | undefined): string {
 /** Build the project-scoped tools for `cwd`. */
 export interface CommandMcpToolOptions {
   readonly cwd: string
-  readonly loadAppCached?: () => Promise<LoadedApp>
+  readonly loadAppCached?: AppLoader
 }
 
 /** Adapt one executable catalog spec to its MCP descriptor and project-scoped handler. */