@nifrajs/cli 4.0.2 → 5.0.0

package/src/component-check.ts

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync } from "node:fs"
+import { resolve } from "node:path"
+import {
+  isUnsupportedTypeScriptError,
+  type UnsupportedTypeScriptError,
+} from "./internal/typescript-import.ts"
+import type { SourceIndex } from "./rules/index.ts"
+
+type ComponentSource = typeof import("@nifrajs/web/server-components/source")
+
+export interface ComponentCheck {
+  readonly receipts: ReadonlySet<string>
+  /** Set when the project's TypeScript has no compiler API to read component modules with
+   * (TypeScript 7): no module gets a receipt, so the ordinary import rule judges each one. */
+  readonly unsupported: UnsupportedTypeScriptError | undefined
+}
+
+const COMPONENT_SERVER = /\.component\.server\.[cm]?[jt]sx?$/
+
+/** A source-only proof. nifra check never executes nifra.config.ts. */
+export async function componentCheckReceipts(
+  root: string,
+  source: SourceIndex,
+  load: () => Promise<ComponentSource> = () => import("@nifrajs/web/server-components/source"),
+): Promise<ComponentCheck> {
+  const receipts = new Set<string>()
+  const result: ComponentCheck = { receipts, unsupported: undefined }
+  if (!source.files.some((file) => COMPONENT_SERVER.test(file))) return result
+  const configFile = ["nifra.config.ts", "backend/framework.ts"].find((file) =>
+    existsSync(resolve(root, file)),
+  )
+  if (configFile === undefined) return result
+  let components: ComponentSource
+  try {
+    components = await load()
+  } catch (error) {
+    if (isUnsupportedTypeScriptError(error)) return { receipts, unsupported: error }
+    throw error
+  }
+  const pipeline = components.staticComponentPipeline(
+    readFileSync(resolve(root, configFile), "utf8"),
+    configFile,
+  )
+  if (typeof pipeline !== "object" || pipeline === null || Array.isArray(pipeline)) return result
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Static receipt inspection checks object shape before reading fields; the source scanner never executes configuration.
+  const options = pipeline as Record<string, unknown>
+  if (
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Static receipt inspection checks object shape before reading fields; the source scanner never executes configuration.
+    !["react", "vue", "svelte", "solid", "preact"].includes(options.adapter as string) ||
+    typeof options.entries !== "object" ||
+    options.entries === null ||
+    Array.isArray(options.entries)
+  )
+    return result
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Static receipt inspection checks object shape before reading fields; the source scanner never executes configuration.
+  const entries = options.entries as Record<string, unknown>
+  if (
+    typeof entries.client !== "string" ||
+    typeof entries.ssr !== "string" ||
+    (options.adapter === "react" && typeof entries.rsc !== "string") ||
+    Object.values(entries).some(
+      (file) => typeof file !== "string" || !existsSync(resolve(root, file)),
+    )
+  )
+    return result
+  for (const file of source.files) {
+    if (!COMPONENT_SERVER.test(file)) continue
+    const content = source.read(file)
+    if (content === undefined) continue
+    try {
+      components.compileComponentModule(content, resolve(root, file), root, "client")
+      receipts.add(file)
+      receipts.add(resolve(root, file))
+    } catch {
+      /* A module without a compilation receipt remains forbidden by the ordinary import rule. */
+    }
+  }
+  return result
+}

package/src/contract-proof.ts

@@ -1,14 +1,12 @@
-import { existsSync, realpathSync } from "node:fs"
-import { resolve, sep } from "node:path"
 import type { AssuranceFinding, AssuranceReport, AssuredRoute } from "@nifrajs/core/assurance"
 import type {
   AssuredCapabilityRoute,
   CapabilityAssuranceReport,
   CapabilityFinding,
 } from "@nifrajs/core/capabilities"
-import { diffRouteSnapshots, type RouteChange, type RoutesDiff } from "@nifrajs/core/diff"
+import type { RouteChange, RoutesDiff } from "@nifrajs/core/diff"
 import type { CheckResult } from "./check.ts"
