@nifrajs/cli 1.12.0 → 2.0.0

package/README.md

@@ -6,8 +6,8 @@ The `nifra` CLI — zero-config dev/build/start for a nifra app, plus the agent
 
 ```
 nifra dev     [--port <n>] [--poll]       True-HMR dev server (Vite + nifra SSR).
-nifra build   [--out <dir>]               Content-hashed client bundle + manifest.json.
-nifra start   [--port <n>] [--out <dir>]  Serve the built app (client + SSR) on Bun.
+nifra build   [--out <dir>] [--target <t>]  Complete deploy directory; target defaults to Bun.
+nifra start   [--port <n>] [--out <dir>]   Run the generated Bun server at <out>/server.js.
 nifra context                             Print this project's API + page routes + conventions.
 nifra mcp                                 MCP server (stdio) exposing this project to a coding agent.
 nifra check   [--json]                    Gate: typecheck + lints; --json includes fixes/suggestions.
@@ -72,6 +72,17 @@ For hand-rolled own-API `fetch()` calls, `nifra check` stays conservative: simpl
 that match a statically visible Nifra route get an exact typed-client rewrite diff; dynamic URLs, custom
 headers, bodies, query strings, or ambiguous routes fall back to manual steps.
 
+When a library such as Better Auth intentionally owns a mounted prefix outside the Nifra contract,
+declare that prefix in `nifra.check.json` so its relative calls do not keep CI red:
+
+```json
+{ "externalMounts": ["/auth"] }
+```
+
+The match is segment-anchored (`/auth` never suppresses `/authors`) and traversal paths are rejected.
+The normalized prefixes are echoed in human, JSON, and MCP results so the lint bypass stays auditable.
+This suppresses only the typed-client diagnostic; it does not mount or authorize the external handler.
+
 ## For AI coding agents
 
 **`nifra context`** prints this project's actual surface — API routes (from `backend.routes()`), page
@@ -98,6 +109,10 @@ an agent can act on the project, not just read about it. Core tools:
 - **`nifra_check`** — run the drift gate and get the structured `{ ok, typecheck, diagnostics[] }`
   result with suggestions, so the agent verifies its own work and fixes each diagnostic before finishing.
 - **`nifra_assure`** — evaluate `nifra.assurance.ts` and return the complete per-route evidence report.
+- **`nifra_levels`** - compute the cumulative verification ladder (L0 typed contract, L1 route
+  assurance, L2 capability lockfile, L3 trust manifest, L4 contract invariants) and return
+  `{ achieved, levels[] }`, so an agent can see what its change proves and read why a level it lost
+  no longer holds.
 - **`nifra_doctor`** — catch imported packages missing from `package.json`; with `autoFix:true`, write
   safe dependency entries when a version can be inferred locally and return exact `bun add` commands
   for anything that needs a package-manager decision.

package/dist/check.d.ts

@@ -20,8 +20,6 @@ export interface SourceFinding {
     readonly line: number;
     readonly snippet: string;
 }
-/** @deprecated kept for back-compat with existing tests; prefer {@link SourceFinding}. */
-export type FetchFinding = SourceFinding;
 /** A server-only-import finding, carrying the offending module specifier on top of the base location so
  * the diagnostic can show the import chain `routeFile → specifier` (the direct edge the regex scan sees). */
 export interface ServerImportFinding extends SourceFinding {
@@ -43,8 +41,17 @@ export interface StaticRouteFinding extends SourceFinding {
  * Shared by the source scanners here and by `nifra doctor` ({@link ./doctor.ts}).
  */
 export declare function stripComments(src: string): string;
-/** Scan one file's text for hand-rolled own-API `fetch()` calls. Pure + line-accurate. */
-export declare function scanFetchText(file: string, content: string): SourceFinding[];
+/** Blank comments and every quoted/template literal while preserving offsets. Unlike
+ * {@link stripComments}, this is a code-position mask: scanners use it to find a call expression in
+ * executable code, then inspect the original source for the call's literal argument. That prevents
+ * documentation strings such as `const example = 'client("/")'` from becoming diagnostics. */
+export declare function codePositionMask(src: string): string;
+/** Scan one file's text for hand-rolled own-API `fetch()` calls. Pure + line-accurate. `externalMounts`
+ * are intentional non-typed mount prefixes (from `nifra.check.json`, e.g. a mounted better-auth owning
+ * `/auth/**`) - a relative fetch into one is deliberate, not drift, so it's skipped. A fetch with an
+ * inline literal `x-nifra-data` header is Nifra's page-loader transport, not a backend API call, and is
+ * skipped too. */
+export declare function scanFetchText(file: string, content: string, externalMounts?: readonly string[]): SourceFinding[];
 /** Statically collect simple Nifra route registrations from source, without importing app code. */
 export declare function scanStaticRouteText(file: string, content: string): StaticRouteFinding[];
 /** Scan one file's text for untyped `client("…")` calls. Pure + line-accurate. */
