@nifrajs/cli 4.0.0 → 5.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/cli",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "The nifra CLI - zero-config dev/build/start for a nifra app (`nifra dev`, `nifra build`, `nifra start`).",
   "keywords": [
     "bun",
@@ -69,17 +69,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/client": "4.0.0",
-    "@nifrajs/core": "4.0.0",
-    "@nifrajs/agent-review": "4.0.0",
-    "@nifrajs/i18n": "4.0.0",
-    "@nifrajs/mcp": "4.0.0",
-    "@nifrajs/mcp-db": "4.0.0",
-    "@nifrajs/runner": "4.0.0",
-    "@nifrajs/schema": "4.0.0",
-    "@nifrajs/testing": "4.0.0",
-    "@nifrajs/web": "4.0.0",
-    "create-nifra": "4.0.0"
+    "@nifrajs/client": "5.0.0",
+    "@nifrajs/core": "5.0.0",
+    "@nifrajs/agent-review": "5.0.0",
+    "@nifrajs/i18n": "5.0.0",
+    "@nifrajs/mcp": "5.0.0",
+    "@nifrajs/mcp-db": "5.0.0",
+    "@nifrajs/runner": "5.0.0",
+    "@nifrajs/schema": "5.0.0",
+    "@nifrajs/testing": "5.0.0",
+    "@nifrajs/web": "5.0.0"
   },
   "repository": {
     "type": "git",

package/src/agent-files.ts

@@ -0,0 +1,203 @@
+/**
+ * The canonical generators for the agent files an app ships. `AGENTS.md` is the single source of agent
+ * guidance; every other agent's file is a thin pointer to it, so no two copies can drift:
+ *
+ *   AGENTS.md                         - the guidance (read natively by Codex, Cursor, Copilot and others)
+ *   CLAUDE.md                         - Claude Code: `@AGENTS.md` import
+ *   GEMINI.md                         - Gemini CLI: `@./AGENTS.md` import
+ *   .cursor/rules/nifra.mdc           - Cursor: an always-applied rule pointing at AGENTS.md
+ *   .github/copilot-instructions.md   - GitHub Copilot: points at AGENTS.md
+ *   .mcp.json, .cursor/mcp.json       - the nifra MCP server, registered for Claude Code and Cursor
+ *
+ * `create-nifra` (scaffold time) and `@nifrajs/cli`'s `nifra init-agents` (retrofit an existing app) each
+ * ship this file byte-identical - `packages/cli/test/init-agents.test.ts` holds the two copies equal - so
+ * the generated files can never drift apart and neither package needs the other at runtime. It stays
+ * dependency-free (pure string + object generation) on purpose: `create-nifra` ships with no runtime deps.
+ *
+ * Why `bunx @nifrajs/cli mcp` (not `bunx nifra mcp`): the `nifra` binary is provided by the
+ * `@nifrajs/cli` package, and the bare npm package literally named `nifra` (this monorepo's
+ * `@nifrajs/web` shim) exposes NO `nifra` bin, so `bunx nifra mcp` would fetch the wrong package in an
+ * app that does not carry `@nifrajs/cli`. Naming the bin-owning package resolves the locally-installed
+ * bin when present and otherwise fetches the package that actually provides the `nifra` command.
+ */
+
+import { readFileSync } from "node:fs"
+
+/** The MCP launch command, shared by `.mcp.json` and `.cursor/mcp.json`. See the module header for why
+ * the package is named explicitly rather than relying on the bare `nifra` bin. */
+export const MCP_SERVER_COMMAND = "bunx" as const
+
+/**
+ * The `@nifrajs/cli` version the launch command pins to - DERIVED at load time from this package's own
+ * `version`, never hardcoded. `fixed` changeset versioning ([["@nifrajs/*", "create-nifra", "nifra"]] in
+ * `.changeset/config.json`) bumps `create-nifra` and `@nifrajs/cli` in lockstep, so `create-nifra@x`
+ * always means `@nifrajs/cli@x`. Deriving it here means a release bump has nothing to forget to update -
+ * there is no stale literal to drift (the 1.0.0 cut shipped a beta pin exactly this way). `check:publish`
+ * still asserts it equals `@nifrajs/cli`'s version as a belt-and-suspenders guard on the `fixed` link.
+ *
+ * Resolves correctly under BOTH export conditions: the `bun` export runs `src/agent-files.ts`
+ * (`../package.json` → the package root) and the tsc `default` export runs `dist/agent-files.js`
+ * (`../package.json` → the same root, since `dist/` sits beside the manifest). npm always ships a
+ * package's own `package.json`, so the read can't miss at install time.
+ *
+ * Why pin at all instead of `bunx @nifrajs/cli mcp`: `bunx` keys its cache on the exact version spec.
+ * An UNPINNED spec resolves to the `latest` tag once, then `bunx` reuses that cached copy on every
+ * later spawn WITHOUT re-checking the registry - so an editor that once launched an older `@nifrajs/cli`
+ * keeps respawning the stale binary even after a newer one is published (the MCP server silently runs
+ * old code). Pinning the exact version makes the version part of the cache key, so each release fetches
+ * fresh and a stale cache can never shadow it. The cost: an already-scaffolded app's `.mcp.json` freezes
+ * at its scaffold-time version until `nifra init-agents --sync-mcp` re-pins it to the nifra the project
+ * installs - an acceptable, deterministic trade.
+ */
+export const MCP_CLI_VERSION: string = ownVersion()
+
+function ownVersion(): string {
+  const manifest: unknown = JSON.parse(
+    readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+  )
+  if (
+    typeof manifest === "object" &&
+    manifest !== null &&
+    "version" in manifest &&
+    typeof manifest.version === "string"
+  )
+    return manifest.version
+  throw new Error("[nifra] agent-files: this package's package.json has no version")
+}
+export const MCP_SERVER_ARGS = [`@nifrajs/cli@${MCP_CLI_VERSION}`, "mcp"] as const
+
+/** The server entry registered under the `nifra` key in both Claude Code's and Cursor's MCP config. */
+export interface McpServerConfig {
+  readonly command: string
+  readonly args: readonly string[]
+}
+
+/** Claude Code / Cursor MCP config shape: a map of server name → launch config. */
+export interface McpConfig {
+  readonly mcpServers: Readonly<Record<string, McpServerConfig>>
+}
+
+/** The one canonical MCP config object both registries serialize - the anti-drift seam. */
+export const MCP_CONFIG: McpConfig = {
+  mcpServers: {
+    nifra: { command: MCP_SERVER_COMMAND, args: [...MCP_SERVER_ARGS] },
+  },
+}
+
+/** Serialize the canonical MCP config as the JSON written to `.mcp.json` and `.cursor/mcp.json`.
+ * Trailing newline so the file is POSIX-clean and diffs don't flag a missing EOL. */
+export function mcpJson(): string {
+  return `${JSON.stringify(MCP_CONFIG, null, 2)}\n`
+}
+
+const POINTER_INTRO =
+  "This project's agent guidance - commands, the project structure, the rules, and the nifra MCP server - lives in AGENTS.md, the single source every agent reads."
+
+/** `CLAUDE.md`: Claude Code expands the `@AGENTS.md` import in place. */
+export function claudeMd(): string {
+  return `# CLAUDE.md\n\n${POINTER_INTRO}\n\n@AGENTS.md\n`
+}
+
+/** `GEMINI.md`: Gemini CLI expands `@./AGENTS.md` imports in its context files. */
+export function geminiMd(): string {
+  return `# GEMINI.md\n\n${POINTER_INTRO}\n\n@./AGENTS.md\n`
+}
+
+/** `.cursor/rules/nifra.mdc`: an always-applied Cursor rule; `@AGENTS.md` attaches the file. */
+export function cursorRule(): string {
+  return `---\ndescription: nifra project guidance\nalwaysApply: true\n---\n\n${POINTER_INTRO} Read it before changing code:\n\n@AGENTS.md\n`
+}
+
+/** `.github/copilot-instructions.md`: Copilot has no import syntax, so this names the file. */
+export function copilotInstructions(): string {
+  return `${POINTER_INTRO} Read AGENTS.md at the repository root before changing code, and follow it.\n`
+}
+
+/**
+ * The "## MCP server" section appended to a scaffolded (or retrofitted) `AGENTS.md`, so non-Claude
+ * agents (Cursor, and anything that reads `AGENTS.md`) also learn the MCP exists and what to prefer.
+ * Mirrors the CLAUDE.md preamble's guidance without the Claude-specific `@import`.
+ */
+export function agentsMcpSection(): string {
+  return `## MCP server
+
+This project ships a **nifra MCP server** - launch it with \`${MCP_SERVER_COMMAND} ${MCP_SERVER_ARGS.join(" ")}\`. It's registered for
+Claude Code in \`.mcp.json\` and for Cursor in \`.cursor/mcp.json\`; other agents can point their MCP client
+at that command. **Prefer its tools** over writing nifra from memory - they're typechecked against this
+project + the installed version, so they beat training-data recall:
+
+- \`nifra_docs\` / \`nifra_example\` - exact signatures + verified, compiling snippets.
+- \`nifra_context\` / \`nifra_routes\` - this project's route index + per-route schemas.
+- \`nifra_types\` - the EXACT TypeScript of any \`@nifrajs/*\` symbol (interface/type/function). Call it for a
+  precise type; **never read \`@nifrajs\` \`.d.ts\` files** - this is the authoritative, complete source.
+- \`nifra_check\` - the done-gate (typecheck + drift lints). Run it before calling work complete; a
+  failing check means it isn't done. (\`nifra check --json\` in a terminal does the same.)`
+}
+
+/**
+ * The "## Project structure" section of a web app's `AGENTS.md`: the zones the build enforces. Shared so
+ * a scaffolded app and one `nifra init-agents` retrofits teach the same rules.
+ */
+export function agentsStructureSection(): string {
+  return `${STRUCTURE_HEADING}
+
+Every file a build loads belongs to one side, and the build refuses an import that crosses the wrong
+way - it fails naming the import chain rather than shipping server code to the browser.
+
+| Where | Holds | Reaches the browser |
+|---|---|---|
+| \`routes/x.tsx\` (\`.svelte\`, \`.vue\`, \`.mdx\`) | a page: the component, \`meta\` | yes |
+| \`routes/x.backend.ts\` | that page's \`loader\`, \`action\`, \`loaderOutput\`, \`actionOutput\`, \`middleware\` | never |
+| \`frontend/\` | components, hooks, browser-only code | yes |
+| \`backend/\` | \`app.ts\` (the API), \`framework.ts\`, the database, auth, secrets | never |
+| \`shared/\` | schemas, types and pure helpers both sides import | yes |
+| \`public/\` | static files served as they are | yes |
+
+A file outside those folders joins a side with a \`.frontend.ts\`, \`.backend.ts\` or \`.shared.ts\` suffix.
+
+- **A route is two files.** \`routes/blog/[slug].tsx\` renders; \`routes/blog/[slug].backend.ts\` loads.
+  A server-only export (\`loader\`, \`action\`, ...) in the \`.tsx\` file is a build error.
+- **Frontend code never imports backend code** - not \`backend/\`, not a \`.backend.ts\` file, not a
+  database driver or \`node:\` built-in. Data reaches a page only as its loader's return value.
+- **Every loader and action declares what it sends**: \`export const loaderOutput = t.object({ ... })\`
+  (and \`actionOutput\`). Only what the schema declares reaches the browser, and a loader without one
+  is refused.
+- **Type a route with its generated \`./+types/<name>\`**: \`import type { Route } from "./+types/[slug]"\`
+  gives \`Route.Loader\` and \`Route.Action\` in the backend half (\`export const loader: Route.Loader =
+  async ({ api, params }) => ...\` checks what it returns against \`loaderOutput\`) and
+  \`Route.ComponentProps\` in the page. \`nifra dev\`, \`nifra build\`, \`nifra check\` and
+  \`nifra types\` write them.
+- **Secrets stay in \`backend/\`.** A value only the server may see is read there (\`process.env\`), never
+  in a frontend file; a build that finds what looks like a credential in browser output fails.`
+}
+
+/** The heading `nifra init-agents` looks for before appending {@link agentsStructureSection}. */
+export const STRUCTURE_HEADING = "## Project structure"
+
+/** Identifies a generated agent-discovery file: where it goes (relative to the project root) and how to
+ * produce its content. `merge` is for files that augment an existing one (AGENTS.md) rather than own it. */
+export interface AgentFileSpec {
+  /** Path relative to the project root (POSIX-style; the caller joins onto the cwd). */
+  readonly path: string
+  /** A human label for the "wrote/skipped" report. */
+  readonly label: string
+}
+
+/** The standalone files this module fully owns (whole-file generators). AGENTS.md is handled separately
+ * because create-nifra builds it from `agents.ts` and the retrofit command appends sections to it. */
+export const MCP_JSON_PATH = ".mcp.json"
+export const CURSOR_MCP_JSON_PATH = ".cursor/mcp.json"
+export const CLAUDE_MD_PATH = "CLAUDE.md"
+export const GEMINI_MD_PATH = "GEMINI.md"
+export const CURSOR_RULE_PATH = ".cursor/rules/nifra.mdc"
+export const COPILOT_INSTRUCTIONS_PATH = ".github/copilot-instructions.md"
+export const AGENTS_MD_PATH = "AGENTS.md"
+
+/** Every agent's pointer to `AGENTS.md`, in the order they are written and reported. */
+export const AGENT_POINTERS: readonly { readonly path: string; readonly content: () => string }[] =
+  [
+    { path: CLAUDE_MD_PATH, content: claudeMd },
+    { path: GEMINI_MD_PATH, content: geminiMd },
+    { path: CURSOR_RULE_PATH, content: cursorRule },
+    { path: COPILOT_INSTRUCTIONS_PATH, content: copilotInstructions },
+  ]

package/src/app-files.ts

@@ -6,7 +6,7 @@
  *   kept free of build tooling because it is bundled into every server build.
  * - `backend/app.ts` - exports `backend`, the app's API (a `@nifrajs/core` server). Optional.
  */
-import { existsSync } from "node:fs"
+import { existsSync, readFileSync } from "node:fs"
 import { resolve } from "node:path"
 
 export const CONFIG_FILE = "nifra.config.ts"
@@ -19,11 +19,41 @@ export const RETIRED_ROOT_FILES: Readonly<Record<string, string>> = {
   "framework.ts": FRAMEWORK_FILE,
 }
 
+/** Outside a routed app, what made each retired root file the app's: else it is just a module. */
+const RETIRED_EXPORTS: Readonly<Record<string, RegExp>> = {
+  "backend.ts":
+    /\bexport\s+(?:const|let|var|(?:async\s+)?function|class)\s+backend\b|\bexport\s*\{[^}]*\bbackend\b/,
+  "framework.ts":
+    /\bexport\s+(?:const|let|var|(?:async\s+)?function|class)\s+adapter\b|\bexport\s*\{[^}]*\badapter\b/,
+}
+
+function exportsRetiredName(path: string, pattern: RegExp | undefined): boolean {
+  if (!existsSync(path)) return false
+  try {
+    return pattern === undefined || pattern.test(readFileSync(path, "utf8"))
+  } catch {
+    // Unreadable: the commands that would load it fail too, so report it rather than skip it.
+    return true
+  }
+}
+
+/**
+ * The retired root files present in `cwd`, each with where it lives now. The old loader imported them
+ * whatever they exported, so in an app with `routes/` or a config each one counts; elsewhere only one
+ * that exports what the loader read does, and a library's `backend.ts` module does not.
+ */
+export function retiredRootFiles(cwd: string): ReadonlyArray<readonly [string, string]> {
+  const routed = ["routes", CONFIG_FILE, FRAMEWORK_FILE].some((entry) =>
+    existsSync(resolve(cwd, entry)),
+  )
+  return Object.entries(RETIRED_ROOT_FILES).filter(([file]) =>
+    exportsRetiredName(resolve(cwd, file), routed ? undefined : RETIRED_EXPORTS[file]),
+  )
+}
+
 /** Refuse an app still on the retired root files: run against it, a command would silently miss them. */
 export function assertCurrentLayout(cwd: string): void {
-  const retired = Object.entries(RETIRED_ROOT_FILES).filter(([file]) =>
-    existsSync(resolve(cwd, file)),
-  )
+  const retired = retiredRootFiles(cwd)
   if (retired.length === 0) return
   const moves = retired.map(([from, to]) => `${from} -> ${to}`).join(", ")
   throw new Error(

package/src/assure-hydration.ts

@@ -11,7 +11,15 @@ import { discoverRoutes } from "@nifrajs/web/fs"
 import type { BunPlugin } from "bun"
 import { collectDoctorResult } from "./doctor.ts"
 import { loadApp, resolvePlugins } from "./load.ts"
-import { CHILD_OUTPUT_MAX_BYTES, joinHeadTail, readBoundedStream, readHeadTail } from "./mcp-io.ts"
+import {
+  CHILD_OUTPUT_MAX_BYTES,
+  forwardTerminalSignals,
+  joinHeadTail,
+  OWN_PROCESS_GROUP,
+  readBoundedStream,
+  readHeadTail,
+  signalProcessGroup,
+} from "./mcp-io.ts"
 import { frameworkWebAppOptions } from "./web-app-options.ts"
 
 const HYDRATION_ASSURANCE = Symbol.for("nifra.hydration.assurance")
@@ -634,15 +642,19 @@ export async function runHydrationAssurance(
       stdin: "pipe",
       stdout: "pipe",
       stderr: "pipe",
+      // Its own group, so a stop reaches whatever the project's code started too; a process left
+      // holding the pipes would otherwise keep this run waiting past its timeout.
+      detached: OWN_PROCESS_GROUP,
     },
   )
   let stopped: string | undefined
   const stop = (reason: string): void => {
     stopped ??= reason
-    proc.kill()
+    signalProcessGroup(proc, "SIGTERM")
   }
   const onAbort = (): void => stop("cancelled")
   control.signal?.addEventListener("abort", onAbort, { once: true })
+  const releaseSignals = forwardTerminalSignals(() => stop("interrupted"))
   const timeoutMs = control.timeoutMs ?? HYDRATION_RUN_TIMEOUT_MS
   const timer = setTimeout(() => stop(`timed out after ${timeoutMs} ms`), timeoutMs)
   try {
@@ -673,6 +685,7 @@ export async function runHydrationAssurance(
   } finally {
     clearTimeout(timer)
     control.signal?.removeEventListener("abort", onAbort)
+    releaseSignals()
   }
 }
 

package/src/capabilities-tool.ts

@@ -18,7 +18,7 @@ import {
 } from "@nifrajs/core/capabilities"
 import { expandOptionalParams } from "@nifrajs/core/pattern"
 import { type ReflectedMount, type ReflectedRoute, reflectRoutes } from "@nifrajs/core/reflection"
-import { scanStaticRouteText, stripComments, walkSource } from "./check.ts"
+import { scanStaticRouteText, scanStaticSocketText, stripComments, walkSource } from "./check.ts"
 
 // Import and re-export clauses are spelled out (a default binding, then `* as ns` or a `{ … }` list)
 // rather than scanned lazily, which is quadratic on a long semicolon-free module.
@@ -200,7 +200,10 @@ function resolveLocalModule(
     const fromAbsolute = join(cwd, from)
     const resolved = Bun.resolveSync(specifier, dirname(fromAbsolute))
     const rel = relative(cwd, resolved).replaceAll("\\", "/")
-    if (rel.startsWith("../") || isAbsolute(rel)) return undefined
+    // Outside the app is still the app's code: a workspace package resolves through its node_modules
+    // link to its source beside the app (`../../packages/db`), and an installed package may be hoisted
+    // above it. Both are walked, as a package in the app's own node_modules is.
+    if (isAbsolute(rel)) return undefined
     if (!sources.has(rel) && existsSync(resolved)) {
       try {
         sources.set(rel, readFileSync(resolved, "utf8"))
@@ -338,7 +341,10 @@ export async function collectCapabilityProjectReport(
   const sources = await readSources(cwd)
   const automatic = new Map<string, Set<string>>()
   for (const [file, content] of sources) {
-    for (const route of scanStaticRouteText(file, content)) {
+    for (const route of [
+      ...scanStaticRouteText(file, content, undefined, sources),
+      ...scanStaticSocketText(file, content, undefined, sources),
+    ]) {
       // A path ending in optional params is reflected as one route per form it serves.
       for (const path of staticRouteForms(route.path)) {
         const modules = automatic.get(routeKey(route.method, path)) ?? new Set<string>()
@@ -703,6 +709,12 @@ export async function runCapabilityCheck(
     // Stated on every run, passing or not: a gap is the report's own boundary, not a failure.
     for (const gap of result.report.gaps ?? [])
       console.log(`• known gap, not analyzed: ${gap.path} - ${gap.reason}`)
+    for (const route of result.report.routes) {
+      if (route.analysis === "declared")
+        console.log(
+          `• declared by an opaque mount, not analyzed: ${route.method} ${route.path} [${route.declared.join(", ")}]`,
+        )
+    }
     for (const finding of result.report.findings) console.log(`✖ ${finding.message}`)
     for (const violation of result.violations)
       console.log(

package/src/check-diagnostics.ts

@@ -10,7 +10,9 @@ import { join } from "node:path"
 import type { AssuranceConfig, AssuranceReport } from "@nifrajs/core/assurance"
 import type { CapabilityGap } from "@nifrajs/core/capabilities"
 import type { ProjectEvidenceSnapshot } from "@nifrajs/core/evidence"
+import type { ReflectedHookReport } from "@nifrajs/core/reflection"
 import type { CapabilityProjectReport } from "./capabilities-tool.ts"
+import { scanFetchText, scanStreamText } from "./check-scan.ts"
 import {
   type Diagnostic,
   type DiagnosticSuggestion,
@@ -20,9 +22,11 @@ import {
 import type { DuplicateInstallFinding } from "./doctor.ts"
 import type { PipelineReport } from "./pipeline-report.ts"
 import { freezeProjectFacts, type ProjectFactsSeed } from "./project-facts.ts"
+import { contractVisibilityRule } from "./rules/contract-visibility.ts"
 import { dataGuardRules } from "./rules/data-guard.ts"
 import { parseRulePacks, runRuleRegistry } from "./rules/index.ts"
 import { islandRules } from "./rules/islands.ts"
+import { retiredLayoutRule } from "./rules/layout.ts"
 import { LEGACY_RULE_CODES, LEGACY_RULE_ORDER, legacyRules } from "./rules/legacy.ts"
 import { nanoRules } from "./rules/nano.ts"
 import { pageRules } from "./rules/pages.ts"
@@ -72,8 +76,9 @@ export type CheckSuggestion = DiagnosticSuggestion
 export interface CheckResult {
   readonly ok: boolean
   readonly typecheck: "pass" | "fail" | "skipped"
-  /** Why `typecheck` is `"skipped"` (no tsconfig.json, typescript not installed, lints-only mode).
-   * Absent when the typecheck ran. Echoed in the human report so a skip is never a dim mystery. */
+  /** Why `typecheck` is `"skipped"` (no tsconfig.json, typescript not installed, lints-only mode), or
+   * why it failed when the compiler itself passed (zoned files outside its program). Echoed in the
+   * human report so a skip is never a dim mystery. */
   readonly typecheckNote?: string
   readonly diagnostics: readonly CheckDiagnostic[]
   /** Normalized diagnostics with stable codes for agents and external renderers. */
@@ -108,6 +113,13 @@ export interface CheckResult {
    * the `duplicate-install` diagnostics; this field is what `--json` consumers parse instead.
    */
   readonly identityPreflight?: IdentityPreflightResult
+  /**
+   * The hooks each backend route and each prefix's unmatched paths run (`nifra routes --hooks`), read
+   * from the `source` of `nifra.assurance.ts`, which check already loads - check runs no other app
+   * code. Omitted without that config, and when `maxDiagnostics` caps the output for the MCP transport,
+   * where `nifra_routes` with `hooks` returns it.
+   */
+  readonly hooks?: ReflectedHookReport
 }
 
 /** The `identityPreflight` slice of {@link CheckResult}. */
@@ -172,7 +184,7 @@ const MAX_IGNORE_GLOB_ALTERNATIVES = 64
  * The matcher supports the portable glob forms users expect here: `*`, `?`, `**`, character
  * classes, and brace alternatives.
  */
-function safeIgnoreGlobMatch(pattern: string, file: string): boolean {
+export function safeIgnoreGlobMatch(pattern: string, file: string): boolean {
   if (pattern.length === 0 || pattern.length > MAX_IGNORE_GLOB_LENGTH) return false
   for (const alternative of expandIgnoreGlobBraces(pattern)) {
     if (matchIgnoreGlobPath(alternative, file)) return true
@@ -356,6 +368,7 @@ export interface CheckTypecheckResult {
   readonly note?: string
   readonly output?: string
   readonly missingTypeScript?: boolean
+  readonly outsideProgram?: readonly string[]
 }
 
 export interface CheckAnalysisInput {
@@ -367,6 +380,19 @@ export interface CheckDiagnosticsOptions {
   readonly assurance?: CheckAssuranceContext
 }
 
+/**
+ * The prefixes of the mounts the assurance source declares `opaque` (a better-auth handler nifra
+ * cannot read): no typed client covers them, so a hand-written fetch into one is deliberate, exactly
+ * like a `nifra.check.json` `externalMounts` entry. A mount without that declaration stays checked.
+ */
+async function mountPrefixes(source: unknown): Promise<readonly string[]> {
+  if (source === undefined) return []
+  const { reflectMounts } = await import("@nifrajs/core/reflection")
+  return reflectMounts(source).flatMap((mount) =>
+    mount.opaque === undefined || mount.path === "/*" ? [] : [mount.path.slice(0, -"/*".length)],
+  )
+}
+
 export async function collectCheckDiagnostics(
   cwd: string,
   scan: CheckAnalysisInput,
@@ -422,6 +448,31 @@ export async function collectCheckDiagnostics(
       rulePacks: applicationRulePacks,
     },
   }
+  const configuredMounts = factsSeed.policies.checkConfig.externalMounts
+  const appMounts = (await mountPrefixes(loadedPolicy?.config?.source)).filter(
+    (prefix) => !configuredMounts.includes(prefix),
+  )
+  if (appMounts.length > 0) {
+    const externalMounts = [...configuredMounts, ...appMounts]
+    const files = factsSeed.source.files.map((file) => ({
+      file,
+      content: factsSeed.source.read(file) ?? "",
+    }))
+    factsSeed = {
+      ...factsSeed,
+      policies: {
+        ...factsSeed.policies,
+        checkConfig: { ...factsSeed.policies.checkConfig, externalMounts },
+      },
+      sourceFindings: {
+        ...factsSeed.sourceFindings,
+        fetches: files.flatMap(({ file, content }) => scanFetchText(file, content, externalMounts)),
+        streams: files.flatMap(({ file, content }) =>
+          scanStreamText(file, content, externalMounts),
+        ),
+      },
+    }
+  }
   const projectFacts = freezeProjectFacts(factsSeed)
   const ruleContext = {
     root: cwd,
@@ -433,9 +484,11 @@ export async function collectCheckDiagnostics(
   }
 
   const builtInRules = [
+    retiredLayoutRule,
     ...legacyRules,
     ...securityRules,
     ...routeRules,
+    contractVisibilityRule,
     ...pageRules,
     ...zoneRules,
     ...dataGuardRules,
@@ -514,7 +567,7 @@ export async function collectCheckDiagnostics(
     if (knownLegacyCodes.has(item.code)) continue
     compatibilityRows.push({
       rule: item.code,
-      severity: item.severity === "error" ? "error" : "warning",
+      severity: item.severity === "warn" ? "warning" : item.severity,
       code: item.code,
       ...(item.file === undefined ? {} : { file: item.file }),
       ...(item.line === undefined ? {} : { line: item.line }),
@@ -583,17 +636,27 @@ export async function collectCheckDiagnostics(
     shown.length < total ? shown.length + nonLegacyStructuredCount : finalStructured.length
 
   const doctor = projectFacts.packages.doctor
+  const outsideProgram = projectFacts.check.typecheck.outsideProgram?.length ?? 0
   const knownGaps = projectFacts.policies.capability?.report.gaps ?? []
+  const hookSource = projectFacts.policies.assurance?.config?.source
+  const hooks =
+    hookSource === undefined || opts.maxDiagnostics !== undefined
+      ? undefined
+      : (await import("@nifrajs/core/reflection")).reflectHooks(hookSource)
   const result: CheckResult = {
     ok: !finalDiagnostics.some((value) => value.severity === "error"),
-    typecheck: projectFacts.check.typecheck.ran
-      ? projectFacts.check.typecheck.ok
+    typecheck: !projectFacts.check.typecheck.ran
+      ? "skipped"
+      : projectFacts.check.typecheck.ok && outsideProgram === 0
         ? "pass"
-        : "fail"
-      : "skipped",
+        : "fail",
     ...(!projectFacts.check.typecheck.ran && projectFacts.check.typecheck.note !== undefined
       ? { typecheckNote: projectFacts.check.typecheck.note }
-      : {}),
+      : outsideProgram > 0
+        ? {
+            typecheckNote: `${outsideProgram} file(s) in zone folders are outside tsc's program, so the typecheck never read them`,
+          }
+        : {}),
     diagnostics: shown,
     ...(projectFacts.pipeline !== undefined ? { pipeline: projectFacts.pipeline } : {}),
     ...(doctor.ran
@@ -610,6 +673,7 @@ export async function collectCheckDiagnostics(
       ? {}
       : { externalMounts: checkConfig.externalMounts }),
     ...(knownGaps.length === 0 ? {} : { knownGaps }),
+    ...(hooks === undefined ? {} : { hooks }),
     ...(Object.keys(checkConfig.rules).length === 0 ? {} : { ruleOverrides: checkConfig.rules }),
     ...(shown.length < total ? { truncated: { shown: shown.length, total } } : {}),
   }