-import { DEFAULT_SNAPSHOT_FILE, parseSnapshotFile, snapshotBackend } from "./diff-tool.ts"
+import { DEFAULT_SNAPSHOT_FILE, diffAgainstBaseline } from "./diff-tool.ts"
 import { collectProjectVerification } from "./verification.ts"
 
 const routeKey = (method: string, path: string): string => `${method.toUpperCase()}\n${path}`
@@ -59,15 +57,6 @@ export interface ContractProofOptions {
   readonly signal?: AbortSignal
 }
 
-function safeBaselinePath(cwd: string, baselinePath: string): string {
-  const root = resolve(cwd)
-  const target = resolve(root, baselinePath)
-  if (target !== root && !target.startsWith(`${root}${sep}`)) {
-    throw new Error("contract proof baseline must stay inside the project directory")
-  }
-  return target
-}
-
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
@@ -144,18 +133,7 @@ export async function collectContractProof(
   options: ContractProofOptions = {},
 ): Promise<ContractProofReport> {
   const baselinePath = options.baselinePath ?? DEFAULT_SNAPSHOT_FILE
-  const resolvedBaseline = safeBaselinePath(cwd, baselinePath)
-  if (!existsSync(resolvedBaseline)) {
-    throw new Error(`contract proof baseline not found: ${resolvedBaseline}`)
-  }
-  const realRoot = realpathSync(resolve(cwd))
-  const realBaseline = realpathSync(resolvedBaseline)
-  if (realBaseline !== realRoot && !realBaseline.startsWith(`${realRoot}${sep}`)) {
-    throw new Error("contract proof baseline must stay inside the project directory")
-  }
-  const baseline = parseSnapshotFile(await Bun.file(resolvedBaseline).text(), baselinePath)
-  const current = await snapshotBackend(cwd)
-  const diff = diffRouteSnapshots(baseline.routes, current)
+  const diff = await diffAgainstBaseline(cwd, baselinePath, { contain: true })
   const verification = await collectProjectVerification(cwd, {
     ...(options.signal === undefined ? {} : { signal: options.signal }),
   })

package/src/contracts.ts

@@ -1,5 +1,6 @@
 import { existsSync } from "node:fs"
 import { resolve } from "node:path"
+import { NIFRA_ASSURANCE } from "@nifrajs/core/assurance"
 import {
   type ProjectEvidenceSnapshot,
   reflectedRoutesFromEvidence,
@@ -16,9 +17,18 @@ export interface ContractDigest {
 
 export interface ContractsLock {
   readonly version: 1
+  /** The {@link CONTRACT_DIGEST_FORMAT} that produced `routes`. Absent in a lock written before it was recorded. */
+  readonly digest?: number
   readonly routes: Readonly<Record<string, ContractDigest>>
 }
 
+/**
+ * Bumped whenever {@link digestRoute} hashes the same schema differently. The lock records it, so a
+ * format change reads as "re-snapshot" instead of as drift on every route. 2: properties named like
+ * annotation keywords are hashed (4.0.1).
+ */
+export const CONTRACT_DIGEST_FORMAT = 2
+
 export const DEFAULT_CONTRACTS_LOCK = "contracts.lock.json"
 const DIGEST = /^[a-f0-9]{64}$/
 
@@ -146,6 +156,7 @@ export async function buildContractsLock(
   )
   return {
     version: 1,
+    digest: CONTRACT_DIGEST_FORMAT,
     routes: Object.fromEntries(Object.entries(routes).sort(([a], [b]) => codeUnitOrder(a, b))),
   }
 }
@@ -160,6 +171,27 @@ async function loadBackend(cwd: string): Promise<unknown> {
   return loaded.backend
 }
 
+const INPUT_PARTS = ["body", "query", "headers", "cookies", "params"] as const
+
+/**
+ * A route that in-process auth guards, but through a hook that runs after its declared input is
+ * validated: an unauthenticated caller reaches the body parser and reads the validation issues.
+ * Gateway auth (declared provenance) never lets that caller in, and an explicit `validationOrder`
+ * is the author's choice.
+ */
+export function validatesBeforeAuthentication(route: ReflectedRoute): boolean {
+  const schema = route.schema
+  if (schema === undefined || schema.validationOrder !== undefined) return false
+  if (!INPUT_PARTS.some((part) => schema[part] !== undefined)) return false
+  const auth = (route.assurance ?? []).filter(
+    (evidence) =>
+      evidence.id === NIFRA_ASSURANCE.AUTHENTICATED &&
+      (evidence.provenance ?? (evidence.source === "declared" ? "declared" : "runtime")) ===
+        "runtime",
+  )
+  return auth.length > 0 && auth.every((evidence) => evidence.source !== "nifra.authenticate")
+}
+
 export async function snapshotContracts(
   cwd: string,
   out = DEFAULT_CONTRACTS_LOCK,
@@ -176,6 +208,9 @@ export function parseContractsLock(value: unknown): ContractsLock {
   const routesRecord = recordOf(routesValue)
   if (record.version !== 1 || routesRecord === undefined)
     throw new TypeError("contracts lock must have version 1 and routes")
+  const digest = record.digest
+  if (digest !== undefined && !(Number.isSafeInteger(digest) && Number(digest) > 0))
+    throw new TypeError("contracts lock digest must be a positive integer")
   const routes: Record<string, ContractDigest> = {}
   for (const [key, raw] of Object.entries(routesRecord)) {
     const item = recordOf(raw)
@@ -192,7 +227,7 @@ export function parseContractsLock(value: unknown): ContractsLock {
       throw new TypeError(`invalid contract ${key}`)
     routes[key] = { request, response }
   }
-  return { version: 1, routes }
+  return typeof digest === "number" ? { version: 1, digest, routes } : { version: 1, routes }
 }
 
 export async function checkContractsLock(
@@ -202,13 +237,30 @@ export async function checkContractsLock(
   present: boolean
   vacuous: boolean
   diagnostics: Array<{ route?: string; message: string }>
+  /** `METHOD /path` of every route the backend serves, read when the lock made the check load it. */
+  served?: readonly string[]
+  /** `METHOD /path` of each route {@link validatesBeforeAuthentication} names, read alongside `served`. */
+  inputBeforeAuth?: readonly string[]
 }> {
   const path = resolve(cwd, file)
   if (!existsSync(path)) return { present: false, vacuous: false, diagnostics: [] }
   const parsed = parseContractsLock(JSON.parse(await Bun.file(path).text()))
-  const current = await buildContractsLock(await loadBackend(cwd))
+  const evidence = snapshotProjectEvidence(await loadBackend(cwd))
+  const current = await buildContractsLock(undefined, evidence)
   const vacuous = await isVacuousLock(current)
+  const served = Object.keys(current.routes)
+  const inputBeforeAuth = reflectedRoutesFromEvidence(evidence)
+    .filter(validatesBeforeAuthentication)
+    .map((route) => `${route.method} ${route.path}`)
   const diagnostics: Array<{ route?: string; message: string }> = []
+  // Digests of two formats never compare, so this still fails; it just names the real cause.
+  if (parsed.digest !== undefined && parsed.digest !== CONTRACT_DIGEST_FORMAT) {
+    const newer = parsed.digest > CONTRACT_DIGEST_FORMAT
+    diagnostics.push({
+      message: `${file} was written with contract digest format ${parsed.digest}, but this nifra computes format ${CONTRACT_DIGEST_FORMAT}${newer ? " (a newer @nifrajs/cli wrote it; upgrade this one)" : ""}, so no route could be compared. Review the route schema changes since the lock was written, then run \`nifra contracts snapshot\` and commit the lock.`,
+    })
+    return { present: true, vacuous, diagnostics, served, inputBeforeAuth }
+  }
   const keys = new Set([...Object.keys(parsed.routes), ...Object.keys(current.routes)])
   for (const key of [...keys].sort()) {
     const before = parsed.routes[key]
@@ -225,5 +277,10 @@ export async function checkContractsLock(
       })
     }
   }
-  return { present: true, vacuous, diagnostics }
+  if (diagnostics.length > 0 && parsed.digest === undefined) {
+    diagnostics.push({
+      message: `${file} records no contract digest format. A lock written before nifra 4.0.1 hashed schemas differently, so a route reported above may not have changed. Review them, then run \`nifra contracts snapshot\` to record the format.`,
+    })
+  }
+  return { present: true, vacuous, diagnostics, served, inputBeforeAuth }
 }

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> = {}