@nifrajs/cli 4.0.2 → 5.1.0

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/dev-feed-tool.ts

@@ -793,6 +793,117 @@ export const logsSpec: CommandSpec<LogsInput, LogsOutput> = {
   json: (out) => out,
 }
 
+export interface ExplainInput {
+  readonly error?: string | undefined
+  readonly stack?: string | undefined
+  readonly name?: string | undefined
+  readonly port?: number | undefined
+  readonly dir?: string | undefined
+  readonly json?: boolean | undefined
+}
+
+/** A diagnostic, or `NIFRA_NONE` with why there was nothing to explain. */
+export type ExplainOutput =
+  | (Diagnostic & { readonly entry?: object; readonly note?: string })
+  | { code: "NIFRA_NONE"; message: string }
+
+const explained = (out: ExplainOutput): out is Diagnostic => out.code !== "NIFRA_NONE"
+
+export const explainSpec: CommandSpec<ExplainInput, ExplainOutput> = {
+  name: "explain",
+  summary:
+    "Turn an error into a structured diagnostic: its code, the frame in your source with a codeframe, and the cause and fix when nifra recognises it. With no message, the running dev server's latest error.",
+  input: {
+    jsonSchema: {
+      type: "object",
+      properties: {
+        error: { type: "string", description: "The error message to explain." },
+        stack: {
+          type: "string",
+          description: "Its stack trace, for the codeframe and source frame.",
+        },
+        name: { type: "string", description: "Its class name, such as TypeError." },
+        port: SHARED_PROPERTIES.port,
+        dir: { type: "string", description: "The app directory." },
+        json: { type: "boolean" },
+      },
+      additionalProperties: false,
+    },
+    parse: (value) => {
+      const raw = fields(value)
+      return {
+        error: text(raw, "error"),
+        stack: text(raw, "stack"),
+        name: text(raw, "name"),
+        port: count(raw, "port"),
+        dir: text(raw, "dir"),
+        json: flag(raw, "json"),
+      }
+    },
+  },
+  output: {
+    version: 1,
+    jsonSchema: {
+      type: "object",
+      properties: { code: { type: "string" }, message: { type: "string" } },
+      required: ["code", "message"],
+    },
+    parse: (value) => {
+      if (isDiagnostic(value)) return value
+      if (
+        typeof value === "object" &&
+        value !== null &&
+        "code" in value &&
+        value.code === "NIFRA_NONE" &&
+        "message" in value &&
+        typeof value.message === "string"
+      )
+        return { code: "NIFRA_NONE", message: value.message }
+      throw new TypeError("explain output must be a diagnostic or NIFRA_NONE")
+    },
+  },
+  transports: ["cli"],
+  stability: "experimental",
+  argv: {
+    positionals: ["error"],
+    flags: [
+      { name: "stack", field: "stack", type: "string" },
+      { name: "name", field: "name", type: "string" },
+      { name: "port", field: "port", type: "number" },
+      { name: "dir", field: "dir", type: "string" },
+      { name: "json", field: "json", type: "boolean" },
+    ],
+  },
+  async run(input, ctx) {
+    const root = resolve(ctx.cwd, input.dir ?? ".")
+    if (input.error === undefined && input.stack === undefined) {
+      return explainLatest(root, input.port, ctx.signal)
+    }
+    const { buildDiagnostic } = await import("@nifrajs/web/diagnostic")
+    const { explainSourceGate } = await import("./mcp-exec.ts")
+    const error = new Error(input.error ?? "")
+    if (input.name !== undefined) error.name = input.name
+    // Without --stack the frames would be this command's own, not the app's.
+    error.stack = input.stack ?? `${error.name}: ${error.message}`
+    return buildDiagnostic(error, { root, showSource: explainSourceGate(root) })
+  },
+  render: (out) => {
+    if (!explained(out)) return [out.message]
+    const at = topFrame(out)
+    return [
+      `${out.code}  ${headline(out)}`,
+      ...(at === undefined ? [] : [`  at ${at}`]),
+      ...(out.codeframe?.lines ?? []).map(
+        (line) => `  ${line.caret ? ">" : " "} ${String(line.number).padStart(4)} | ${line.text}`,
+      ),
+      ...(out.cause === undefined ? [] : [`  cause: ${out.cause}`]),
+      ...(out.fix === undefined ? [] : [`  fix: ${out.fix}`]),
+    ]
+  },
+  exitCode: (out) => (explained(out) ? 0 : 2),
+  json: (out) => out,
+}
+
 // ---------------------------------------------------------------------------------------------------
 // nifra_explain / nifra_inspect reads
 // ---------------------------------------------------------------------------------------------------
@@ -802,7 +913,7 @@ export async function explainLatest(
   cwd: string,
   port: number | undefined,
   signal?: AbortSignal,
-): Promise<unknown> {
+): Promise<ExplainOutput> {
   const { findDevServer, describeLookup, readDevFeed } = await import("./dev-server-client.ts")
   const lookup = await findDevServer(cwd, { port }, signal)
   if (lookup.status === "live") {

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