@@ -100,7 +107,7 @@ export declare function resolveServerOnlyChains(file: string, content: string, r
  * the typed client's `data` to `never`. Pure + line-accurate; returns `[]` for files with no `server(` call. */
 export declare function scanResponseRoutes(file: string, content: string): SourceFinding[];
 export declare function walkSource(cwd: string, visit: (rel: string, content: string) => void): Promise<void>;
-/** Collect own-API `fetch()` findings across the project (kept for back-compat + reuse). */
+/** Collect own-API `fetch()` findings across the project. */
 export declare function scanProject(cwd: string): Promise<SourceFinding[]>;
 export interface ManifestDriftFinding {
     /** The committed server-manifest file (relative to cwd). */
@@ -121,7 +128,7 @@ export interface ManifestDriftFinding {
 export declare function scanServerManifestDrift(cwd: string): Promise<ManifestDriftFinding[]>;
 /** A single machine-readable check failure — the unit an agent (or CI) acts on. */
 export interface CheckDiagnostic {
-    readonly rule: "typecheck" | "typed-client" | "untyped-client" | "server-only-import" | "response-route" | "undeclared-dependency" | "duplicate-install" | "server-manifest-drift" | "manifest-drift" | "capability-assurance" | "capability-config";
+    readonly rule: "typecheck" | "typed-client" | "untyped-client" | "server-only-import" | "response-route" | "undeclared-dependency" | "duplicate-install" | "server-manifest-drift" | "manifest-drift" | "capability-assurance" | "capability-config" | "check-config";
     /** `error` fails the gate (a real contract break); `warning` is advisory — surfaced to the agent but
      * does NOT fail `nifra check`, for patterns that are sometimes intentional (a route returning a raw
      * `Response`, which silently drops the typed client to `data: never` but is valid for files/redirects). */
@@ -162,6 +169,10 @@ export interface CheckResult {
     readonly ok: boolean;
     readonly typecheck: "pass" | "fail" | "skipped";
     readonly diagnostics: readonly CheckDiagnostic[];
+    /** Intentional non-typed mount prefixes declared in `nifra.check.json` (e.g. `/auth` for a mounted
+     * better-auth). Echoed here so `--json` / the MCP tool / the report can show what the typed-client scan
+     * deliberately skipped - a suppressed prefix stays auditable instead of silently hiding real drift. */
+    readonly externalMounts?: readonly string[];
     /** Set only when the caller passed `maxDiagnostics` and there were more — `diagnostics` then holds the
      * first `shown` of `total`. It caps the serialized size so the `nifra_check` MCP tool can't emit a
      * message large enough to break the stdio transport; fix the shown diagnostics and re-run for the rest. */

package/dist/check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"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"}

package/dist/check.js

@@ -22,7 +22,7 @@ import { Glob } from "bun";
 // i.e. same-origin = this app's own API. `(?<![.\w])` skips `.fetch(` (a method) and `prefetch(`; the
 // `(?!\/)` skips protocol-relative `//host` (an external origin). A variable arg (`fetch(url)`) is left
 // alone on purpose — undecidable from source, and flagging it would punish legitimate external calls.
-const OWN_API_FETCH = /(?<![.\w])fetch\s*\(\s*['"`]\/(?!\/)/g;
+const GLOBAL_FETCH_CALL = /(?<![.\w])fetch\s*\(/g;
 const FETCH_CALL = /(?<![.\w])fetch\s*\(/g;
 const HTTP_VERBS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
 const SIMPLE_REWRITE_METHODS = new Set(["GET", "DELETE", "HEAD", "OPTIONS"]);
@@ -253,12 +253,180 @@ export function stripComments(src) {
     }
     return out.join("");
 }
-/** Scan one file's text for hand-rolled own-API `fetch()` calls. Pure + line-accurate. */
-export function scanFetchText(file, content) {
+/** Blank comments and every quoted/template literal while preserving offsets. Unlike
+ * {@link stripComments}, this is a code-position mask: scanners use it to find a call expression in
+ * executable code, then inspect the original source for the call's literal argument. That prevents
+ * documentation strings such as `const example = 'client("/")'` from becoming diagnostics. */
+export function codePositionMask(src) {
+    const out = src.split("");
+    const n = src.length;
+    let i = 0;
+    const blank = (a, b) => {
+        for (let k = a; k < b; k++)
+            if (out[k] !== "\n")
+                out[k] = " ";
+    };
+    while (i < n) {
+        const c = src[i];
+        const d = src[i + 1];
+        if (c === "/" && d === "/") {
+            let j = i + 2;
+            while (j < n && src[j] !== "\n")
+                j++;
+            blank(i, j);
+            i = j;
+        }
+        else if (c === "/" && d === "*") {
+            let j = i + 2;
+            while (j < n && !(src[j] === "*" && src[j + 1] === "/"))
+                j++;
+            j = Math.min(j + 2, n);
+            blank(i, j);
+            i = j;
+        }
+        else if (c === "'" || c === '"' || c === "`") {
+            const quote = c;
+            let j = i + 1;
+            while (j < n && src[j] !== quote) {
+                if (src[j] === "\\")
+                    j++;
+                j++;
+            }
+            j = Math.min(j + 1, n);
+            blank(i, j);
+            i = j;
+        }
+        else {
+            i++;
+        }
+    }
+    return out.join("");
+}
+const firstArgumentIndex = (content, callEnd) => {
+    let index = callEnd;
+    while (/\s/.test(content[index] ?? ""))
+        index++;
+    return index;
+};
+// Read the literal URL path of a `fetch("/…")` call starting at `start` (the index of the leading `/`),
+// stopping at the first quote / query / hash / template-expression boundary, and test it against the
+// allowlist. A template like `/auth/${id}` matches on its literal head (`/auth`), so a dynamic sign-in URL
+// is covered too. Match is segment-anchored - `/auth` blesses `/auth` and `/auth/**`, never `/authors`.
+function matchesExternalMount(content, start, mounts) {
+    let end = start;
+    while (end < content.length) {
+        const ch = content[end];
+        if (ch === "'" || ch === '"' || ch === "`" || ch === "?" || ch === "#")
+            break;
+        if (ch === "$" && content[end + 1] === "{")
+            break;
+        end++;
+    }
+    const path = content.slice(start, end);
+    // A `..` segment means the runtime path escapes the literal prefix (`/auth/../api/admin` resolves to
+    // `/api/admin`), so it must NOT be blessed by an `/auth` mount - never let traversal hide a real own-API
+    // fetch. Match is otherwise segment-anchored (`/auth` blesses `/auth` and `/auth/**`, never `/authors`).
+    try {
+        if (path.split("/").some((segment) => decodeURIComponent(segment) === ".."))
+            return false;
+    }
+    catch {
+        // A malformed escape is not a prefix we can prove stays inside the external mount.
+        return false;
+    }
+    return mounts.some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
+}
+function findTopLevelPropertyColon(src) {
+    let depth = 0;
+    let quote;
+    for (let i = 0; i < src.length; i++) {
+        const c = src[i];
+        if (quote !== undefined) {
+            if (c === "\\") {
+                i++;
+                continue;
+            }
+            if (c === quote)
+                quote = undefined;
+            continue;
+        }
+        if (c === '"' || c === "'" || c === "`") {
+            quote = c;
+            continue;
+        }
+        if (c === "(" || c === "{" || c === "[")
+            depth++;
+        else if (c === ")" || c === "}" || c === "]")
+            depth--;
+        else if (c === ":" && depth === 0)
+            return i;
+    }
+    return undefined;
+}
+function parseStaticPropertyName(raw) {
+    const name = raw.trim();
+    if (IDENT.test(name))
+        return name;
+    const quoted = parseQuotedLiteral(name);
+    if (quoted !== undefined)
+        return quoted;
+    if (name.startsWith("[") && name.endsWith("]")) {
+        return parseQuotedLiteral(name.slice(1, -1).trim());
+    }
+    return undefined;
+}
+/** Return a statically named property from a plain object literal. Deliberately does not follow
+ * spreads, identifiers, or helper calls: only an inline literal proves this fetch is Nifra's page-data
+ * transport rather than an arbitrary same-origin API request. */
+function staticObjectProperty(raw, name) {
+    if (raw === undefined)
+        return undefined;
+    const object = raw.trim();
+    if (!object.startsWith("{") || !object.endsWith("}"))
+        return undefined;
+    const properties = splitTopLevelArgs(object.slice(1, -1));
+    if (properties === undefined)
+        return undefined;
+    for (const property of properties) {
+        const colon = findTopLevelPropertyColon(property);
+        if (colon === undefined || parseStaticPropertyName(property.slice(0, colon)) !== name)
+            continue;
+        return property.slice(colon + 1).trim();
+    }
+    return undefined;
+}
+function hasLiteralNifraDataHeader(content, openParen) {
+    const closeParen = findMatchingParen(content, openParen);
+    if (closeParen === undefined)
+        return false;
+    const args = splitTopLevelArgs(content.slice(openParen + 1, closeParen));
+    if (args === undefined || args.length !== 2)
+        return false;
+    const headers = staticObjectProperty(args[1], "headers");
+    return staticObjectProperty(headers, "x-nifra-data") !== undefined;
+}
+/** Scan one file's text for hand-rolled own-API `fetch()` calls. Pure + line-accurate. `externalMounts`
+ * are intentional non-typed mount prefixes (from `nifra.check.json`, e.g. a mounted better-auth owning
+ * `/auth/**`) - a relative fetch into one is deliberate, not drift, so it's skipped. A fetch with an
+ * inline literal `x-nifra-data` header is Nifra's page-loader transport, not a backend API call, and is
+ * skipped too. */
+export function scanFetchText(file, content, externalMounts = []) {
     const out = [];
     const lines = content.split("\n");
-    OWN_API_FETCH.lastIndex = 0;
-    for (let m = OWN_API_FETCH.exec(content); m !== null; m = OWN_API_FETCH.exec(content)) {
+    const code = codePositionMask(content);
+    GLOBAL_FETCH_CALL.lastIndex = 0;
+    for (let m = GLOBAL_FETCH_CALL.exec(code); m !== null; m = GLOBAL_FETCH_CALL.exec(code)) {
+        const argument = firstArgumentIndex(content, m.index + m[0].length);
+        const quote = content[argument];
+        if (quote !== "'" && quote !== '"' && quote !== "`")
+            continue;
+        if (content[argument + 1] !== "/" || content[argument + 2] === "/")
+            continue;
+        const openParen = m.index + m[0].lastIndexOf("(");
+        if (hasLiteralNifraDataHeader(content, openParen))
+            continue;
+        if (externalMounts.length > 0 && matchesExternalMount(content, argument + 1, externalMounts))
+            continue;
         const line = lineAt(content, m.index);
         out.push({ file, line, snippet: (lines[line - 1] ?? "").trim() });
     }
@@ -278,13 +446,18 @@ export function scanStaticRouteText(file, content) {
 // the compiler has nothing to derive types from, so the anti-drift guarantee silently vanishes.
 // `client<typeof app>("…")` has `<…>` between the name and `(` so it never matches; the published-
 // contract form `client(contract, url)` starts with an identifier, not a quote — also unmatched.
-const UNTYPED_CLIENT = /(?<![.\w])client\s*\(\s*['"`]/g;
+const CLIENT_CALL = /(?<![.\w])client\s*\(/g;
 /** Scan one file's text for untyped `client("…")` calls. Pure + line-accurate. */
 export function scanUntypedClient(file, content) {
     const out = [];
     const lines = content.split("\n");
-    UNTYPED_CLIENT.lastIndex = 0;
-    for (let m = UNTYPED_CLIENT.exec(content); m !== null; m = UNTYPED_CLIENT.exec(content)) {
+    const code = codePositionMask(content);
+    CLIENT_CALL.lastIndex = 0;
+    for (let m = CLIENT_CALL.exec(code); m !== null; m = CLIENT_CALL.exec(code)) {
+        const argument = firstArgumentIndex(content, m.index + m[0].length);
+        const quote = content[argument];
+        if (quote !== "'" && quote !== '"' && quote !== "`")
+            continue;
         const line = lineAt(content, m.index);
         out.push({ file, line, snippet: (lines[line - 1] ?? "").trim() });
     }
@@ -298,8 +471,12 @@ export function scanServerOnlyImports(file, content) {
         return [];
     const out = [];
     const lines = content.split("\n");
+    const code = stripComments(content);
+    const positions = codePositionMask(content);
     STATIC_IMPORT.lastIndex = 0;
-    for (let m = STATIC_IMPORT.exec(content); m !== null; m = STATIC_IMPORT.exec(content)) {
+    for (let m = STATIC_IMPORT.exec(code); m !== null; m = STATIC_IMPORT.exec(code)) {
+        if (positions[m.index] === " ")
+            continue;
         const specifier = m[1] ?? "";
         if (!SERVER_ONLY.test(specifier))
             continue;
@@ -345,7 +522,11 @@ const staticImportRegex = () => new RegExp(STATIC_IMPORT.source, STATIC_IMPORT.f
 function staticImportEdges(content) {
     const edges = [];
     const re = staticImportRegex();
-    for (let m = re.exec(content); m !== null; m = re.exec(content)) {
+    const code = stripComments(content);
+    const positions = codePositionMask(content);
+    for (let m = re.exec(code); m !== null; m = re.exec(code)) {
+        if (positions[m.index] === " ")
+            continue;
         if (m[1] !== undefined)
             edges.push({ specifier: m[1], index: m.index });
     }
@@ -511,10 +692,22 @@ export function scanResponseRoutes(file, content) {
     RESPONSE_RETURN.lastIndex = 0;
     for (let m = RESPONSE_RETURN.exec(code); m !== null; m = RESPONSE_RETURN.exec(code)) {
         const line = lineAt(content, m.index);
-        out.push({ file, line, snippet: (lines[line - 1] ?? "").trim() });
+        // A `// nifra-expect raw-response` pragma marks an intentional raw Response (a file/redirect that can't
+        // be a typed route), silencing this advisory. Honor it on the return line itself, OR on the line above
+        // ONLY when that line is a standalone comment - so a TRAILING pragma on one route's return line can't
+        // leak down and suppress the very next route's genuine advisory. `stripComments` blanks the pragma in
+        // `code` (so it never affects the match); the raw `lines` still carry it.
+        const thisLine = lines[line - 1] ?? "";
+        const aboveLine = lines[line - 2] ?? "";
+        const aboveSuppresses = aboveLine.trimStart().startsWith("//") && aboveLine.includes(RAW_RESPONSE_PRAGMA);
+        if (thisLine.includes(RAW_RESPONSE_PRAGMA) || aboveSuppresses)
+            continue;
+        out.push({ file, line, snippet: thisLine.trim() });
     }
     return out;
 }
+/** The opt-out pragma that suppresses the {@link scanResponseRoutes} advisory for an intentional raw Response. */
+const RAW_RESPONSE_PRAGMA = "nifra-expect raw-response";
 /** Walk the project's `.ts`/`.tsx` source (skipping deps/build/tests), calling `visit` per file.
  * Exported so `nifra doctor` ({@link ./doctor.ts}) scans the same source surface as `nifra check`. */
 /**
@@ -565,7 +758,7 @@ export async function walkSource(cwd, visit) {
     }
 }
 const bySite = (a, b) => a.file.localeCompare(b.file) || a.line - b.line;
-/** Collect own-API `fetch()` findings across the project (kept for back-compat + reuse). */
+/** Collect own-API `fetch()` findings across the project. */
 export async function scanProject(cwd) {
     const out = [];
     await walkSource(cwd, (rel, content) => out.push(...scanFetchText(rel, content)));
@@ -671,10 +864,32 @@ async function typecheck(cwd, signal) {
 }
 // `src/x.tsx(12,5): error TS2322: <message>` → one structured diagnostic.
 const TSC_LINE = /^(.+?)\((\d+),\d+\):\s*(?:error|warning)\s+TS\d+:\s*(.+)$/;
+/** Load `nifra.check.json` if present. Fail-open + total: absent → empty; malformed → empty plus a parse
+ * `error` the caller surfaces as a `warning` diagnostic (never throws, never blocks the gate). Mount
+ * entries are normalized to bare path prefixes (`/auth/**` and `/auth/` both become `/auth`). */
+async function loadCheckConfig(cwd) {
+    const path = join(cwd, "nifra.check.json");
+    if (!existsSync(path))
+        return { config: { externalMounts: [] } };
+    try {
+        const parsed = JSON.parse(await Bun.file(path).text());
+        const raw = Array.isArray(parsed.externalMounts) ? parsed.externalMounts : [];
+        const externalMounts = raw
+            .filter((m) => typeof m === "string" && m.startsWith("/"))
+            .map((m) => m.replace(/\/\*+$/, "").replace(/\/+$/, "") || "/");
+        return { config: { externalMounts } };
+    }
+    catch (error) {
+        return {
+            config: { externalMounts: [] },
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
 const UNTYPED_CLIENT_HINT = 'client("…") without a type argument — write client<typeof app>("…") (or client(contract, url)) so the compiler can catch drift';
 const FETCH_HINT = "hand-rolled fetch() to your own API — call it through client<typeof app> (from @nifrajs/client) so the compiler catches drift";
 const SERVER_IMPORT_HINT = "server-only import in a route module (bundled for the browser) — reach it via c.db / ctx.api inside a loader, never a top-level import";
-const RESPONSE_ROUTE_HINT = "route handler returns a raw Response — the typed client infers `data: never`, so drift detection is lost for this route. Return a plain object (it's serialized for you), or add `{ response: t.… }` to the route if a raw Response is intended (file/redirect/stream)";
+const RESPONSE_ROUTE_HINT = "route handler returns a raw Response - the typed client infers `data: never`, so drift detection is lost for this route. Return a plain object (it's serialized for you); for a stream use a typed SSE route (`app.sse(...)`), which keeps typed events; or, if a raw Response is intended (file/redirect), add `{ response: t.… }` or a `// nifra-expect raw-response` comment to mark it and silence this";
 const UNDECLARED_DEP_HINT = "imported package is not declared in package.json dependencies — run bun add to declare it";
 const MANIFEST_DRIFT_HINT = "server-manifest.ts is out of sync with routes/ — re-run the build to regenerate it (a disk-less worker bakes this route table, so the drift is a silent edge break), then commit it";
 const TRUST_MANIFEST_DRIFT_HINT = "nifra.manifest.json is missing, invalid, or out of sync — run `nifra manifest emit`, review it, and commit the regenerated trust artifact";
@@ -794,7 +1009,8 @@ function responseRouteSuggestion() {
         title: "Preserve typed-client response inference",
         steps: [
             "Prefer returning a plain object from JSON routes; nifra serializes it for you.",
-            "If this route must return a raw Response (redirect, file, stream), declare an explicit response schema or accept the warning.",
+            "For a stream, use a typed SSE route - `app.sse(...)` (or `sse(c, run)` from `@nifrajs/core/server`) - which keeps typed events instead of collapsing the client to `data: never`.",
+            "If this route must return a raw Response (redirect, file), declare an explicit response schema, or add a `// nifra-expect raw-response` comment above the return to mark it intentional and silence this advisory.",
         ],
     };
 }
@@ -809,6 +1025,9 @@ export async function collectCheckResult(cwd, opts = {}) {
     // Route modules (rel + content) collected during the walk, so the TRANSITIVE server-only resolution
     // (#4.4) — which needs fs-backed import resolution, not just per-file text — runs after the walk.
     const routeModules = [];
+    // Load the optional check config first - the typed-client scan needs the external-mount allowlist as it
+    // walks. It's a tiny pure-JSON read; a malformed file surfaces as a warning below, never blocking.
+    const { config: checkConfig, error: checkConfigError } = await loadCheckConfig(cwd);
     // lintsOnly: skip the tsc pass (seconds on a big project) and run just the near-instant source
     // lints — the agent inner-loop mode; the full gate stays the definition of done.
     const [tc, _, dr, manifestDrift] = await Promise.all([
@@ -816,7 +1035,7 @@ export async function collectCheckResult(cwd, opts = {}) {
             ? Promise.resolve({ ran: false, ok: true, note: "skipped (lintsOnly)" })
             : typecheck(cwd, opts.signal),
         walkSource(cwd, (rel, content) => {
-            fetches.push(...scanFetchText(rel, content));
+            fetches.push(...scanFetchText(rel, content, checkConfig.externalMounts));
             staticRoutes.push(...scanStaticRouteText(rel, content));
             untypedClients.push(...scanUntypedClient(rel, content));
             if (ROUTE_FILE.test(rel))
@@ -854,6 +1073,15 @@ export async function collectCheckResult(cwd, opts = {}) {
         serverImports.push(...resolveServerOnlyChains(rel, content, resolveModule, readModule));
     }
     const diagnostics = [];
+    if (checkConfigError !== undefined) {
+        diagnostics.push({
+            rule: "check-config",
+            severity: "warning",
+            file: "nifra.check.json",
+            message: `nifra.check.json could not be parsed (${checkConfigError}) - its external-mount allowlist was ignored`,
+            fix: "Fix the JSON syntax in nifra.check.json",
+        });
+    }
     if (tc.ran && !tc.ok) {
         const lines = (tc.output ?? "").split("\n");
         let matched = false;
@@ -1114,6 +1342,9 @@ export async function collectCheckResult(cwd, opts = {}) {
         ok: !diagnostics.some((diagnostic) => diagnostic.severity === "error"),
         typecheck: tc.ran ? (tc.ok ? "pass" : "fail") : "skipped",
         diagnostics: shown,
+        ...(checkConfig.externalMounts.length > 0
+            ? { externalMounts: checkConfig.externalMounts }
+            : {}),
         ...(shown.length < total ? { truncated: { shown: shown.length, total } } : {}),
     };
 }
@@ -1130,6 +1361,9 @@ export async function runCheck(cwd, opts = {}) {
         : result.typecheck === "fail"
             ? "✗ typecheck failed — the frontend/backend contract is broken"
             : "• typecheck skipped (no tsconfig / typescript not installed)");
+    if (result.externalMounts !== undefined && result.externalMounts.length > 0) {
+        console.log(`• intentional external mounts (not typed-client checked): ${result.externalMounts.join(", ")}`);
+    }
     const counts = (rule) => result.diagnostics.filter((d) => d.rule === rule);
     for (const [rule, label] of [
         ["typecheck", "typecheck"],
@@ -1143,6 +1377,7 @@ export async function runCheck(cwd, opts = {}) {
         ["manifest-drift", "versioned trust manifest drift"],
         ["capability-assurance", "effect/capability assurance"],
         ["capability-config", "capability assurance config"],
+        ["check-config", "nifra.check.json"],
     ]) {
         const ds = counts(rule);
         if (rule === "response-route") {
@@ -1171,6 +1406,12 @@ export async function runCheck(cwd, opts = {}) {
         }
     }
     console.log(result.ok ? "\n✓ check passed" : "\n✗ check failed");
+    // Discoverability nudge: a project with no `.mcp.json` hasn't wired its nifra MCP for coding agents.
+    // `nifra init-agents` writes it (+ .cursor/mcp.json + a CLAUDE.md preamble), no-clobber. A non-fatal
+    // one-line tip in the human report only (the `--json` path returns above, unaffected).
+    if (!existsSync(join(cwd, ".mcp.json"))) {
+        console.log("\ntip: no .mcp.json here - run `nifra init-agents` to wire this project's MCP + agent files (no-clobber).");
+    }
     return result.ok;
 }
 //# sourceMappingURL=check.js.map