@nifrajs/cli 4.0.0 → 5.0.0

package/src/db-tool.ts

@@ -34,8 +34,10 @@ import { readProjectEnv } from "./db-config.ts"
 import {
   CHILD_OUTPUT_MAX_BYTES,
   CHILD_TIMEOUT_MS,
+  OWN_PROCESS_GROUP,
   readBoundedLines,
   readBoundedStream,
+  signalProcessGroup,
 } from "./mcp-io.ts"
 
 /** Added to the declared `timeoutMs` before the subprocess is killed. */
@@ -134,12 +136,13 @@ export async function runDbChild(
     stdin: "pipe",
     stdout: "pipe",
     stderr: "pipe",
+    detached: OWN_PROCESS_GROUP,
   })
   let killedFor: "startup" | "deadline" | "cancel" | undefined
   const kill = (reason: NonNullable<typeof killedFor>): void => {
     if (killedFor !== undefined) return
     killedFor = reason
-    proc.kill("SIGKILL")
+    signalProcessGroup(proc, "SIGKILL")
   }
   let deadlineMs: number | undefined
   let timer = setTimeout(() => kill("startup"), startupMs)
@@ -565,7 +568,7 @@ export interface DbRoleInput {
 export const dbRoleSpec: CommandSpec<DbRoleInput, DbToolOutput> = {
   name: "db-role",
   summary:
-    "Print the SQL that creates a read-only Postgres role for the declared development database (pg_read_all_data on 14+, else GRANT SELECT, with a REVOKE per excluded table). Nothing is run.",
+    "Print the SQL that creates a read-only Postgres role for the declared development database (GRANT SELECT on each allowed schema, with a REVOKE per excluded table). Nothing is run.",
   input: {
     jsonSchema: {
       type: "object",

package/src/dev-bun-config.ts

@@ -42,10 +42,29 @@
 import { timingSafeEqual } from "node:crypto"
 import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs"
 import { relative, resolve } from "node:path"
+import { readSingleCopyDeclaration } from "@nifrajs/core/single-copy"
 
-/** TOML string literal: basic (double-quoted) form with the two escapes it needs. */
+const TOML_ESCAPES: Readonly<Record<string, string>> = {
+  "\\": "\\\\",
+  '"': '\\"',
+  "\b": "\\b",
+  "\t": "\\t",
+  "\n": "\\n",
+  "\f": "\\f",
+  "\r": "\\r",
+}
+
+/** TOML string literal: basic (double-quoted) form. A basic string may hold no raw control
+ * character, so each one is escaped along with the quote and the backslash. */
 function tomlString(value: string): string {
-  return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`
+  let out = '"'
+  for (const char of value) {
+    const code = char.charCodeAt(0)
+    out +=
+      TOML_ESCAPES[char] ??
+      (code < 0x20 || code === 0x7f ? `\\u${code.toString(16).padStart(4, "0")}` : char)
+  }
+  return `${out}"`
 }
 
 /** A parsed bunfig: plain data from `Bun.TOML.parse`. */
@@ -198,24 +217,40 @@ function relativeSpecifier(fromDir: string, target: string): string {
  * `servePlugins` are the app's own bunfig `[serve.static] plugins`, composed last and in order rather
  * than listed beside this module, so that every plugin reaching the bundler registers through
  * `reserveDevSpecifiers` (see `@nifrajs/web/internal/dev-reserved`).
+ *
+ * `singleCopy` is whether `package.json` declares `"nifra": { "singleCopy": [...] }`. The declared
+ * resolver then runs where `buildClient` runs it, after the zone guard; an app that also lists
+ * `singleCopyPlugin()` in `clientPlugins` gets its own instance in that place, once.
  */
 export function renderBoundaryPluginModule(
   configPath?: string,
   pluginDir?: string,
   servePlugins: readonly string[] = [],
+  singleCopy = false,
 ): string {
   const appImport =
     configPath !== undefined && pluginDir !== undefined
       ? `import * as appConfig from ${tomlString(relativeSpecifier(pluginDir, configPath))}\n`
       : ""
-  const appSetup =
+  const appPluginsSetup =
     appImport === ""
-      ? ""
+      ? "    const appPlugins = []\n"
       : `    // The app's OWN client transforms (SFC compilers etc.). \`clientPlugins\` may be a thunk.
     const field = appConfig.clientPlugins
     const appPlugins = (typeof field === "function" ? await field() : field) ?? []
-    for (const p of appPlugins) await p.setup(guarded)
 `
+  const singleCopySetup = singleCopy
+    ? `    const listedSingleCopy = appPlugins.find((p) => p?.name === "nifra-single-copy")
+    ;(listedSingleCopy ?? singleCopyPlugin({ cwd: appRoot })).setup(guarded)
+`
+    : ""
+  // Without a declaration the app's plugins are read where they are set up, as before.
+  const appSetup =
+    appImport === ""
+      ? ""
+      : singleCopy
+        ? "    for (const p of appPlugins) if (p !== listedSingleCopy) await p.setup(guarded)\n"
+        : `${appPluginsSetup}    for (const p of appPlugins) await p.setup(guarded)\n`
   const serveSetup =
     servePlugins.length === 0
       ? ""
@@ -232,10 +267,11 @@ export function renderBoundaryPluginModule(
 import { serverFnStubPlugin, zoneGuardPlugin } from "@nifrajs/web/build"
 import { reserveDevSpecifiers } from "@nifrajs/web/internal/dev-reserved"
 import { cssModulesBunPlugin } from "@nifrajs/web/plugins/css-modules"
-${appImport}
+${singleCopy ? 'import { singleCopyPlugin } from "@nifrajs/core/single-copy"\n' : ""}${appImport}
 // This module lives at <app>/.nifra/dev-bun/, so the app root is two directories up.
+const appRoot = Bun.fileURLToPath(new URL("../../", import.meta.url))
 const zones = zoneGuardPlugin({
-  appRoot: Bun.fileURLToPath(new URL("../../", import.meta.url)),${
+  appRoot,${
     appImport === ""
       ? ""
       : `
@@ -251,10 +287,10 @@ export default {
     // Every plugin below registers through this view: a resolve filter matching the dev entry script
     // or Bun's built-in React refresh runtime breaks the page even when its handler declines.
     const guarded = reserveDevSpecifiers(build)
-    // Boundary first: an app plugin must never get to transform a module that the boundary is about
+${singleCopy ? appPluginsSetup : ""}    // Boundary first: an app plugin must never get to transform a module that the boundary is about
     // to refuse or stub, or the transform decides what ships instead of the boundary.
     zones.setup(guarded)
-    fn.setup(guarded)
+${singleCopySetup}    fn.setup(guarded)
     cssModules.setup(guarded)
 ${appSetup}${serveSetup}  },
 }
@@ -287,7 +323,12 @@ export async function writeBunDevConfig(
   const user = parseUserBunfig(userToml)
   writeFileSync(
     pluginPath,
-    renderBoundaryPluginModule(configPath, dir, userServePlugins(user, appRoot)),
+    renderBoundaryPluginModule(
+      configPath,
+      dir,
+      userServePlugins(user, appRoot),
+      readSingleCopyDeclaration(appRoot) !== undefined,
+    ),
   )
   const bunfigPath = resolve(dir, "bunfig.toml")
   writeFileSync(bunfigPath, renderDevBunfig(pluginPath, user, appRoot, define))

package/src/diagnostics.ts

@@ -21,6 +21,9 @@ export interface DiagnosticCompatibility {
   readonly suggestion?: DiagnosticSuggestion
   /** The import path evidence used by the legacy server-only-import view. */
   readonly chain?: readonly string[]
+  /** The project files a server-only chain runs through, so a diff review keeps a finding whose
+   * route is unchanged but whose chain a changed module made. */
+  readonly modules?: readonly string[]
   /** Preserve the old optional `CheckDiagnostic.code` field exactly where it existed. */
   readonly includeCode?: boolean
 }

package/src/diff-tool.ts

@@ -14,8 +14,8 @@
  * framework config or routes/ directory (unlike the eager `loadApp`).
  */
 
-import { existsSync } from "node:fs"
-import { resolve } from "node:path"
+import { existsSync, realpathSync } from "node:fs"
+import { isAbsolute, relative, resolve } from "node:path"
 import {
   diffRouteSnapshots,
   type RouteChange,
@@ -23,7 +23,7 @@ import {
   type RoutesDiff,
   snapshotRoutes,
 } from "@nifrajs/core/diff"
-import { BACKEND_APP_FILE } from "./app-files.ts"
+import { assertCurrentLayout, BACKEND_APP_FILE } from "./app-files.ts"
 
 /** Snapshot file envelope - versioned so a future format change can migrate instead of misparse. */
 export interface SnapshotFile {
@@ -84,6 +84,7 @@ export function formatDiff(diff: RoutesDiff): string {
 
 /** Import `backend/app.ts` from `cwd` and snapshot its routes. */
 export async function snapshotBackend(cwd: string): Promise<readonly RouteSnapshot[]> {
+  assertCurrentLayout(cwd)
   const backendPath = resolve(cwd, BACKEND_APP_FILE)
   if (!existsSync(backendPath)) {
     throw new Error(
@@ -97,35 +98,41 @@ export async function snapshotBackend(cwd: string): Promise<readonly RouteSnapsh
   return snapshotRoutes(backend)
 }
 
-/** `nifra snapshot`: write the current contract as the CI baseline. */
-export async function runSnapshot(cwd: string, options: { out?: string }): Promise<void> {
-  const routes = await snapshotBackend(cwd)
-  const file: SnapshotFile = { nifraSnapshot: 1, routes }
-  const outPath = resolve(cwd, options.out ?? DEFAULT_SNAPSHOT_FILE)
-  await Bun.write(outPath, `${JSON.stringify(file, null, 2)}\n`)
-  console.log(`[nifra] wrote ${routes.length} route${routes.length === 1 ? "" : "s"} to ${outPath}`)
+/** `nifra snapshot`: write the current contract to `out` (from `cwd`) as the CI baseline. */
+export async function writeSnapshot(
+  cwd: string,
+  out: string = DEFAULT_SNAPSHOT_FILE,
+): Promise<SnapshotFile> {
+  const snapshot: SnapshotFile = { nifraSnapshot: 1, routes: await snapshotBackend(cwd) }
+  await Bun.write(resolve(cwd, out), `${JSON.stringify(snapshot, null, 2)}\n`)
+  return snapshot
+}
+
+const outside = (root: string, target: string): boolean => {
+  const rel = relative(root, target)
+  return rel.startsWith("..") || isAbsolute(rel)
 }
 
-/** `nifra diff`: compare the current contract against a baseline. Returns false on breaking changes. */
-export async function runDiff(
+/**
+ * `nifra diff`: the current contract against the snapshot at `baselinePath` (from `cwd`). `contain`
+ * refuses a baseline outside `cwd`, symlinks followed, for a caller handed the path by someone else.
+ */
+export async function diffAgainstBaseline(
   cwd: string,
-  baselinePath: string,
-  options: { json?: boolean },
-): Promise<boolean> {
+  baselinePath: string = DEFAULT_SNAPSHOT_FILE,
+  options: { readonly contain?: boolean } = {},
+): Promise<RoutesDiff> {
   const resolved = resolve(cwd, baselinePath)
-  const baselineFile = Bun.file(resolved)
-  if (!(await baselineFile.exists())) {
+  const refuse = (): never => {
+    throw new Error(`[nifra] the baseline ${baselinePath} is outside the project directory`)
+  }
+  if (options.contain === true && outside(resolve(cwd), resolved)) refuse()
+  if (!existsSync(resolved)) {
     throw new Error(
       `[nifra] baseline not found: ${resolved} - create it on your main branch with \`nifra snapshot\`.`,
     )
   }
-  const baseline = parseSnapshotFile(await baselineFile.text(), baselinePath)
-  const current = await snapshotBackend(cwd)
-  const diff = diffRouteSnapshots(baseline.routes, current)
-  if (options.json === true) {
-    console.log(JSON.stringify({ hasBreaking: diff.hasBreaking, changes: diff.changes }, null, 2))
-  } else {
-    console.log(formatDiff(diff))
-  }
-  return !diff.hasBreaking
+  if (options.contain === true && outside(realpathSync(cwd), realpathSync(resolved))) refuse()
+  const baseline = parseSnapshotFile(await Bun.file(resolved).text(), baselinePath)
+  return diffRouteSnapshots(baseline.routes, await snapshotBackend(cwd))
 }

package/src/doctor.ts

@@ -29,11 +29,20 @@ import {
   resolvedInstalledCopy,
 } from "@nifrajs/web/internal/parity"
 import { codePositionMask, type SourceFinding, stripComments, walkSource } from "./check.ts"
+import {
+  type HandBuiltManifest,
+  handBuiltManifestMessage,
+  handBuiltManifests,
+  type ManifestList,
+  manifestListsIn,
+} from "./hand-built-manifest.ts"
 import { collectStaleMcpPins, type StaleMcpPin } from "./init-agents.ts"
 import { codeUnitOrder } from "./internal/code-unit-order.ts"
+import { createSpecifierResolver } from "./internal/project-specifiers.ts"
 import { detectToolingDrift, syncMcpCommand, type ToolingDrift } from "./mcp-root.ts"
 import { collectPipelineReport, type PipelineReport } from "./pipeline-report.ts"
 import { type ResolvedTarget, resolveTarget } from "./port.ts"
+import { collectVersionDrift, type VersionDrift, versionDriftMessage } from "./version-drift.ts"
 import { buildScriptName } from "./workspace-link.ts"
 
 // Runtime-provided modules that are never an npm dependency: Node core (bare + `node:` form) and Bun's
@@ -178,6 +187,17 @@ export interface DoctorResult {
    * supplied and the feature versions disagree. Computed by {@link detectToolingDrift}.
    */
   readonly toolingDrift?: ToolingDrift
+  /**
+   * More than one version of the fixed release group across pins, installs and the running CLI.
+   * Advisory (never folded into `ok`); its fix is `nifra upgrade <highest>`. Computed by
+   * {@link collectVersionDrift}.
+   */
+  readonly versionDrift?: VersionDrift
+  /**
+   * `buildManifest(...)` calls whose spelled-out file list reaches a page but not its backend half, so
+   * that page runs without its loader, action and guards. Advisory (never folded into `ok`).
+   */
+  readonly handBuiltManifests?: readonly HandBuiltManifest[]
   /**
    * Agent files whose MCP launch pins an `@nifrajs/cli` other than the one the project installs, so
    * the agent's server answers for a release the code no longer builds with. Advisory (never folded
@@ -347,16 +367,6 @@ const declaredPackages = (pkg: Record<string, unknown>): ReadonlySet<string> =>
   return declared
 }
 
-const tsconfigPaths = async (
-  root: string,
-): Promise<Readonly<Record<string, unknown>> | undefined> => {
-  const tsconfig = await readJson(join(root, "tsconfig.json"))
-  const compilerOptions = tsconfig?.compilerOptions as
-    | { paths?: Record<string, unknown> }
-    | undefined
-  return compilerOptions?.paths
-}
-
 /** Build per-package declaration scopes for a workspace. Longest roots are first so nested packages
  * own their source; files outside a workspace package remain owned by the root manifest. */
 async function doctorPackageScopes(
@@ -365,16 +375,16 @@ async function doctorPackageScopes(
 ): Promise<readonly DoctorPackageScope[]> {
   const importers = await workspaceImporters(cwd, rootPackage, true)
   const packages = importers.length > 0 ? importers : [{ root: cwd, package: rootPackage }]
-  const rootPaths = await tsconfigPaths(cwd)
-  const scopes = await Promise.all(
-    packages.map(async (entry): Promise<DoctorPackageScope> => {
-      const paths = (await tsconfigPaths(entry.root)) ?? rootPaths
-      return {
-        root: entry.root,
-        relativeRoot: relative(cwd, entry.root).split("\\").join("/"),
-        declared: declaredPackages(entry.package),
-        isAlias: aliasMatcher(paths),
-      }
+  // The nearest tsconfig, read as TypeScript does: comments, trailing commas and `extends` included.
+  const resolver = createSpecifierResolver()
+  const scopes = packages.map(
+    (entry): DoctorPackageScope => ({
+      root: entry.root,
+      relativeRoot: relative(cwd, entry.root).split("\\").join("/"),
+      declared: declaredPackages(entry.package),
+      isAlias: aliasMatcher(
+        Object.fromEntries(resolver.pathPatterns(entry.root).map((pattern) => [pattern, []])),
+      ),
     }),
   )
   return scopes.sort((a, b) => b.relativeRoot.length - a.relativeRoot.length)
@@ -690,7 +700,7 @@ async function collectDoctorReadiness(
       : configured(
           "graceful-lifecycle",
           "graceful lifecycle",
-          /\bgracefulSignals\s*:\s*true\b|\bonStop\s*\(/,
+          /\bgracefulSignals\s*:\s*(?:true\b|\{)|\bonStop\s*\(/,
         ),
   ]
   return {
@@ -783,6 +793,7 @@ export async function collectDoctorResult(
   const scopes = await doctorPackageScopes(cwd, pkg)
 
   const findings: DoctorFinding[] = []
+  const manifestLists: ManifestList[] = []
   // A standalone app owns its tests, so they remain in the declaration check. A workspace root owns
   // the published package source while its root devDependencies intentionally own shared tests,
   // benchmarks, and scaffold copy-surfaces. Keep that boundary explicit instead of reporting a
@@ -813,6 +824,7 @@ export async function collectDoctorResult(
       for (const f of scanUndeclaredImports(rel, content, scope.declared, scope.isAlias)) {
         findings.push({ file: f.file, line: f.line, package: f.snippet })
       }
+      manifestLists.push(...manifestListsIn(rel, content))
     },
     { includeTests: scanScope.includeTests, ignore: workspaceSurface },
   )
@@ -829,6 +841,8 @@ export async function collectDoctorResult(
   const toolingDrift =
     opts.cliVersion !== undefined ? await detectToolingDrift(cwd, opts.cliVersion) : undefined
   const staleMcpPins = await collectStaleMcpPins(cwd).catch(() => undefined)
+  const versionDrift = collectVersionDrift(cwd, opts.cliVersion)
+  const handBuilt = handBuiltManifests(cwd, manifestLists)
   // `staleDists`, `toolingDrift` and `staleMcpPins` are advisory (see DoctorResult): they never fail `ok`.
   return {
     ok:
@@ -846,6 +860,8 @@ export async function collectDoctorResult(
     readiness,
     scanScope,
     ...(toolingDrift !== undefined ? { toolingDrift } : {}),
+    ...(versionDrift !== undefined ? { versionDrift } : {}),
+    ...(handBuilt.length > 0 ? { handBuiltManifests: handBuilt } : {}),
     ...(staleMcpPins !== undefined && staleMcpPins.files.length > 0 ? { staleMcpPins } : {}),
     ...(pipeline.ran ? { pipeline } : {}),
   }
@@ -1031,6 +1047,12 @@ export async function runDoctor(
         "or ./node_modules/.bin/nifra)\n",
     )
   }
+  if (result.versionDrift !== undefined) {
+    console.log(`⚠ ${versionDriftMessage(result.versionDrift)}\n`)
+  }
+  for (const finding of result.handBuiltManifests ?? []) {
+    console.log(`⚠ ${handBuiltManifestMessage(finding)}\n`)
+  }
   // Advisory: the agent's MCP server is launched from these pins, so a stale one answers for an old
   // release even when the CLI running doctor matches the project.
   if (result.staleMcpPins !== undefined) {

package/src/env-file.ts

@@ -44,6 +44,13 @@ function unquote(raw: string): string {
   return (comment === -1 ? value : value.slice(0, comment)).trim()
 }
 
+/**
+ * Set to the command name while a CLI command imports a project only to read its declarations
+ * (`nifra check`, `routes`, the `assure` report), so app code can skip work a read never needs, such
+ * as connecting to Redis.
+ */
+export const REFLECT_ENV = "NIFRA_REFLECT"
+
 /** Parse dotenv text into a plain record. Later assignments to the same key win, as in a shell. */
 export function parseEnvFile(text: string): Record<string, string> {
   const values: Record<string, string> = {}

package/src/fix-recipes.ts

@@ -42,10 +42,15 @@ registerFixRecipe({
         "[nifra] the timing-safe fix finds each comparison in the syntax tree, so it needs TypeScript - run `bun add -d typescript`, then rerun the fix",
       )
     try {
-      const { rewriteSecretComparisons } = await import("./rules/security.ts")
+      const { provenBrowserFile, rewriteSecretComparisons } = await import("./rules/security.ts")
       const source = await readFile(path, "utf8")
       // Every site in the file at once, so the rest of that file's diagnostics find nothing left.
-      const rewritten = rewriteSecretComparisons(loaded.compiler, diagnostic.file, source)
+      const rewritten = rewriteSecretComparisons(
+        loaded.compiler,
+        diagnostic.file,
+        source,
+        provenBrowserFile(root, diagnostic.file),
+      )
       if (rewritten === source) return []
       await writeFile(path, rewritten, "utf8")
       return [diagnostic.file]
@@ -62,7 +67,33 @@ registerFixRecipe({
   async apply(root) {
     const { syncServerManifests } = await import("./sync-manifest.ts")
     const results = await syncServerManifests(root)
-    return results.filter((result) => result.changed).map((result) => result.file)
+    const changed = results.filter((result) => result.changed).map((result) => result.file)
+    const failed = results.filter((result) => result.error !== undefined)
+    if (failed.length > 0) {
+      const synced = changed.length === 0 ? "" : `synced ${changed.join(", ")}; `
+      throw new Error(
+        `[nifra] ${synced}cannot sync ${failed.map((result) => `${result.file}: ${result.error}`).join("; ")}`,
+      )
+    }
+    return changed
+  },
+})
+
+registerFixRecipe({
+  id: "framework.api-prefix",
+  description:
+    "Serve the backend over HTTP at /api by exporting apiPrefix from the framework config.",
+  verify: "nifra check",
+  async apply(root, diagnostic) {
+    if (diagnostic.file === undefined) return []
+    const path = await resolveInsideProject(root, diagnostic.file)
+    if (path === undefined) return []
+    const { withDefaultApiPrefix } = await import("./rules/pages.ts")
+    const file = Bun.file(path)
+    const next = withDefaultApiPrefix((await file.exists()) ? await file.text() : undefined)
+    if (next === undefined) return []
+    await writeFile(path, next, "utf8")
+    return [diagnostic.file]
   },
 })
 

package/src/hand-built-manifest.ts

@@ -0,0 +1,144 @@
+/**
+ * A route manifest built by hand from a list that names no backend half. `buildManifest(files, load)`
+ * pairs a page with its `.backend.*` half only when both are in `files`: it is pure, so it cannot know
+ * a half is missing. A test or server that spells the list out (an array literal, or `import.meta.glob`
+ * patterns) and leaves the halves out runs every route without its loader, action and guards.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { Glob } from "bun"
+import { codePositionMask } from "./check.ts"
+import { expressionEnd } from "./rules/data-guard.ts"
+
+/** A `buildManifest(...)` call whose file list reaches pages under `routes/` but not their halves. */
+export interface HandBuiltManifest {
+  readonly file: string
+  readonly line: number
+  /** How the list was spelled out. */
+  readonly source: "array" | "glob"
+  /** The backend halves, cwd-relative, of pages the list reaches but whose half it does not. */
+  readonly missing: readonly string[]
+}
+
+/** A `buildManifest(...)` call and the literal entries or glob patterns of its file list. */
+export interface ManifestList {
+  readonly file: string
+  readonly line: number
+  readonly source: "array" | "glob"
+  readonly entries: readonly string[]
+}
+
+// Mirrors `isRouteBackendFile` in @nifrajs/web's manifest.
+const BACKEND_HALF = /\.backend\.(?:[cm]?[jt]s)$/
+const LITERAL = /(["'`])((?:\\.|(?!\1)[^\\])*)\1/g
+
+const lineAt = (text: string, index: number): number => text.slice(0, index).split("\n").length
+
+/**
+ * The `buildManifest(` calls in `content` whose first argument is spelled out in source: an array of
+ * string literals, or an expression around `import.meta.glob(...)` with literal patterns. A list built
+ * any other way (a variable, a spread, a template with a substitution) is not read.
+ */
+export function manifestListsIn(file: string, content: string): ManifestList[] {
+  if (!content.includes("buildManifest")) return []
+  const mask = codePositionMask(content)
+  const lists: ManifestList[] = []
+  for (const call of mask.matchAll(/\bbuildManifest\s*\(/g)) {
+    const start = call.index + call[0].length
+    const end = expressionEnd(mask, start)
+    const argument = mask.slice(start, end).trim()
+    const literals = [...content.slice(start, end).matchAll(LITERAL)].map((m) => m[2] ?? "")
+    if (literals.some((text) => text.includes("${"))) continue
+    let source: ManifestList["source"]
+    if (argument.startsWith("[") && argument.endsWith("]")) {
+      // Every element a literal: the mask, with literals blanked, holds only brackets and commas.
+      if (!/^\[[\s,]*\]$/.test(argument)) continue
+      source = "array"
+    } else if (argument.includes("import.meta.glob(")) {
+      source = "glob"
+    } else continue
+    lists.push({ file, line: lineAt(content, call.index), source, entries: literals })
+  }
+  return lists
+}
+
+function filesUnder(routesDir: string): readonly string[] {
+  try {
+    return readdirSync(routesDir, { recursive: true, encoding: "utf8" }).map((rel) =>
+      rel.replaceAll("\\", "/"),
+    )
+  } catch {
+    return []
+  }
+}
+
+const stem = (file: string): string => file.replace(/\.[^./]+$/, "")
+
+/** A glob pattern from source, relative to `routes/` when it names that directory. */
+function routesRelative(pattern: string): string {
+  const at = pattern.lastIndexOf("routes/")
+  return at === -1 ? pattern.replace(/^(?:\.{0,2}\/)+/, "") : pattern.slice(at + "routes/".length)
+}
+
+function reaches(list: ManifestList): (file: string) => boolean {
+  if (list.source === "array") {
+    const listed = new Set(list.entries.map((entry) => entry.replace(/^\.\//, "")))
+    return (file) => listed.has(file)
+  }
+  const glob = (pattern: string): ((file: string) => boolean) => {
+    const compiled = new Glob(routesRelative(pattern))
+    return (file) => compiled.match(file) || compiled.match(`routes/${file}`)
+  }
+  const include = list.entries.filter((p) => !p.startsWith("!")).map(glob)
+  const exclude = list.entries.filter((p) => p.startsWith("!")).map((p) => glob(p.slice(1)))
+  return (file) => include.some((match) => match(file)) && !exclude.some((match) => match(file))
+}
+
+/** The `routes/` directory nearest above `file`, up to and including `cwd`'s own, as a cwd-relative path. */
+function routesDirFor(cwd: string, file: string): string | undefined {
+  for (let dir = dirname(file); ; dir = dirname(dir)) {
+    const candidate = dir === "." ? "routes" : `${dir}/routes`
+    const abs = join(cwd, candidate)
+    if (existsSync(abs) && statSync(abs).isDirectory()) return candidate
+    if (dir === "." || dir === "/" || dir === "") return undefined
+  }
+}
+
+/** The lists that reach a page under their app's `routes/` but not the backend half beside it. */
+export function handBuiltManifests(
+  cwd: string,
+  lists: readonly ManifestList[],
+): HandBuiltManifest[] {
+  const found: HandBuiltManifest[] = []
+  const filesByDir = new Map<string, readonly string[]>()
+  for (const list of lists) {
+    const routesDir = routesDirFor(cwd, list.file)
+    if (routesDir === undefined) continue
+    let files = filesByDir.get(routesDir)
+    if (files === undefined) {
+      files = filesUnder(join(cwd, routesDir))
+      filesByDir.set(routesDir, files)
+    }
+    const halves = files.filter((file) => BACKEND_HALF.test(file))
+    if (halves.length === 0) continue
+    const listed = reaches(list)
+    const missing = halves.filter((half) => {
+      if (listed(half)) return false
+      const page = stem(half.replace(BACKEND_HALF, ""))
+      return files.some((file) => !BACKEND_HALF.test(file) && stem(file) === page && listed(file))
+    })
+    if (missing.length > 0) {
+      const shown = missing.map((half) => `${routesDir}/${half}`)
+      found.push({ file: list.file, line: list.line, source: list.source, missing: shown })
+    }
+  }
+  return found
+}
+
+/** The advisory `nifra doctor` prints for one finding. */
+export function handBuiltManifestMessage(finding: HandBuiltManifest): string {
+  const list = finding.source === "array" ? "a file list" : "import.meta.glob patterns"
+  const shown = finding.missing.slice(0, 3)
+  const more = finding.missing.length > 3 ? ` and ${finding.missing.length - 3} more` : ""
+  return `${finding.file}:${finding.line} builds a route manifest from ${list} that leaves out ${finding.missing.length} backend half(s) of pages it lists (${shown.join(", ")}${more}). buildManifest pairs a page with its .backend.* half only when both are listed, so those pages run without their loaders, actions and guards. Use discoverRoutes("./routes") from @nifrajs/web/fs, or the generated server-manifest.`
+}