@nifrajs/cli 1.12.0 → 2.0.0

package/src/cli.ts

@@ -4,8 +4,8 @@
  * the project root (see {@link loadApp}) and wires the right `@nifrajs/web` entrypoint:
  *
  *   nifra dev      true-HMR dev server (Vite middleware + nifra SSR)        — @nifrajs/web/vite
- *   nifra build    bundle the client (content-hashed) + write manifest.json — @nifrajs/web/build
- *   nifra start    serve the built client + SSR on Bun.serve              — @nifrajs/web
+ *   nifra build    emit a complete target-specific deploy directory        — @nifrajs/web/build
+ *   nifra start    run the default Bun build                               — dist/server.js
  *
  * Bun-only (it runs the framework's TS + Bun plugins directly). The *output* runs anywhere.
  */
@@ -22,9 +22,8 @@ export interface Flags {
   readonly port: number
   readonly out: string
   readonly poll: boolean
-  /** `nifra build --target <t>`: emit a full deploy dir for a target (bun/node/deno/cf-pages/vercel/
-   * static) instead of just the client bundle. Undefined ⇒ the legacy client-only build. */
-  readonly target?: string
+  /** `nifra build --target <t>`: emit a full deploy dir for this target. Defaults to `bun`. */
+  readonly target: string
   /** `nifra build --report`: print a per-chunk size + gzip table after the build. */
   readonly report: boolean
 }
@@ -33,15 +32,15 @@ const HELP = `nifra — zero-config dev/build/start for a nifra app
 
 Usage:
   nifra dev     [--port <n>] [--poll]    Start the true-HMR dev server (Vite). Default port ${DEFAULT_DEV_PORT}.
-  nifra build   [--out <dir>]            Bundle the client + write manifest.json.
-                [--target <t>] [--report]  With --target, emit a FULL deploy dir for <t>:
+  nifra build   [--out <dir>] [--report]  Emit a complete Bun deploy directory by default.
+                [--target <t>]             Target a FULL deploy dir for <t>:
                                          bun | node | deno | cf-pages | vercel | static. Packages
                                          buildClient + buildServer (+ prerender for static) so an app
                                          no longer hand-writes build-<target>.ts + _worker.ts +
                                          _routes.json. The server entry is generated from your
                                          framework.ts (adapter) + backend.ts + routes/. --report prints
                                          a per-chunk size + gzip table (biggest first).
-  nifra start   [--port <n>] [--out <dir>]  Serve the built app (client + SSR) on Bun. Default port ${DEFAULT_DEV_PORT}.
+  nifra start   [--port <n>] [--out <dir>]  Run the Bun build at <out>/server.js. Default port ${DEFAULT_DEV_PORT}.
   nifra context                          Print this project's route INDEX (API + page routes) + conventions
                                          for an AI agent's prompt. Per-route schemas: nifra mcp's
                                          nifra_context (path/kind slice) or nifra routes --json.
@@ -59,12 +58,16 @@ Usage:
                                          agent: nifra_context, nifra_routes (routes+schemas as JSON),
                                          nifra_run (backend), nifra_render (SSR a page), nifra_docs,
                                          nifra_example (verified snippets), nifra_scaffold (route→file),
-                                         nifra_check (drift gate + fixes), nifra_doctor (deps + duplicate installs).
+                                         nifra_check (drift gate + fixes), nifra_levels (verification
+                                         ladder), nifra_doctor (deps + duplicate installs).
   nifra docs-mcp [--port <n>]            Serve the PUBLIC docs MCP over HTTP (nifra_docs + nifra_example) —
                                          self-host on a VPS so any remote agent can learn nifra. Default :8787.
   nifra check   [--json] [--lints-only]  Gate: typecheck + lints (hand-rolled fetch(), untyped client("…"),
                                          server-only imports in routes/). Run as "done"; --json for agents;
                                          --lints-only skips tsc for a near-instant inner-loop pass.
+  nifra sync-manifest                    Regenerate a committed web server-manifest.ts from routes/ WITHOUT
+                                         a full build - clears server-manifest drift after a route add/rename
+                                         (a new hydrating component still needs a full build).
   nifra snapshot [--out <file>]          Write the backend's API contract (routes + schemas) as plain
                                          JSON — the baseline for \`nifra diff\`. Default api-snapshot.json.
   nifra diff    [<baseline>] [--json]    Breaking-change gate: re-snapshot the contract and compare
@@ -95,8 +98,8 @@ Usage:
                                          @nifrajs/core/React identity-sensitive dependencies;
                                          --auto-fix writes safe local-version dependency fixes.
   nifra upgrade <version>                Run the per-release upgrade recipe for <version>: sweep every
-                [--write] [--no-verify]  matching dependency pin (preserving ^/~/exact) + apply exact
-                [--list] [--json]        import moves across the workspace, then verify with nifra check.
+                [--write] [--no-verify]  matching dependency pin (preserving ^/~/exact), move removed
+                [--list] [--json]        packages, apply exact imports, then verify with nifra check.
                                          Dry-run by default; --write applies then verifies (--no-verify
                                          to skip). --list shows available targets. Fail-closed on an
                                          unknown version. Deterministic + idempotent.
@@ -114,7 +117,7 @@ Port: \`dev\` and \`start\` share the default ${DEFAULT_DEV_PORT}. Override with
 \`PORT\` env var (\`--port\` wins over \`PORT\`, which wins over the default).`
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const CLI_VERSION = "1.12.0"
+const CLI_VERSION = "2.0.0"
 
 // A render adapter + nifra server are opaque to the CLI (it just forwards them); cast at the seam.
 const asAdapter = (v: unknown): RenderAdapter => v as RenderAdapter
@@ -123,6 +126,17 @@ const apiOf = (backend: unknown): { api?: unknown } =>
   backend === undefined ? {} : { api: inProcessClient(backend as never) }
 
 async function dev(app: LoadedApp, flags: Flags): Promise<void> {
+  // Preflight: `nifra dev` needs `vite` resolvable from the project. Run via `bunx @nifrajs/cli dev` the CLI
+  // sits in an isolated install where the project's peer deps don't resolve, so the vite import below fails
+  // with an opaque ERR_MODULE_NOT_FOUND. Surface the real fix instead.
+  try {
+    Bun.resolveSync("vite", app.cwd)
+  } catch {
+    throw new Error(
+      "[nifra] `nifra dev` needs `vite` installed in this project. Run it via your workspace-local " +
+        "script (`bun run dev`), not `bunx @nifrajs/cli dev` (which can't resolve the project's peers).",
+    )
+  }
   const { plugin } = await import("bun")
   const { createViteDevServer } = await import("@nifrajs/web/vite")
   const { framework: fw, routesDir, cwd, backend } = app
@@ -150,20 +164,6 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
   console.log(`nifra dev → http://localhost:${server.port}`)
 }
 
-async function build(app: LoadedApp): Promise<void> {
-  const { buildClient } = await import("@nifrajs/web/build")
-  const { framework: fw, routesDir, outDir } = app
-  const manifest = await buildClient({
-    routesDir,
-    outDir,
-    clientModule: fw.clientModule,
-    plugins: asBunPlugins(await resolvePlugins(fw.clientPlugins)),
-    define: { "process.env.NODE_ENV": '"production"', ...(fw.define ?? {}) },
-    ...(fw.conditions ? { conditions: fw.conditions } : {}),
-  })
-  console.log(`nifra build → ${outDir} (entry ${manifest.entry}${manifest.css ? ", + css" : ""})`)
-}
-
 /**
  * `nifra build --target <t>` — package the engine (buildClient + buildServer + prerender) into one
  * command that emits a full deploy dir, so an app no longer hand-writes build-bun.ts + _worker.ts +
@@ -206,12 +206,12 @@ async function buildForTarget(app: LoadedApp, target: string, report: boolean):
   if (report) console.log(`\n${renderSizeReport(result.size)}`)
 }
 
-/** Build the app FACTORY for the `static` target's prerender pass. Mirrors `nifra start`: register the
+/** Build the app FACTORY for the `static` target's prerender pass. Registers the
  * framework's SSR Bun plugins (so `.vue`/`.svelte`/Solid routes import) once, then return a factory that
  * `createWebApp`s the app for the client build's manifest. The client entry MUST be the real content-hashed
  * bundle (`client.entry`) — it's the hydration `<script src>` the prerendered HTML emits, so a placeholder
  * would 404 and the pages would render but never hydrate (inert controls). Styles/route-preload are wired
- * from the same manifest so the static HTML matches what `nifra start` serves. */
+ * from the same manifest so the static HTML matches the deployed app. */
 async function buildPrerenderApp(
   app: LoadedApp,
 ): Promise<(client: BuiltManifest) => { fetch(req: Request): Response | Promise<Response> }> {
@@ -238,43 +238,23 @@ interface BuiltManifest {
 }
 
 async function start(app: LoadedApp, flags: Flags): Promise<void> {
-  const { plugin } = await import("bun")
-  const { framework: fw, routesDir, outDir, backend } = app
-  // Register the framework's SSR Bun plugins so `.vue`/`.svelte`/Solid route files compile on the
-  // server's runtime import (React/Preact JSX is Bun-native → none).
-  for (const p of asBunPlugins(await resolvePlugins(fw.serverPlugins))) plugin(p)
-
-  const manifestFile = Bun.file(`${outDir}/manifest.json`)
-  if (!(await manifestFile.exists())) {
-    throw new Error(`[nifra] no ${outDir}/manifest.json — run \`nifra build\` first.`)
+  const serverFile = resolve(app.outDir, "server.js")
+  if (!existsSync(serverFile)) {
+    // A Cloudflare Pages build emits `_worker.js` (a Workers bundle), not a self-hosting `server.js` - so
+    // `nifra start` on a dir built for cf-pages would otherwise fail with a bare "no server.js". Name the
+    // actual mismatch and the fix.
+    if (existsSync(resolve(app.outDir, "_worker.js"))) {
+      throw new Error(
+        `[nifra] ${app.outDir} holds a Cloudflare Pages worker bundle (_worker.js), not a self-hosting ` +
+          "server. Run `nifra build --target bun` then `nifra start`, or serve this dir with `wrangler pages`.",
+      )
+    }
+    throw new Error(
+      `[nifra] no ${serverFile} — run \`nifra build\` or \`nifra build --target bun\` first.`,
+    )
   }
-  const manifest = JSON.parse(await manifestFile.text()) as BuiltManifest
-
-  const server = createWebApp({
-    adapter: asAdapter(fw.adapter),
-    manifest: discoverRoutes(routesDir),
-    clientEntry: manifest.entry,
-    ...(manifest.routes ? { routePreload: manifest.routes } : {}),
-    ...(manifest.css ? { styles: manifest.css } : {}),
-    ...(manifest.routeStyles ? { routeStyles: manifest.routeStyles } : {}),
-    ...apiOf(backend),
-  })
-  // Serve the content-hashed bundle (immutable). `.css` → text/css, else JS. Name is path-validated.
-  server.get("/assets/*", async (c) => {
-    const name = new URL(c.req.url).pathname.slice("/assets/".length)
-    if (!/^[A-Za-z0-9._-]+$/.test(name)) return new Response("bad request", { status: 400 })
-    const file = Bun.file(`${outDir}/${name}`)
-    if (!(await file.exists())) return new Response("Not Found", { status: 404 })
-    const type = name.endsWith(".css") ? "text/css" : "text/javascript"
-    return new Response(file, {
-      headers: {
-        "content-type": `${type}; charset=utf-8`,
-        "cache-control": "public, max-age=31536000, immutable",
-      },
-    })
-  })
-  const running = server.listen(flags.port)
-  console.log(`nifra start → http://localhost:${running.port}`)
+  Bun.env.PORT = String(flags.port)
+  await import(serverFile)
 }
 
 export function parseFlags(args: readonly string[]): Flags {
@@ -284,20 +264,20 @@ export function parseFlags(args: readonly string[]): Flags {
   let port = Number(Bun.env.PORT ?? DEFAULT_DEV_PORT)
   let out = "dist"
   let poll = Bun.env.CHOKIDAR_USEPOLLING === "1"
-  let target: string | undefined
+  let target = "bun"
   let report = false
   for (let i = 0; i < args.length; i++) {
     const a = args[i]
     if ((a === "--port" || a === "-p") && args[i + 1]) port = Number(args[++i])
     else if (a === "--out" && args[i + 1]) out = args[++i] as string
     else if (a === "--poll") poll = true
-    else if (a === "--target" && args[i + 1]) target = args[++i]
+    else if (a === "--target" && args[i + 1]) target = args[++i] as string
     else if (a === "--report") report = true
   }
   if (!Number.isFinite(port) || port < 0 || port > 65535) {
     throw new Error(`[nifra] invalid --port: ${port}`)
   }
-  return { port, out, poll, report, ...(target !== undefined ? { target } : {}) }
+  return { port, out, poll, target, report }
 }
 
 async function main(): Promise<void> {
@@ -355,6 +335,14 @@ async function main(): Promise<void> {
     })
     return
   }
+  // `sync-manifest` rewrites a committed web `server-manifest.ts` from the current `routes/` tree, without
+  // a full build. Pure fs/text (re-scan routes, preserve baked client assets), so - like `check` - dispatch
+  // it before the eager `loadApp`.
+  if (command === "sync-manifest") {
+    const { runSyncManifest } = await import("./sync-manifest.ts")
+    if (!(await runSyncManifest(process.cwd()))) process.exitCode = 1
+    return
+  }
   // `doctor` is a pure cwd check (imports vs declared deps) — like `check`, dispatch before `loadApp`
   // so it runs on an API-only / not-yet-built project.
   if (command === "doctor") {
@@ -600,12 +588,8 @@ async function main(): Promise<void> {
   const flags = parseFlags(argv.slice(1))
   const app = await loadApp(process.cwd(), flags.out)
   if (command === "dev") await dev(app, flags)
-  else if (command === "build") {
-    // `--target` (or `--report`) → the full per-target deploy build; otherwise the legacy client build.
-    if (flags.target !== undefined || flags.report) {
-      await buildForTarget(app, flags.target ?? "cf-pages", flags.report)
-    } else await build(app)
-  } else if (command === "context") console.log(describeProject(app))
+  else if (command === "build") await buildForTarget(app, flags.target, flags.report)
+  else if (command === "context") console.log(describeProject(app))
   else if (command === "routes") {
     console.log(await describeRoutes(app, { json: argv.includes("--json") }))
   } else await start(app, flags)

package/src/doctor.ts

@@ -13,7 +13,7 @@
 import { realpath } from "node:fs/promises"
 import { builtinModules } from "node:module"
 import { dirname, join, relative } from "node:path"
-import { type SourceFinding, stripComments, walkSource } from "./check.ts"
+import { codePositionMask, type SourceFinding, stripComments, walkSource } from "./check.ts"
 
 // Runtime-provided modules that are never an npm dependency: Node core (bare + `node:` form) and Bun's
 // own `bun` module. `node:`/`bun:`-prefixed specifiers are filtered in packageOf by prefix.
@@ -89,9 +89,13 @@ export function scanUndeclaredImports(
   const out: SourceFinding[] = []
   const seen = new Set<string>()
   const code = stripComments(content) // so doc-comment usage examples aren't read as real imports
+  const positions = codePositionMask(content)
   for (const rx of IMPORT_PATTERNS) {
     rx.lastIndex = 0
     for (let m = rx.exec(code); m !== null; m = rx.exec(code)) {
+      // The specifier regex must run over quoted literals, but its import/require token must begin in
+      // executable code. Otherwise documentation and code-generator strings look like real imports.
+      if (positions[m.index] === " ") continue
       const spec = m[1] ?? ""
       if (isAlias(spec)) continue
       const pkg = packageOf(spec)
@@ -191,11 +195,13 @@ function workspacePatterns(pkg: Record<string, unknown>): string[] {
     .sort()
 }
 
-/** Discover package roots declared by npm/Bun's two workspace manifest shapes. Bounded so a hostile
- * `**` pattern cannot turn a diagnostic into an unbounded filesystem crawl. */
+/** Discover package roots declared by npm/Bun's workspace manifest shapes plus nested package
+ * boundaries (scaffold templates and benchmark fixtures are commonly real standalone packages even
+ * when they are not workspace members). Bounded so a hostile tree cannot make doctor unbounded. */
 async function workspaceImporters(
   cwd: string,
   rootPackage: Record<string, unknown>,
+  includeNestedPackages = false,
 ): Promise<Array<{ root: string; package: Record<string, unknown> }>> {
   const manifests = new Set<string>([join(cwd, "package.json")])
   for (const pattern of workspacePatterns(rootPackage)) {
@@ -208,6 +214,22 @@ async function workspaceImporters(
       if (manifests.size > MAX_WORKSPACE_IMPORTERS) return []
     }
   }
+  if (includeNestedPackages) {
+    for await (const rel of new Bun.Glob("**/package.json").scan({ cwd, dot: false })) {
+      const segments = rel.split(/[\\/]/)
+      if (
+        segments.some((segment) =>
+          ["node_modules", "dist", "build", ".git", ".nifra", ".next", "coverage"].includes(
+            segment,
+          ),
+        )
+      ) {
+        continue
+      }
+      manifests.add(join(cwd, rel))
+      if (manifests.size > MAX_WORKSPACE_IMPORTERS) return []
+    }
+  }
 
   const out: Array<{ root: string; package: Record<string, unknown> }> = []
   for (const manifest of [...manifests].sort()) {
@@ -217,6 +239,62 @@ async function workspaceImporters(
   return out
 }
 
+interface DoctorPackageScope {
+  readonly root: string
+  readonly relativeRoot: string
+  readonly declared: ReadonlySet<string>
+  readonly isAlias: (specifier: string) => boolean
+}
+
+const declaredPackages = (pkg: Record<string, unknown>): ReadonlySet<string> => {
+  const declared = new Set<string>()
+  if (typeof pkg.name === "string") declared.add(pkg.name)
+  for (const field of DEPENDENCY_FIELDS) {
+    for (const name of depNames(pkg, field)) declared.add(name)
+  }
+  return declared
+}
+
+const tsconfigPaths = async (
+  root: string,
+): Promise<Readonly<Record<string, unknown>> | undefined> => {
+  const tsconfig = await readJson(join(root, "tsconfig.json"))
+  const compilerOptions = tsconfig?.compilerOptions as
+    | { paths?: Record<string, unknown> }
+    | undefined
+  return compilerOptions?.paths
+}
+
+/** Build per-package declaration scopes for a workspace. Longest roots are first so nested packages
+ * own their source; files outside a workspace package remain owned by the root manifest. */
+async function doctorPackageScopes(
+  cwd: string,
+  rootPackage: Record<string, unknown>,
+): Promise<readonly DoctorPackageScope[]> {
+  const importers = await workspaceImporters(cwd, rootPackage, true)
+  const packages = importers.length > 0 ? importers : [{ root: cwd, package: rootPackage }]
+  const rootPaths = await tsconfigPaths(cwd)
+  const scopes = await Promise.all(
+    packages.map(async (entry): Promise<DoctorPackageScope> => {
+      const paths = (await tsconfigPaths(entry.root)) ?? rootPaths
+      return {
+        root: entry.root,
+        relativeRoot: relative(cwd, entry.root).split("\\").join("/"),
+        declared: declaredPackages(entry.package),
+        isAlias: aliasMatcher(paths),
+      }
+    }),
+  )
+  return scopes.sort((a, b) => b.relativeRoot.length - a.relativeRoot.length)
+}
+
+const scopeForFile = (scopes: readonly DoctorPackageScope[], file: string): DoctorPackageScope =>
+  scopes.find(
+    (scope) =>
+      scope.relativeRoot !== "" &&
+      (file === scope.relativeRoot || file.startsWith(`${scope.relativeRoot}/`)),
+  ) ?? (scopes.find((scope) => scope.relativeRoot === "") as DoctorPackageScope)
+
 function duplicateTargets(pkg: Record<string, unknown>): string[] {
   const targets = new Set<string>()
   for (const field of DEPENDENCY_FIELDS) {
@@ -266,25 +344,40 @@ export async function collectDuplicateInstalls(
 ): Promise<DuplicateInstallFinding[]> {
   const importers = await workspaceImporters(cwd, rootPackage)
   const byPackage = new Map<string, Map<string, { version: string; importers: Set<string> }>>()
+  const record = (
+    name: string,
+    copy: { path: string; version: string },
+    importer: string,
+  ): void => {
+    let copies = byPackage.get(name)
+    if (copies === undefined) {
+      copies = new Map()
+      byPackage.set(name, copies)
+    }
+    const entry = copies.get(copy.path) ?? { version: copy.version, importers: new Set<string>() }
+    entry.importers.add(importer)
+    copies.set(copy.path, entry)
+  }
+
+  const targets = new Set<string>()
   for (const importer of importers) {
     for (const name of duplicateTargets(importer.package)) {
       if (importer.package.name === name) continue
+      targets.add(name)
       const copy = await resolvedInstalledCopy(importer.root, cwd, name)
-      if (copy === undefined) continue
-      let copies = byPackage.get(name)
-      if (copies === undefined) {
-        copies = new Map()
-        byPackage.set(name, copies)
-      }
-      const record = copies.get(copy.path) ?? {
-        version: copy.version,
-        importers: new Set<string>(),
-      }
-      record.importers.add(displayPath(cwd, importer.root))
-      copies.set(copy.path, record)
+      if (copy !== undefined) record(name, copy, displayPath(cwd, importer.root))
     }
   }
 
+  // Probe the workspace root for every target too, even when the root manifest doesn't declare it.
+  // A hoisted root copy is reachable from any package that lacks its own nested one, so leaving it
+  // out hides the very split it should catch: every declaring package nested onto one copy while the
+  // root resolved a different one, which reads as a single copy when only declarers are consulted.
+  for (const name of targets) {
+    const copy = await resolvedInstalledCopy(cwd, cwd, name)
+    if (copy !== undefined) record(name, copy, ".")
+  }
+
   const findings: DuplicateInstallFinding[] = []
   for (const [name, copies] of [...byPackage.entries()].sort(([a], [b]) => a.localeCompare(b))) {
     if (copies.size < 2) continue
@@ -362,21 +455,12 @@ export async function collectDoctorResult(cwd: string): Promise<DoctorResult> {
   const pkg = await readJson(join(cwd, "package.json"))
   if (pkg === undefined) return { ok: true, ran: false, findings: [], duplicateInstalls: [] }
 
-  const declared = new Set<string>()
-  if (typeof pkg.name === "string") declared.add(pkg.name) // a package may import its own name (exports map)
-  for (const field of DEPENDENCY_FIELDS) {
-    for (const name of depNames(pkg, field)) declared.add(name)
-  }
-
-  const tsconfig = await readJson(join(cwd, "tsconfig.json"))
-  const compilerOptions = tsconfig?.compilerOptions as
-    | { paths?: Record<string, unknown> }
-    | undefined
-  const isAlias = aliasMatcher(compilerOptions?.paths)
+  const scopes = await doctorPackageScopes(cwd, pkg)
 
   const findings: DoctorFinding[] = []
   await walkSource(cwd, (rel, content) => {
-    for (const f of scanUndeclaredImports(rel, content, declared, isAlias)) {
+    const scope = scopeForFile(scopes, rel)
+    for (const f of scanUndeclaredImports(rel, content, scope.declared, scope.isAlias)) {
       findings.push({ file: f.file, line: f.line, package: f.snippet })
     }
   })
@@ -395,49 +479,64 @@ export async function applyDoctorAutoFix(cwd: string): Promise<DoctorResult> {
   const before = await collectDoctorResult(cwd)
   if (!before.ran || before.findings.length === 0) return before
 
-  const pkgPath = join(cwd, "package.json")
-  const pkg = await readJson(pkgPath)
-  if (pkg === undefined) return before
-  const dependencies = pkg.dependencies
-  if (dependencies !== undefined && !isRecord(dependencies)) {
-    const skippedFixes = [...new Set(before.findings.map((f) => f.package))].sort().map(
-      (name): DoctorSkippedFix => ({
-        package: name,
-        reason: "`dependencies` exists but is not an object; refusing to rewrite it automatically",
-        command: ["bun", "add", name],
-      }),
-    )
-    return { ...before, skippedFixes }
+  const rootPackage = await readJson(join(cwd, "package.json"))
+  if (rootPackage === undefined) return before
+  const scopes = await doctorPackageScopes(cwd, rootPackage)
+  const byRoot = new Map<string, Set<string>>()
+  for (const finding of before.findings) {
+    const root = scopeForFile(scopes, finding.file).root
+    const names = byRoot.get(root) ?? new Set<string>()
+    names.add(finding.package)
+    byRoot.set(root, names)
   }
 
-  const deps = (dependencies ?? {}) as Record<string, unknown>
-  if (dependencies === undefined) pkg.dependencies = deps
-
   const fixed: DoctorAppliedFix[] = []
   const skippedFixes: DoctorSkippedFix[] = []
-  for (const name of [...new Set(before.findings.map((f) => f.package))].sort()) {
-    if (!isNpmPackageName(name)) {
-      skippedFixes.push({
-        package: name,
-        reason: "package name did not match npm package-name syntax",
-        command: ["bun", "add", name],
-      })
+  for (const [root, names] of [...byRoot.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    const pkgPath = join(root, "package.json")
+    const pkg = await readJson(pkgPath)
+    if (pkg === undefined) continue
+    const dependencies = pkg.dependencies
+    if (dependencies !== undefined && !isRecord(dependencies)) {
+      for (const name of [...names].sort()) {
+        skippedFixes.push({
+          package: name,
+          reason:
+            "`dependencies` exists but is not an object; refusing to rewrite it automatically",
+          command: ["bun", "add", name],
+        })
+      }
       continue
     }
-    const inferred = await inferDependencyFix(cwd, name)
-    if (inferred === undefined) {
-      skippedFixes.push({
-        package: name,
-        reason: "no declared ancestor version or installed package metadata was found locally",
-        command: ["bun", "add", name],
-      })
-      continue
+
+    const deps = (dependencies ?? {}) as Record<string, unknown>
+    if (dependencies === undefined) pkg.dependencies = deps
+    let changed = false
+    for (const name of [...names].sort()) {
+      if (!isNpmPackageName(name)) {
+        skippedFixes.push({
+          package: name,
+          reason: "package name did not match npm package-name syntax",
+          command: ["bun", "add", name],
+        })
+        continue
+      }
+      const inferred = await inferDependencyFix(root, name)
+      if (inferred === undefined) {
+        skippedFixes.push({
+          package: name,
+          reason: "no declared ancestor version or installed package metadata was found locally",
+          command: ["bun", "add", name],
+        })
+        continue
+      }
+      deps[name] = inferred.version
+      changed = true
+      fixed.push({ package: name, field: "dependencies", ...inferred })
     }
-    deps[name] = inferred.version
-    fixed.push({ package: name, field: "dependencies", ...inferred })
+    if (changed) await Bun.write(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`)
   }
 
-  if (fixed.length > 0) await Bun.write(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`)
   const after = fixed.length > 0 ? await collectDoctorResult(cwd) : before
   return {
     ...after,

package/src/mcp-http.ts

@@ -26,7 +26,7 @@ export { docsTools } from "./mcp-docs-tools.ts"
 export type { TypeEntry } from "./types-search.ts"
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const VERSION = "1.12.0"
+const VERSION = "2.0.0"
 const SERVER_INFO = { name: "nifra-docs", version: VERSION }
 const DOCS_HEALTH =
   "nifra docs MCP — POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call). Tools: nifra_docs, nifra_example."

package/src/mcp.ts

@@ -15,6 +15,8 @@
  *   - `nifra_scaffold`— map a URL path to the correct `routes/` file + a contract-correct page stub.
  *   - `nifra_check`   — the drift gate (typecheck + lints, each with a structured fix), for an agent to fix against.
  *   - `nifra_assure`  — route classification + enforcement-evidence gate.
+ *   - `nifra_levels`  - the cumulative verification ladder (L0 contract → L4 invariants): what the
+ *     project actually proves, and why each level it misses does not hold.
  *   - `nifra_doctor`  — package.json dependency drift detector, with safe local-version auto-fix.
  *
  * Wire it into a client (e.g. Claude Desktop / Cursor) as: command `nifra`, args `["mcp"]`, run in the
@@ -988,6 +990,56 @@ export function projectTools(
         return JSON.stringify(await collectAssuranceReport(target, config), null, 2)
       },
     },
+    {
+      name: "nifra_levels",
+      description:
+        "Compute this project's verification ladder and return { achieved, levels[] }, where each level carries { level, name, ok, reasons[] }. The ladder is cumulative: L0 typed contract (nifra check), L1 route assurance, L2 reviewed capability lockfile, L3 route trust manifest in sync, L4 contract invariants, so a level only holds when every level below it holds, and `achieved` is -1 when even L0 fails. This is the single gate that reports what a change actually proves: run it after finishing work, and treat any `reasons` on a level the project already claimed as a regression to fix.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          config: {
+            type: "string",
+            description:
+              "Assurance config path relative to the selected project directory. Default: nifra.assurance.ts.",
+          },
+          seed: {
+            type: "number",
+            description: "Deterministic seed for the L4 invariant run. Default 1.",
+          },
+          dir: {
+            type: "string",
+            description:
+              'Evaluate this project subdirectory (relative to the MCP root), e.g. "apps/api". Default: the project root.',
+          },
+        },
+        additionalProperties: false,
+      },
+      handler: async (args) => {
+        const opts = args as { config?: string; seed?: number; dir?: string }
+        const target = resolveProjectDir(cwd, opts.dir)
+        if (target === null) return dirError(opts.dir)
+        if (opts.seed !== undefined && !Number.isSafeInteger(opts.seed)) {
+          return JSON.stringify({ ok: false, error: "seed must be a safe integer" }, null, 2)
+        }
+        const config = opts.config === undefined ? undefined : resolve(target, opts.config)
+        if (config !== undefined && config !== target && !config.startsWith(target + sep)) {
+          return JSON.stringify(
+            { ok: false, error: "config must stay inside the selected project directory" },
+            null,
+            2,
+          )
+        }
+        const { collectVerificationLevels } = await import("./levels-tool.ts")
+        return JSON.stringify(
+          await collectVerificationLevels(target, {
+            ...(opts.config === undefined ? {} : { config: opts.config }),
+            ...(opts.seed === undefined ? {} : { seed: opts.seed }),
+          }),
+          null,
+          2,
+        )
+      },
+    },
     {
       name: "nifra_doctor",
       description:

package/src/recipes/2.0.0.ts

@@ -0,0 +1,26 @@
+import type { UpgradeRecipe } from "./index.ts"
+
+/**
+ * Upgrade recipe for the Nifra 2.0 fixed-group cutover.
+ *
+ * The runner handles deterministic package pins and the removed budget import. Structural API changes
+ * stay as explicit notes so the tool never guesses at application intent.
+ */
+export const recipe: UpgradeRecipe = {
+  version: "2.0.0",
+  pins: [
+    { match: "@nifrajs/", to: "2.0.0" },
+    { match: "create-nifra", to: "2.0.0" },
+    { match: "nifra", to: "2.0.0" },
+  ],
+  dependencyMoves: [{ from: "@nifrajs/budget", to: "@nifrajs/core", toVersion: "2.0.0" }],
+  importMoves: [{ from: "@nifrajs/budget", to: "@nifrajs/core/budget" }],
+  notes: [
+    "Read the 1.x → 2.0 migration guide: https://nifra.dev/docs/migrate-2.",
+    "Optional server systems are instance-scoped plugins in 2.0. Add `.use(idempotency())`, `.use(effectLedger())`, `.use(mcp())`, `.use(streaming())`, `.use(websocket())`, or `.use(nodeDirect())` where used.",
+    "The old `@nifrajs/budget` package is removed. This recipe moves its dependency to `@nifrajs/core` and its imports to `@nifrajs/core/budget`.",
+    "Custom web backend mounts must implement the symbol-keyed BackendMount interface. `inProcessClient(app)` and `testClient(app)` already do.",
+    'If Better Auth or another library owns a non-Nifra route prefix, declare it in `nifra.check.json`, for example `{ "externalMounts": ["/auth"] }`.',
+    "Client failures with declared error schemas now narrow by `status`; narrow `res.status` before reading failure data.",
+  ],
+}