@nifrajs/cli 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -97,3 +97,11 @@ claude mcp add nifra -- nifra mcp
 
 Run the client from (or point it at) your project root. The protocol is hand-rolled
 (newline-delimited JSON-RPC 2.0) — no SDK dependency.
+
+## For AI agents
+
+Start with [`LLM.md`](./LLM.md) — this package's contract card (the exports you call + its footguns),
+one cheap read instead of the whole corpus. For the wider framework: the repo's
+[`AGENTS.md`](../../AGENTS.md) is the copy-paste quick reference, and
+[`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
+done-gate, or `nifra mcp` to give the agent live project tools.

package/dist/check.d.ts

@@ -22,6 +22,12 @@ export interface SourceFinding {
 }
 /** @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 {
+    /** The server-only module specifier the route top-level-imports (e.g. `pg`, `node:fs`, `../db`). */
+    readonly specifier: string;
+}
 export interface StaticRouteFinding extends SourceFinding {
     readonly method: string;
     readonly path: string;
@@ -44,8 +50,52 @@ export declare function scanStaticRouteText(file: string, content: string): Stat
 /** Scan one file's text for untyped `client("…")` calls. Pure + line-accurate. */
 export declare function scanUntypedClient(file: string, content: string): SourceFinding[];
 /** Scan a route module for top-level server-only imports. Returns `[]` for non-route files (only
- * `routes/` modules are browser-bundled, so a server-only import elsewhere is fine). Pure. */
-export declare function scanServerOnlyImports(file: string, content: string): SourceFinding[];
+ * `routes/` modules are browser-bundled, so a server-only import elsewhere is fine). Each finding carries
+ * the offending `specifier` so the diagnostic can render the `routeFile → specifier` chain. Pure. */
+export declare function scanServerOnlyImports(file: string, content: string): ServerImportFinding[];
+/** Extract the static, non-type import specifiers from a module's source (the edges to follow/inspect).
+ * Mirrors {@link STATIC_IMPORT}, so `import type` + dynamic `import()` are already excluded. Pure. */
+export declare function parseStaticImports(content: string): string[];
+/** The server-only SINK an import specifier names directly (a `node:`/`bun:` builtin or a known
+ * server-only package), or `undefined` if it isn't a by-name sink. Pure — the label is the specifier
+ * itself (it's already the actionable name). */
+export declare function directSinkSpecifier(spec: string): string | undefined;
+/** One transitive server-only finding: the route module, the route's offending top-level import (the
+ * first hop / `specifier`), the line + snippet of that import, and the FULL chain to the sink. */
+export interface TransitiveServerImportFinding extends ServerImportFinding {
+    /** `[routeFile, ...as-written specifiers…, sink]` — the shortest path the walk found. Length 2 means
+     * the route imports the sink directly (same as the regex scan's direct edge). */
+    readonly chain: readonly string[];
+    /** True when a precise transitive resolve wasn't possible for the first hop (a bare pkg / path alias),
+     * so the chain is the honest direct edge rather than a fabricated deeper path. */
+    readonly fallback: boolean;
+}
+/** A resolver from `(fromFile, specifier)` to an absolute module path, or `undefined` when it can't be
+ * resolved precisely (bare pkg, path alias, missing file). Abstracted so the BFS is unit-testable with a
+ * fake graph (no real fs). The production resolver wraps `Bun.resolveSync`. */
+export type ModuleResolver = (fromFile: string, specifier: string) => string | undefined;
+/** Reads a resolved module's source, or `undefined` if unreadable. Abstracted for the same reason. */
+export type ModuleReader = (absPath: string) => string | undefined;
+/**
+ * BFS the LOCAL module graph from a route file for the SHORTEST import chain that reaches a server-only
+ * sink, returning `[routeFile, …as-written specifiers…, sink]` or `undefined` if none is reachable. A
+ * node's outgoing edges are its static imports; an edge is followed only when it's a RELATIVE specifier
+ * that `resolve` maps to a readable local file (so the walk never descends into node_modules or chases an
+ * unresolvable alias). At each node, a by-name sink import (`node:fs`, `postgres`) OR a resolved
+ * `*.server` / `server-only`-marked dependency terminates the chain. Bounded by depth + a visited set, so
+ * it's linear and cycle-free. `routeFile`/`routeContent` seed the walk; `resolve`/`read` supply the graph
+ * — pure given those, so it's unit-testable with a fake graph.
+ */
+export declare function walkServerOnlyChain(routeFile: string, routeContent: string, resolve: ModuleResolver, read: ModuleReader): readonly string[] | undefined;
+/**
+ * Resolve the FULL transitive server-only chain(s) for a route module, given a real fs-backed resolver +
+ * reader. For each of the route's top-level imports, if a precise transitive walk finds a sink, the
+ * finding carries the full chain; otherwise — when the first hop is itself a direct by-name sink the
+ * regex scan already flags, or when a relative import can't be resolved — it falls back to the DIRECT
+ * edge (`fallback: true`), never a fabricated chain. Returns one finding per offending top-level import,
+ * de-duplicated to the shortest chain per first-hop specifier. Non-route files yield `[]`.
+ */
+export declare function resolveServerOnlyChains(file: string, content: string, resolve: ModuleResolver, read: ModuleReader): TransitiveServerImportFinding[];
 /** Scan a backend module (one that calls `server(`) for handlers returning a raw `Response`, which collapses
  * 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[];
@@ -54,9 +104,26 @@ export declare function scanResponseRoutes(file: string, content: string): Sourc
 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). */
 export declare function scanProject(cwd: string): Promise<SourceFinding[]>;
+export interface ManifestDriftFinding {
+    /** The committed server-manifest file (relative to cwd). */
+    readonly file: string;
+    /** Route files in `routes/` missing from the manifest (stale manifest — these routes won't serve). */
+    readonly missing: readonly string[];
+    /** Route files the manifest imports that no longer exist in `routes/` (a dangling import). */
+    readonly extra: readonly string[];
+}
+/**
+ * Scan the project for committed, generated `server-manifest.ts` files and report any that have drifted
+ * from the live `routes/` tree. For each, the routes dir is derived from the manifest's own import
+ * prefix (so a manifest that imports `../routes/x` is checked against the sibling `routes/`), its route
+ * imports are parsed (`parseManifestRouteFiles`), and the set is diffed against the actual route files
+ * on disk. A clean manifest yields no finding. Returns one finding per drifted manifest. Never throws on
+ * a per-manifest miss (an unreadable routes dir is simply skipped).
+ */
+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";
+    readonly rule: "typecheck" | "typed-client" | "untyped-client" | "server-only-import" | "response-route" | "undeclared-dependency" | "server-manifest-drift";
     /** `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). */
@@ -71,6 +138,18 @@ export interface CheckDiagnostic {
     /** A richer, agent-oriented fix hint. Diffs are only emitted when the edit is mechanical and local;
      * ambiguous cases give concrete steps instead of pretending the checker can safely rewrite code. */
     readonly suggestion?: CheckSuggestion;
+    /**
+     * The import chain that pulls server-only code into the browser bundle, as display labels
+     * `[routeFile, …as-written specifiers…, sink]`. Set only on `server-only-import`.
+     *
+     * #4.4: this is now the FULL **transitive** chain — a bounded import-resolution walk (`Bun.resolveSync`
+     * from each file's dir, BFS the local module graph) follows `route → ../data → ../db → node:crypto`,
+     * matching the build leak-guard's depth (`detectNodeBuiltinsInClient` in `@nifrajs/web/build`). A
+     * length-2 chain (`[routeFile, specifier]`) means the route imports the sink directly. When a hop can't
+     * be resolved precisely (a bare pkg, a tsconfig path alias), the walk degrades to the honest direct
+     * edge rather than fabricating a deeper path — never a lie.
+     */
+    readonly chain?: readonly string[];
 }
 export interface CheckSuggestion {
     readonly kind: "edit" | "command" | "manual";

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

@@ -15,7 +15,8 @@
  * `nifra_check` MCP tool, so an agent acts on diagnostics instead of scraping prose). Exits non-zero if
  * anything fails. Pure scanners (`scanFetchText`, `scanServerOnlyImports`) are unit-tested.
  */
-import { join } from "node:path";
+import { readFileSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
 import { Glob } from "bun";
 // `fetch( <ws> ('|"|`) / (not /)` — a string/template arg starting with a single `/` is a relative URL,
 // i.e. same-origin = this app's own API. `(?<![.\w])` skips `.fetch(` (a method) and `prefetch(`; the
@@ -287,7 +288,8 @@ export function scanUntypedClient(file, content) {
     return out;
 }
 /** Scan a route module for top-level server-only imports. Returns `[]` for non-route files (only
- * `routes/` modules are browser-bundled, so a server-only import elsewhere is fine). Pure. */
+ * `routes/` modules are browser-bundled, so a server-only import elsewhere is fine). Each finding carries
+ * the offending `specifier` so the diagnostic can render the `routeFile → specifier` chain. Pure. */
 export function scanServerOnlyImports(file, content) {
     if (!ROUTE_FILE.test(file))
         return [];
@@ -295,10 +297,196 @@ export function scanServerOnlyImports(file, content) {
     const lines = content.split("\n");
     STATIC_IMPORT.lastIndex = 0;
     for (let m = STATIC_IMPORT.exec(content); m !== null; m = STATIC_IMPORT.exec(content)) {
-        if (!SERVER_ONLY.test(m[1] ?? ""))
+        const specifier = m[1] ?? "";
+        if (!SERVER_ONLY.test(specifier))
             continue;
         const line = lineAt(content, m.index);
-        out.push({ file, line, snippet: (lines[line - 1] ?? "").trim() });
+        out.push({ file, line, snippet: (lines[line - 1] ?? "").trim(), specifier });
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------------------------------
+// #4.4 — TRANSITIVE import-chain resolution for `server-only-import`. `scanServerOnlyImports` above is a
+// pure per-file regex scan: it sees only the route's DIRECT `import` line, so it reports the direct edge
+// `routes/x → ../db`. The build leak-guard, which has the real module graph, reports the full transitive
+// `route → ../data → ../db → pg`. These helpers give `nifra check` the same depth via a BOUNDED
+// import-resolution walk: from a flagged route, resolve its local imports (`Bun.resolveSync`), BFS the
+// local module graph, and build the shortest chain to a server-only SINK. It's best-effort: an import
+// that can't be precisely resolved (a bare pkg, a tsconfig path alias) falls back to the direct edge.
+// ---------------------------------------------------------------------------------------------------
+// Server-only specifiers that are TERMINAL sinks — a bare `node:`/`bun:` builtin or a known server-only
+// npm package. These are never local source we can walk into, so the chain ends here. (Same vocabulary
+// as SERVER_ONLY, minus the relative `../db` arm — a relative `db` module IS local source we resolve.)
+const SERVER_ONLY_SINK = /^(?:node:|bun:)|^(?:postgres|pg|mysql2|ioredis|redis|better-sqlite3|mongodb|@libsql\/client)$|^drizzle-orm\/(?:node-postgres|postgres-js|bun-sqlite|libsql|mysql2|pglite)\b/;
+// The `.server` convention: a module named `*.server.ts(x)` is server-only (the client build empties it).
+const SERVER_MODULE_FILE = /\.server(\.[cm]?[jt]sx?)?$/;
+// The explicit poison-import marker (`@nifrajs/web/server-only`) — a module opting into the client-leak
+// guard. A resolved file whose source carries this side-effect import is a server-only sink.
+const SERVER_ONLY_MARKER_IMPORT = /import\s+["']@nifrajs\/web\/server-only["']/;
+// Depth/visited caps keep the walk linear + cycle-safe. A route's server-only dependency sits within a
+// few hops in practice; the bound stops a pathological graph from blowing up the per-file scan.
+const TRANSITIVE_MAX_DEPTH = 8;
+const TRANSITIVE_MAX_VISITED = 200;
+/** A relative module specifier (`./x`, `../y`) — the only kind we resolve + walk into (a bare specifier
+ * is either a sink we recognise by name or a third-party dep we don't follow into node_modules). */
+const isRelativeSpecifier = (spec) => spec.startsWith("./") || spec.startsWith("../");
+// A FRESH copy of the static-import regex per scan. The transitive walk is REENTRANT — the outer
+// per-route loop and the inner BFS both scan imports — and a single shared global-flag regex carries
+// `lastIndex` state, so reusing the module-level `STATIC_IMPORT` across nested calls corrupts the outer
+// loop's position (it restarts forever). A fresh instance per call keeps each scan's state private.
+const staticImportRegex = () => new RegExp(STATIC_IMPORT.source, STATIC_IMPORT.flags);
+/** Extract the static, non-type import specifiers from a module's source (the edges to follow/inspect),
+ * each with the match index (for line attribution). Mirrors {@link STATIC_IMPORT}, so `import type` +
+ * dynamic `import()` are already excluded. Uses a fresh regex instance, so it's safe under the reentrant
+ * transitive walk. Pure. */
+function staticImportEdges(content) {
+    const edges = [];
+    const re = staticImportRegex();
+    for (let m = re.exec(content); m !== null; m = re.exec(content)) {
+        if (m[1] !== undefined)
+            edges.push({ specifier: m[1], index: m.index });
+    }
+    return edges;
+}
+/** Extract the static, non-type import specifiers from a module's source (the edges to follow/inspect).
+ * Mirrors {@link STATIC_IMPORT}, so `import type` + dynamic `import()` are already excluded. Pure. */
+export function parseStaticImports(content) {
+    return staticImportEdges(content).map((e) => e.specifier);
+}
+/** The server-only SINK an import specifier names directly (a `node:`/`bun:` builtin or a known
+ * server-only package), or `undefined` if it isn't a by-name sink. Pure — the label is the specifier
+ * itself (it's already the actionable name). */
+export function directSinkSpecifier(spec) {
+    return SERVER_ONLY_SINK.test(spec) ? spec : undefined;
+}
+/**
+ * BFS the LOCAL module graph from a route file for the SHORTEST import chain that reaches a server-only
+ * sink, returning `[routeFile, …as-written specifiers…, sink]` or `undefined` if none is reachable. A
+ * node's outgoing edges are its static imports; an edge is followed only when it's a RELATIVE specifier
+ * that `resolve` maps to a readable local file (so the walk never descends into node_modules or chases an
+ * unresolvable alias). At each node, a by-name sink import (`node:fs`, `postgres`) OR a resolved
+ * `*.server` / `server-only`-marked dependency terminates the chain. Bounded by depth + a visited set, so
+ * it's linear and cycle-free. `routeFile`/`routeContent` seed the walk; `resolve`/`read` supply the graph
+ * — pure given those, so it's unit-testable with a fake graph.
+ */
+export function walkServerOnlyChain(routeFile, routeContent, resolve, read) {
+    const seen = new Set([routeFile]);
+    let frontier = [{ abs: routeFile, content: routeContent, chain: [routeFile], depth: 0 }];
+    let visited = 0;
+    while (frontier.length > 0) {
+        const next = [];
+        for (const node of frontier) {
+            if (node.depth >= TRANSITIVE_MAX_DEPTH)
+                continue;
+            for (const spec of parseStaticImports(node.content)) {
+                // (a) A by-name sink (builtin / known server-only pkg) → the chain ends here (shortest first,
+                // since BFS reaches the nearest sink before any deeper one).
+                const sink = directSinkSpecifier(spec);
+                if (sink !== undefined)
+                    return [...node.chain, sink];
+                // (b) Only relative specifiers are local source we resolve + walk into. A bare third-party
+                // specifier that isn't a known sink is a leaf — don't follow it into node_modules.
+                if (!isRelativeSpecifier(spec))
+                    continue;
+                const abs = resolve(node.abs, spec);
+                if (abs === undefined || seen.has(abs))
+                    continue;
+                // (c) A resolved `*.server` module is a server-only sink by the `.server` convention — the chain
+                // ends at it (named by the as-written specifier).
+                if (SERVER_MODULE_FILE.test(abs))
+                    return [...node.chain, spec];
+                const content = read(abs);
+                if (content === undefined)
+                    continue; // unreadable → can't walk; treat as a leaf
+                // (d) A resolved module that opts into the `server-only` marker is a sink too.
+                if (SERVER_ONLY_MARKER_IMPORT.test(content))
+                    return [...node.chain, spec];
+                if (visited >= TRANSITIVE_MAX_VISITED)
+                    continue;
+                visited++;
+                seen.add(abs);
+                next.push({ abs, content, chain: [...node.chain, spec], depth: node.depth + 1 });
+            }
+        }
+        frontier = next;
+    }
+    return undefined;
+}
+/**
+ * Resolve the FULL transitive server-only chain(s) for a route module, given a real fs-backed resolver +
+ * reader. For each of the route's top-level imports, if a precise transitive walk finds a sink, the
+ * finding carries the full chain; otherwise — when the first hop is itself a direct by-name sink the
+ * regex scan already flags, or when a relative import can't be resolved — it falls back to the DIRECT
+ * edge (`fallback: true`), never a fabricated chain. Returns one finding per offending top-level import,
+ * de-duplicated to the shortest chain per first-hop specifier. Non-route files yield `[]`.
+ */
+export function resolveServerOnlyChains(file, content, resolve, read) {
+    if (!ROUTE_FILE.test(file))
+        return [];
+    const lines = content.split("\n");
+    const out = [];
+    const flaggedSpecifiers = new Set();
+    // Collect the route's import edges up front (fresh-regex scan) so the per-edge logic below can call
+    // the REENTRANT transitive walk without corrupting a shared regex's `lastIndex` (the walk also scans
+    // imports). Driving `STATIC_IMPORT.exec` here directly would restart this loop forever.
+    for (const { specifier, index } of staticImportEdges(content)) {
+        if (flaggedSpecifiers.has(specifier))
+            continue;
+        const line = lineAt(content, index);
+        const snippet = (lines[line - 1] ?? "").trim();
+        // (1) A direct by-name sink (`node:fs`, `postgres`) — the route imports it itself; chain is the
+        // direct edge. (Length-2 chain == the regex scan's existing `[route, specifier]`.)
+        if (directSinkSpecifier(specifier) !== undefined) {
+            flaggedSpecifiers.add(specifier);
+            out.push({ file, line, snippet, specifier, chain: [file, specifier], fallback: false });
+            continue;
+        }
+        // (2) A relative local import — try the transitive walk from the resolved dependency. If it reaches
+        // a sink, emit the full chain rooted at THIS route's import line.
+        if (isRelativeSpecifier(specifier)) {
+            const abs = resolve(file, specifier);
+            if (abs === undefined) {
+                // Unresolvable relative import. If it's the known server-only `../db` convention the regex scan
+                // flags directly, fall back to the direct edge (precise resolve impossible — say so via
+                // `fallback`). Any other unresolvable relative import we can't assert is server-only — skip it.
+                if (SERVER_ONLY.test(specifier)) {
+                    flaggedSpecifiers.add(specifier);
+                    out.push({ file, line, snippet, specifier, chain: [file, specifier], fallback: true });
+                }
+                continue;
+            }
+            // The `.server` / marker sink can be the first hop itself.
+            if (SERVER_MODULE_FILE.test(abs)) {
+                flaggedSpecifiers.add(specifier);
+                out.push({ file, line, snippet, specifier, chain: [file, specifier], fallback: false });
+                continue;
+            }
+            const depContent = read(abs);
+            if (depContent === undefined)
+                continue;
+            if (SERVER_ONLY_MARKER_IMPORT.test(depContent)) {
+                flaggedSpecifiers.add(specifier);
+                out.push({ file, line, snippet, specifier, chain: [file, specifier], fallback: false });
+                continue;
+            }
+            // Walk INTO the dependency: build the chain `[depAbs, …]` then re-root it at the route's import.
+            const subChain = walkServerOnlyChain(abs, depContent, resolve, read);
+            if (subChain !== undefined) {
+                flaggedSpecifiers.add(specifier);
+                // subChain is `[depAbs, …hops…, sink]`; replace its head (the resolved dep path) with the
+                // route's as-written specifier so the chain reads `routes/x → ../data → ../db → node:crypto`.
+                const chain = [file, specifier, ...subChain.slice(1)];
+                out.push({ file, line, snippet, specifier, chain, fallback: false });
+                continue;
+            }
+            // (3) The relative `../db`-style convention the regex scan flags directly, but where the walk
+            // found no deeper sink (e.g. the file wasn't readable past the first hop) — fall back to the
+            // direct edge so we still surface the known-server-only convention rather than going silent.
+            if (SERVER_ONLY.test(specifier)) {
+                flaggedSpecifiers.add(specifier);
+                out.push({ file, line, snippet, specifier, chain: [file, specifier], fallback: true });
+            }
+        }
     }
     return out;
 }
@@ -340,6 +528,59 @@ export async function scanProject(cwd) {
     await walkSource(cwd, (rel, content) => out.push(...scanFetchText(rel, content)));
     return out.sort(bySite);
 }
+// #7 — server-manifest drift. `server-manifest.ts` is a COMMITTED generated file (it bakes the route
+// list + client-entry hash for a disk-less worker). If `routes/` changes but the manifest isn't
+// regenerated, the worker serves a stale route table — a silent edge break that no other check catches.
+// We diff each committed manifest's imported route files against the live `routes/` tree.
+// The marker comment `generateServerManifest` emits at the top of the file — identifies a generated
+// manifest unambiguously (so a user file merely named `server-manifest.ts` isn't mistaken for one).
+const GENERATED_MARKER = "GENERATED by @nifrajs/web generateServerManifest";
+// The first route-import specifier's prefix up to `routes/` (e.g. `./`, `../`, `./src/`) — used to
+// locate the routes dir relative to the manifest, and to strip to route-relative keys.
+const ROUTES_PREFIX = /["'](\.{1,2}(?:\/[^"'/]+)*?\/routes\/)[^"']+["']/;
+// Route file extensions discovery recognises (mirrors `@nifrajs/web/fs`'s filter).
+const ROUTE_FILE_EXT = /\.(tsx|jsx|svelte|vue|mdx)$/;
+/**
+ * Scan the project for committed, generated `server-manifest.ts` files and report any that have drifted
+ * from the live `routes/` tree. For each, the routes dir is derived from the manifest's own import
+ * prefix (so a manifest that imports `../routes/x` is checked against the sibling `routes/`), its route
+ * imports are parsed (`parseManifestRouteFiles`), and the set is diffed against the actual route files
+ * on disk. A clean manifest yields no finding. Returns one finding per drifted manifest. Never throws on
+ * a per-manifest miss (an unreadable routes dir is simply skipped).
+ */
+export async function scanServerManifestDrift(cwd) {
+    const { parseManifestRouteFiles, diffManifestRoutes, isManifestInSync } = await import("@nifrajs/web/build");
+    const findings = [];
+    for await (const rel of new Glob("**/server-manifest.ts").scan({ cwd, dot: false })) {
+        if (IGNORED.test(rel))
+            continue;
+        const source = await Bun.file(join(cwd, rel)).text();
+        if (!source.includes(GENERATED_MARKER))
+            continue; // not a generated manifest — skip
+        const prefixMatch = ROUTES_PREFIX.exec(source);
+        if (prefixMatch?.[1] === undefined)
+            continue; // no `routes/` imports → nothing to diff (empty app)
+        const routesPrefix = prefixMatch[1];
+        const manifestFiles = parseManifestRouteFiles(source, routesPrefix);
+        // The routes dir sits at `<manifest dir>/<prefix>` — resolve it relative to the manifest file.
+        const manifestDir = rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : "";
+        const routesDir = join(cwd, manifestDir, routesPrefix);
+        let discovered;
+        try {
+            discovered = (await Array.fromAsync(new Glob("**/*.{tsx,jsx,svelte,vue,mdx}").scan({ cwd: routesDir })))
+                .map((f) => f.replaceAll("\\", "/"))
+                .filter((f) => ROUTE_FILE_EXT.test(f));
+        }
+        catch {
+            continue; // routes dir gone/unreadable — not a drift we can assess
+        }
+        const drift = diffManifestRoutes(manifestFiles, discovered);
+        if (!isManifestInSync(drift)) {
+            findings.push({ file: rel, missing: drift.missing, extra: drift.extra });
+        }
+    }
+    return findings.sort((a, b) => a.file.localeCompare(b.file));
+}
 /** Run the project's own `tsc --noEmit`, if TypeScript + a tsconfig are present. Never auto-installs. */
 async function typecheck(cwd, signal) {
     const tsconfig = join(cwd, "tsconfig.json");
@@ -392,6 +633,7 @@ const FETCH_HINT = "hand-rolled fetch() to your own API — call it through clie
 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 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";
 function oneLineDiff(file, line, before, after) {
     return `--- ${file}:${line}\n+++ ${file}:${line}\n@@\n-${before}\n+${after}`;
 }
@@ -481,14 +723,23 @@ function ownFetchSuggestion(f, routes) {
         ],
     };
 }
-function serverImportSuggestion() {
+function serverImportSuggestion(specifier, chain, fallback) {
+    const sink = chain[chain.length - 1] ?? specifier;
+    // Surface the resolved chain in the fix steps so the agent sees the full path (`route → ../data →
+    // ../db → node:crypto`) and which module to cut — not just the route's own top-level import.
+    const chainStep = chain.length > 2
+        ? fallback
+            ? `Server-only code reaches this route through \`${chain.join(" → ")}\` (the deeper chain couldn't be resolved precisely — trace it from \`${specifier}\`).`
+            : `Server-only code reaches this route transitively: \`${chain.join(" → ")}\`. The sink is \`${sink}\`; break the chain at the first hop (\`${specifier}\`) or move the sink behind the server boundary.`
+        : undefined;
     return {
         kind: "manual",
         title: "Move server-only code behind the route server boundary",
         steps: [
-            "Remove the top-level server-only import from the route module.",
+            ...(chainStep !== undefined ? [chainStep] : []),
+            `Remove the top-level \`import … from "${specifier}"\` from this route module (it's bundled for the browser).`,
             "Access backend/data work through the route `loader`/`action` context (`api`, `env`, or project server context).",
-            "If a direct module import is unavoidable, lazy-load it inside the server-only loader/action path.",
+            `If a direct module import is unavoidable, lazy-load it (\`await import("${specifier}")\`) inside the server-only loader/action path.`,
         ],
     };
 }
@@ -510,9 +761,12 @@ export async function collectCheckResult(cwd, opts = {}) {
     const untypedClients = [];
     const serverImports = [];
     const responseRoutes = [];
+    // 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 = [];
     // 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] = await Promise.all([
+    const [tc, _, dr, manifestDrift] = await Promise.all([
         opts.lintsOnly
             ? Promise.resolve({ ran: false, ok: true, note: "skipped (lintsOnly)" })
             : typecheck(cwd, opts.signal),
@@ -520,11 +774,40 @@ export async function collectCheckResult(cwd, opts = {}) {
             fetches.push(...scanFetchText(rel, content));
             staticRoutes.push(...scanStaticRouteText(rel, content));
             untypedClients.push(...scanUntypedClient(rel, content));
-            serverImports.push(...scanServerOnlyImports(rel, content));
+            if (ROUTE_FILE.test(rel))
+                routeModules.push({ rel, content });
             responseRoutes.push(...scanResponseRoutes(rel, content));
         }),
         import("./doctor.js").then((m) => m.collectDoctorResult(cwd)),
+        scanServerManifestDrift(cwd),
     ]);
+    // #4.4: resolve the FULL transitive server-only chain per route. The resolver/reader are fs-backed
+    // (`Bun.resolveSync` from the importing file's dir + a sync read), so the walk follows the real local
+    // module graph (`route → ../data → ../db → node:crypto`). Both are best-effort + total: a resolve/read
+    // miss returns `undefined`, and the walk falls back to the direct edge. The whole walk is bounded
+    // (depth + visited caps), so a deep/cyclic graph can't blow up the check.
+    const resolveModule = (fromFile, specifier) => {
+        try {
+            // `fromFile` is a cwd-RELATIVE route path on the first hop (`routes/x.tsx`) but ABSOLUTE on the
+            // deeper hops the walk takes (it carries resolved absolute paths) — resolve the dir for each.
+            const fromAbs = isAbsolute(fromFile) ? fromFile : join(cwd, fromFile);
+            return Bun.resolveSync(specifier, dirname(fromAbs));
+        }
+        catch {
+            return undefined; // unresolvable (bare pkg without install, tsconfig path alias, missing file)
+        }
+    };
+    const readModule = (absPath) => {
+        try {
+            return readFileSync(absPath, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+    };
+    for (const { rel, content } of routeModules) {
+        serverImports.push(...resolveServerOnlyChains(rel, content, resolveModule, readModule));
+    }
     const diagnostics = [];
     if (tc.ran && !tc.ok) {
         const lines = (tc.output ?? "").split("\n");
@@ -587,14 +870,21 @@ export async function collectCheckResult(cwd, opts = {}) {
         });
     }
     for (const f of serverImports.sort(bySite)) {
+        // #4.4: the FULL transitive chain the import-resolution walk found — `route → ../data → ../db →
+        // node:crypto`, matching the build leak-guard's depth — instead of just the direct edge. The chain's
+        // tail is the actual server-only sink; the head is the route. When a precise resolve wasn't possible
+        // (a bare pkg / path alias), `fallback` is set and the chain degrades to the honest direct edge.
+        const chain = f.chain;
+        const sink = chain[chain.length - 1] ?? f.specifier;
         diagnostics.push({
             rule: "server-only-import",
             severity: "error",
             file: f.file,
             line: f.line,
-            message: `${f.snippet} — ${SERVER_IMPORT_HINT}`,
+            message: `${f.snippet} — server-only "${sink}" reaches the browser bundle via ${chain.join(" → ")}${f.fallback ? " (direct edge — couldn't resolve the transitive chain precisely)" : ""}; ${SERVER_IMPORT_HINT}`,
             fix: SERVER_IMPORT_HINT,
-            suggestion: serverImportSuggestion(),
+            chain,
+            suggestion: serverImportSuggestion(f.specifier, chain, f.fallback),
         });
     }
     // Advisory — surfaced but NOT folded into `ok`, so it never fails the gate (a raw Response is valid).
@@ -626,11 +916,35 @@ export async function collectCheckResult(cwd, opts = {}) {
             });
         }
     }
+    // #7: a committed server-manifest.ts that drifted from routes/ — name the exact missing/extra routes.
+    for (const f of manifestDrift) {
+        const parts = [];
+        if (f.missing.length > 0)
+            parts.push(`missing from manifest: ${f.missing.join(", ")}`);
+        if (f.extra.length > 0)
+            parts.push(`stale in manifest: ${f.extra.join(", ")}`);
+        diagnostics.push({
+            rule: "server-manifest-drift",
+            severity: "error",
+            file: f.file,
+            message: `${f.file} drifted from routes/ (${parts.join("; ")}) — ${MANIFEST_DRIFT_HINT}`,
+            fix: MANIFEST_DRIFT_HINT,
+            suggestion: {
+                kind: "manual",
+                title: "Regenerate the committed server manifest",
+                steps: [
+                    "Re-run your build (`nifra build --target <t>` or your build script) — it regenerates server-manifest.ts from the current routes/.",
+                    "Commit the updated server-manifest.ts.",
+                ],
+            },
+        });
+    }
     return {
         ok: tc.ok &&
             fetches.length === 0 &&
             untypedClients.length === 0 &&
             serverImports.length === 0 &&
+            manifestDrift.length === 0 &&
             (!dr.ran || dr.findings.length === 0),
         typecheck: tc.ran ? (tc.ok ? "pass" : "fail") : "skipped",
         diagnostics,
@@ -657,6 +971,7 @@ export async function runCheck(cwd, opts = {}) {
         ["server-only-import", "server-only import in a route module"],
         ["response-route", "route returns a raw Response (typed client → data: never)"],
         ["undeclared-dependency", "undeclared dependency in package.json"],
+        ["server-manifest-drift", "server-manifest.ts drifted from routes/"],
     ]) {
         const ds = counts(rule);
         if (rule === "response-route") {