@nifrajs/cli 2.13.0 → 3.1.0

package/src/cli.ts

@@ -9,7 +9,7 @@
  *
  * Bun-only (it runs the framework's TS + Bun plugins directly). The *output* runs anywhere.
  */
-import { existsSync } from "node:fs"
+import { existsSync, readFileSync } from "node:fs"
 import { resolve } from "node:path"
 import { inProcessClient } from "@nifrajs/client"
 import {
@@ -20,7 +20,8 @@ import {
 } from "@nifrajs/web"
 import { discoverRoutes } from "@nifrajs/web/fs"
 import type { BunPlugin } from "bun"
-import { describeProject, describeRouteGraph, describeRoutes } from "./introspect.ts"
+import { bindCommandArgv, findCommandSpec, renderCommandCatalogHelp } from "./command-catalog.ts"
+import { applyEnvFiles, takeEnvFileFlags } from "./env-file.ts"
 import { type LoadedApp, loadApp, type NifraFramework } from "./load.ts"
 import { chooseBuildPipeline, describePipeline } from "./pipeline-guard.ts"
 
@@ -40,6 +41,10 @@ export interface Flags {
    *
    * `nifra build --bun`: force the Bun build. Refuses when that would drop the app's `vitePlugins`. */
   readonly bun: boolean
+  /** `nifra dev --allow-duplicate-identity`: downgrade the Vite dev server's identity-parity check from
+   * a hard failure to a loud warning so a duplicate coming from a linked sibling repo doesn't take dev
+   * down while you fix the resolution. Dev only - `nifra build` always fails hard on a duplicate. */
+  readonly allowDuplicateIdentity: boolean
 }
 
 const HELP = `nifra - zero-config dev/build/start for a nifra app
@@ -53,6 +58,10 @@ Usage:
                                          preserved), no Vite in the process. CSS Modules, plain CSS,
                                          Tailwind and the app's own \`clientPlugins\`/\`serverPlugins\` run
                                          through the same Bun transforms production uses.
+                [--allow-duplicate-identity]  Downgrade the Vite dev server's identity-parity check to a
+                                         loud warning instead of a hard failure, so a duplicate React/
+                                         adapter copy from a linked sibling repo doesn't take dev down
+                                         while you fix the resolution. Dev only - \`nifra build\` still fails.
   nifra build   [--out <dir>] [--report]  Emit a complete deploy directory.
                 [--target <t>]             Target a FULL deploy dir for <t>:
                                          bun | node | deno | cf-pages | vercel | static. Packages
@@ -123,11 +132,13 @@ Usage:
                                          closed. Exits non-zero on any breaking change - run it in CI.
   nifra sdk     --lang <python|go> [--out <file>]
                                          Generate a deterministic non-TypeScript SDK from backend.ts.
-  nifra assure  [--config <file>] [--json] [--strict] [--out <file>] [--hydration] [--interact]
-                                         Emit one structured assurance bundle. The bundle records every
-                                         applicable gate as pass, fail, or skip and exits non-zero unless
-                                         its verdict is green. Without these bundle flags, the legacy
-                                         route-assurance report remains available.
+  nifra assure  [--config <file>] [--json]  Route-assurance report. Human table by default; --json emits
+                                         the {ok, routes, findings} report for agents.
+  nifra assure  --bundle [--json] [--strict] [--out <file>] [--hydration] [--interact]
+                                         Emit one structured assurance {version, gates, verdict} bundle
+                                         (always JSON). Records every applicable gate as pass, fail, or
+                                         skip and exits non-zero unless its verdict is green. --strict,
+                                         --hydration, --interact and --out imply --bundle.
   nifra contracts snapshot [--out <file>] Write the deterministic route contract lock.
   nifra contracts check [--json]          Check the current routes against contracts.lock.json.
   nifra replay <file>                     Replay a token-only verification metadata file.
@@ -137,6 +148,8 @@ Usage:
   nifra capabilities check [--lockfile <file>] [--config <file>] [--json]
                                          CI gate: fail on raw effect-import bypasses, declaration/evidence
                                          drift, unsafe GET/HEAD writes, idempotency gaps, or lockfile drift.
+  nifra capabilities explain <METHOD> <path> [--config <file>] [--json]
+                                         Explain one route's declared capability tokens and static provenance.
   nifra manifest emit [--out <file>] [--config <file>] [--sign <key-ref>]
                                          Emit a deterministic route trust artifact after assurance passes;
                                          optionally write an Ed25519 signature via the configured KMS signer.
@@ -174,10 +187,18 @@ Reads nifra.config.ts (adapter + clientModule + plugins; or framework.ts), backe
 routes/ from the current directory. Run from your project root.
 
 Port: \`dev\` and \`start\` share the default ${DEFAULT_DEV_PORT}. Override with \`--port <n>\` (alias \`-p\`) or the
-\`PORT\` env var (\`--port\` wins over \`PORT\`, which wins over the default).`
+\`PORT\` env var (\`--port\` wins over \`PORT\`, which wins over the default).
+
+Env: \`--env-file <path>\` works on EVERY command and may be repeated (later files win). Commands that
+reflect your app import it, so an app that validates its environment at module scope needs that
+environment present - without it the app aborts before nifra runs a single check. A variable already
+set in the process environment is never overwritten by a file.
+  e.g. \`nifra check --env-file .env.local\`
+
+${renderCommandCatalogHelp()}`
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const CLI_VERSION = "2.13.0"
+const CLI_VERSION = "3.1.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
@@ -389,6 +410,7 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
     ...(fw.publicEnvPrefix !== undefined ? { publicEnvPrefix: fw.publicEnvPrefix } : {}),
     poll: flags.poll,
     port: flags.port,
+    ...(flags.allowDuplicateIdentity ? { allowDuplicateIdentity: true } : {}),
     ...(fw.conditions ? { conditions: fw.conditions } : {}),
     ...(fw.define ? { define: fw.define } : {}),
     // `load` resolves route modules through VITE, not through Bun. That is what makes the Vite
@@ -445,6 +467,38 @@ export async function assertUseIsEdgeExported(
   )
 }
 
+/**
+ * A production build must not ship a workspace-linked package whose `default`-condition artifact is
+ * missing or older than its source. The `"bun": "./src"` / `"default": "./dist"` split means Bun (this
+ * build, the tests) reads live source while the deployed app and any node consumer read `dist/` - so a
+ * green `nifra build` can bundle stale or absent dist and the drift never shows in a diff. The doctor
+ * reports the same skew as an advisory during development; at build time it is a hard failure, because
+ * this is the artifact that ships. No-op outside a workspace: tarball-installed deps cannot drift.
+ */
+async function assertFreshWorkspaceDists(cwd: string): Promise<void> {
+  const pkgPath = resolve(cwd, "package.json")
+  if (!existsSync(pkgPath)) return
+  let rootPackage: Record<string, unknown>
+  try {
+    rootPackage = JSON.parse(readFileSync(pkgPath, "utf8")) as Record<string, unknown>
+  } catch {
+    return // an unreadable/!JSON package.json is a separate problem; don't mask it as a stale-dist failure
+  }
+  const { collectStaleWorkspaceDists } = await import("./doctor.ts")
+  const stale = await collectStaleWorkspaceDists(cwd, rootPackage)
+  if (stale.length === 0) return
+  const lines = stale.map((f) =>
+    f.missing
+      ? `  ${f.package}: ${f.distFile} was never built (source ${f.sourceFile})`
+      : `  ${f.package}: ${f.distFile} is ${f.behindSeconds}s behind ${f.sourceFile}`,
+  )
+  throw new Error(
+    `[nifra] build blocked: ${stale.length} workspace-linked package(s) ship a stale or missing dist artifact, so the deployed app would serve code this build did not produce:\n${lines.join(
+      "\n",
+    )}\nBuild the offending package(s) (\`bun run build\` in each) so every export target exists and is at least as new as its source, then rebuild.`,
+  )
+}
+
 async function buildForTarget(app: LoadedApp, target: string, flags: Flags): Promise<void> {
   const { isBuildTarget, renderSizeReport, BUILD_TARGETS } = await import("@nifrajs/web/build")
   if (!isBuildTarget(target)) {
@@ -505,6 +559,11 @@ async function buildForTarget(app: LoadedApp, target: string, flags: Flags): Pro
     // The static target needs a built app to drive prerendering - only build it when targeting static.
     ...(target === "static" ? { prerenderApp: await buildPrerenderApp(app) } : {}),
   })
+  // A production build must not certify itself green while a workspace-linked dependency ships a dist
+  // artifact older than (or absent next to) its source: the `bun`->src condition let this compile read
+  // live source, but the deployed app and every node consumer read `dist/`. Gate here, after the compile
+  // proved the source is buildable, so the failure names the package to rebuild rather than a bundle error.
+  await assertFreshWorkspaceDists(cwd)
   console.log(`nifra build (${target}, ${decision.pipeline}) → ${result.run}`)
   // The pipeline is stated on every build, not only the surprising ones - an auto-selected Vite build
   // must never look like the default, and a default Bun build must not leave the question open either.
@@ -575,6 +634,7 @@ export function parseFlags(args: readonly string[]): Flags {
   let report = false
   let vite = false
   let bun = false
+  let allowDuplicateIdentity = 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])
@@ -584,15 +644,58 @@ export function parseFlags(args: readonly string[]): Flags {
     else if (a === "--report") report = true
     else if (a === "--vite") vite = true
     else if (a === "--bun") bun = true
+    else if (a === "--allow-duplicate-identity") allowDuplicateIdentity = true
   }
   if (!Number.isFinite(port) || port < 0 || port > 65535) {
     throw new Error(`[nifra] invalid --port: ${port}`)
   }
-  return { port, out, poll, target, report, vite, bun }
+  return { port, out, poll, target, report, vite, bun, allowDuplicateIdentity }
+}
+
+/**
+ * `assure` uses the structured-bundle lane only when explicitly asked. A bare `--json` is NOT a
+ * request for the bundle - it keeps the legacy `{ ok, routes, findings }` report machine-readable, so a
+ * pre-bundle consumer is never silently handed the `{ gates, verdict }` shape. `--bundle` (or a
+ * bundle-only flag) opts in; `--bundle --json` still yields the bundle, which is always JSON.
+ */
+export function assureBundleRequested(argv: readonly string[]): boolean {
+  return (
+    argv.includes("--bundle") ||
+    argv.includes("--strict") ||
+    argv.includes("--hydration") ||
+    argv.includes("--interact") ||
+    argv.includes("--out")
+  )
+}
+
+/**
+ * A command that reflects the project imports it, and an app that validates its environment at module
+ * scope calls `process.exit` from inside that import. Nothing is throwable at that point, so the whole
+ * output is the app's own abort message with no hint that a nifra command triggered it. Name the cause
+ * on the way out and point at the flag that supplies the environment.
+ */
+function installReflectionExitHint(): (command: string | undefined) => void {
+  let inFlight: string | undefined
+  process.on("exit", (code) => {
+    if (inFlight === undefined || code === 0) return
+    process.stderr.write(
+      `\n[nifra] \`nifra ${inFlight}\` reflects this project by importing it, and the import exited ` +
+        `with code ${code} before the command produced a result - the message above came from your app, not nifra.\n` +
+        `        If it is the app's environment validation, supply the environment and re-run:\n` +
+        `        nifra ${inFlight} --env-file .env.local\n`,
+    )
+  })
+  return (command) => {
+    inFlight = command
+  }
 }
 
 async function main(): Promise<void> {
-  const argv = Bun.argv.slice(2)
+  const { argv: rawArgv, files: envFiles } = takeEnvFileFlags(Bun.argv.slice(2))
+  // Applied before any command runs: a reflecting command imports the app on its first await, and the
+  // app reads its environment at module scope, so the variables must already be in place by then.
+  if (envFiles.length > 0) await applyEnvFiles(process.cwd(), envFiles)
+  const argv = rawArgv
   const command = argv[0]
   if (command === undefined || command === "--help" || command === "-h" || command === "help") {
     console.log(HELP)
@@ -637,18 +740,31 @@ async function main(): Promise<void> {
     )
     return
   }
-  // `check` is a pure cwd-based gate (typecheck + lint) - it must run even when the project doesn't
-  // load (API-only, not built yet), so it dispatches before the eager `loadApp` below.
-  if (command === "check") {
-    const { runCheck } = await import("./check.ts")
-    if (
-      !(await runCheck(process.cwd(), {
-        json: argv.includes("--json"),
-        structured: argv.includes("--json"),
-        lintsOnly: argv.includes("--lints-only"),
-      }))
-    )
+  const catalogSpec = command === undefined ? undefined : findCommandSpec(command)
+  if (catalogSpec?.transports.includes("cli")) {
+    const markReflecting = installReflectionExitHint()
+    try {
+      const input = bindCommandArgv(catalogSpec, argv.slice(1))
+      markReflecting(command)
+      const output = await catalogSpec.run(input, { cwd: process.cwd(), cliVersion: CLI_VERSION })
+      markReflecting(undefined)
+      const asRecord = output as unknown as Record<string, unknown>
+      const wantsJson = asRecord.json === true || argv.includes("--json")
+      if (wantsJson) {
+        const value = catalogSpec.json?.(output, input) ?? output
+        console.log(typeof value === "string" ? value : JSON.stringify(value, null, 2))
+      } else {
+        console.log(catalogSpec.render(output, input).join("\n"))
+      }
+      if (catalogSpec.success !== undefined && !catalogSpec.success(output, input))
+        process.exitCode = 1
+    } catch (err) {
+      // A thrown error is nifra's own reporting path, not a silent abort: clear the sentinel so the
+      // hint stays reserved for the case where the process died inside the app import.
+      markReflecting(undefined)
+      console.error(formatCliError(err))
       process.exitCode = 1
+    }
     return
   }
   if (command === "verify") {
@@ -660,29 +776,6 @@ async function main(): Promise<void> {
     if (!ok) process.exitCode = 1
     return
   }
-  if (command === "fix") {
-    const codeIndex = argv.indexOf("--code")
-    const code = codeIndex === -1 ? undefined : argv[codeIndex + 1]
-    try {
-      const { collectCheckResult } = await import("./check.ts")
-      const { applyDiagnosticRecipe } = await import("./fix-recipes.ts")
-      const result = await collectCheckResult(process.cwd(), { lintsOnly: true })
-      const changed: string[] = []
-      for (const diagnostic of result.structuredDiagnostics ?? []) {
-        if (code !== undefined && diagnostic.code !== code) continue
-        changed.push(...(await applyDiagnosticRecipe(process.cwd(), diagnostic)))
-      }
-      const final = await collectCheckResult(process.cwd(), { lintsOnly: true })
-      console.log(
-        JSON.stringify({ changed, diagnostics: final.structuredDiagnostics ?? [] }, null, 2),
-      )
-      if (final.ok === false) process.exitCode = 1
-    } catch (err) {
-      console.error(formatCliError(err))
-      process.exitCode = 1
-    }
-    return
-  }
   // `init-agents` retrofits the agent-discovery files (.mcp.json, CLAUDE.md, …) into the cwd. It's a
   // pure file-writing command independent of the app loading, so dispatch it before the eager `loadApp`
   // (an existing app might be API-only or not yet built). It always succeeds unless a write throws.
@@ -694,75 +787,6 @@ 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
-  }
-  // `sync-routes` regenerates the route-search types `.d.ts` (typed `navigate({ to, search })`) from
-  // `routes/`. Pure fs/text (needs only the route tree, not `framework.ts`), so dispatch before `loadApp`.
-  if (command === "sync-routes") {
-    const { runSyncRoutes } = await import("./sync-routes.ts")
-    if (!(await runSyncRoutes(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") {
-    const { runDoctor } = await import("./doctor.ts")
-    const targetIdx = argv.indexOf("--target")
-    const target = targetIdx !== -1 ? argv[targetIdx + 1] : undefined
-    if (targetIdx !== -1 && (target === undefined || target.startsWith("-"))) {
-      console.error("[nifra] --target needs a value: bun | node | deno | cf-pages | vercel")
-      process.exitCode = 1
-      return
-    }
-    if (
-      !(await runDoctor(process.cwd(), {
-        json: argv.includes("--json"),
-        autoFix: argv.includes("--auto-fix") || argv.includes("--fix"),
-        strict: argv.includes("--strict"),
-        ...(target === undefined ? {} : { target }),
-      }))
-    )
-      process.exitCode = 1
-    return
-  }
-  // `snapshot` / `diff` load ONLY backend.ts (the API contract) - like `check`, they must run on an
-  // API-only project, so they dispatch before the eager `loadApp`.
-  if (command === "snapshot") {
-    const { runSnapshot } = await import("./diff-tool.ts")
-    const outIdx = argv.indexOf("--out")
-    const out = outIdx !== -1 ? argv[outIdx + 1] : undefined
-    if (outIdx !== -1 && (out === undefined || out.startsWith("-"))) {
-      console.error("[nifra] --out needs a file path")
-      process.exitCode = 1
-      return
-    }
-    try {
-      await runSnapshot(process.cwd(), out !== undefined ? { out } : {})
-    } catch (err) {
-      console.error(formatCliError(err))
-      process.exitCode = 1
-    }
-    return
-  }
-  if (command === "diff") {
-    const { runDiff, DEFAULT_SNAPSHOT_FILE } = await import("./diff-tool.ts")
-    const baseline = argv.slice(1).find((arg) => !arg.startsWith("-")) ?? DEFAULT_SNAPSHOT_FILE
-    try {
-      if (!(await runDiff(process.cwd(), baseline, { json: argv.includes("--json") }))) {
-        process.exitCode = 1
-      }
-    } catch (err) {
-      console.error(formatCliError(err))
-      process.exitCode = 1
-    }
-    return
-  }
   if (command === "sdk") {
     const languageIndex = argv.indexOf("--lang")
     const language = languageIndex === -1 ? undefined : argv[languageIndex + 1]
@@ -787,237 +811,6 @@ async function main(): Promise<void> {
     }
     return
   }
-  // Route assurance intentionally loads only its explicit config (which imports the backend it audits),
-  // not the full SSR app. Like snapshot/diff, this works for API-only projects.
-  if (command === "assure") {
-    const { runAssurance } = await import("./assure.ts")
-    const configIdx = argv.indexOf("--config")
-    const config = configIdx !== -1 ? argv[configIdx + 1] : undefined
-    if (configIdx !== -1 && (config === undefined || config.startsWith("-"))) {
-      console.error("[nifra] --config needs a file path")
-      process.exitCode = 1
-      return
-    }
-    try {
-      if (
-        !(await runAssurance(process.cwd(), {
-          json: argv.includes("--json"),
-          bundle:
-            argv.includes("--json") ||
-            argv.includes("--strict") ||
-            argv.includes("--hydration") ||
-            argv.includes("--interact") ||
-            argv.includes("--out"),
-          strict: argv.includes("--strict"),
-          hydration: argv.includes("--hydration"),
-          interact: argv.includes("--interact"),
-          ...(argv.includes("--out") ? { out: argv[argv.indexOf("--out") + 1] } : {}),
-          ...(config !== undefined ? { config } : {}),
-        }))
-      )
-        process.exitCode = 1
-    } catch (err) {
-      console.error(formatCliError(err))
-      process.exitCode = 1
-    }
-    return
-  }
-  if (command === "contracts") {
-    const action = argv[1]
-    const outIndex = argv.indexOf("--out")
-    const out = outIndex === -1 ? undefined : argv[outIndex + 1]
-    try {
-      const { checkContractsLock, snapshotContracts } = await import("./contracts.ts")
-      if (action === "snapshot") {
-        const lock = await snapshotContracts(process.cwd(), out)
-        if (argv.includes("--json")) console.log(JSON.stringify(lock, null, 2))
-        else console.log(`[nifra] wrote ${Object.keys(lock.routes).length} contract digests`)
-      } else if (action === "check") {
-        const result = await checkContractsLock(process.cwd())
-        const output = { ok: result.present && result.diagnostics.length === 0, ...result }
-        console.log(JSON.stringify(output, null, 2))
-        if (!output.ok) process.exitCode = 1
-      } else {
-        console.error("[nifra] contracts needs snapshot or check")
-        process.exitCode = 1
-      }
-    } catch (err) {
-      console.error(formatCliError(err))
-      process.exitCode = 1
-    }
-    return
-  }
-  if (command === "replay") {
-    const file = argv[1]
-    if (file === undefined || file.startsWith("-")) {
-      console.error("[nifra] replay needs a file path")
-      process.exitCode = 1
-      return
-    }
-    try {
-      const { runReplay } = await import("./replay.ts")
-      const result = await runReplay(process.cwd(), file)
-      console.log(JSON.stringify(result, null, 2))
-      if (!result.ok) process.exitCode = 1
-    } catch (err) {
-      console.error(formatCliError(err))
-      process.exitCode = 1
-    }
-    return
-  }
-  if (command === "capabilities") {
-    const action = argv[1]
-    const valueAfter = (flag: string): string | undefined => {
-      const index = argv.indexOf(flag)
-      const value = index === -1 ? undefined : argv[index + 1]
-      if (index !== -1 && (value === undefined || value.startsWith("-"))) {
-        throw new Error(`[nifra] ${flag} needs a file path`)
-      }
-      return value
-    }
-    try {
-      const { runCapabilityCheck, runCapabilitySnapshot } = await import("./capabilities-tool.ts")
-      const config = valueAfter("--config")
-      if (action === "snapshot") {
-        const out = valueAfter("--out")
-        if (
-          !(await runCapabilitySnapshot(process.cwd(), {
-            ...(config !== undefined ? { config } : {}),
-            ...(out !== undefined ? { out } : {}),
-          }))
-        )
-          process.exitCode = 1
-      } else if (action === "check") {
-        const lockfile = valueAfter("--lockfile")
-        if (
-          !(await runCapabilityCheck(process.cwd(), {
-            ...(config !== undefined ? { config } : {}),
-            ...(lockfile !== undefined ? { lockfile } : {}),
-            json: argv.includes("--json"),
-          }))
-        )
-          process.exitCode = 1
-      } else {
-        throw new Error("[nifra] capabilities needs `snapshot` or `check`")
-      }
-    } catch (err) {
-      console.error(formatCliError(err))
-      process.exitCode = 1
-    }
-    return
-  }
-  if (command === "manifest") {
-    const action = argv[1]
-    const valueAfter = (flag: string): string | undefined => {
-      const index = argv.indexOf(flag)
-      const value = index === -1 ? undefined : argv[index + 1]
-      if (index !== -1 && (value === undefined || value.startsWith("-"))) {
-        throw new Error(`[nifra] ${flag} needs a value`)
-      }
-      return value
-    }
-    try {
-      const { runManifestDiff, runManifestEmit } = await import("./manifest-tool.ts")
-      if (action === "emit") {
-        const config = valueAfter("--config")
-        const out = valueAfter("--out")
-        const sign = valueAfter("--sign")
-        if (
-          !(await runManifestEmit(process.cwd(), {
-            ...(config !== undefined ? { config } : {}),
-            ...(out !== undefined ? { out } : {}),
-            ...(sign !== undefined ? { sign } : {}),
-          }))
-        )
-          process.exitCode = 1
-      } else if (action === "diff") {
-        const paths = argv.slice(2).filter((arg) => !arg.startsWith("-"))
-        if (paths.length !== 2) throw new Error("[nifra] manifest diff needs <before> <after>")
-        if (
-          !(await runManifestDiff(process.cwd(), paths[0]!, paths[1]!, {
-            json: argv.includes("--json"),
-          }))
-        )
-          process.exitCode = 1
-      } else {
-        throw new Error("[nifra] manifest needs `emit` or `diff`")
-      }
-    } catch (err) {
-      console.error(formatCliError(err))
-      process.exitCode = 1
-    }
-    return
-  }
-  if (command === "levels") {
-    const valueAfter = (flag: string): string | undefined => {
-      const index = argv.indexOf(flag)
-      const value = index === -1 ? undefined : argv[index + 1]
-      if (index !== -1 && (value === undefined || value.startsWith("-"))) {
-        throw new Error(`[nifra] ${flag} needs a value`)
-      }
-      return value
-    }
-    try {
-      const { runLevels } = await import("./levels-tool.ts")
-      const config = valueAfter("--config")
-      const minRaw = valueAfter("--min")
-      const min = minRaw === undefined ? undefined : Number(minRaw)
-      if (min !== undefined && (!Number.isInteger(min) || min < 0 || min > 4)) {
-        throw new Error("[nifra] --min must be an integer level between 0 and 4")
-      }
-      if (
-        !(await runLevels(process.cwd(), {
-          json: argv.includes("--json"),
-          ...(config !== undefined ? { config } : {}),
-          ...(min !== undefined ? { min } : {}),
-        }))
-      )
-        process.exitCode = 1
-    } catch (err) {
-      console.error(formatCliError(err))
-      process.exitCode = 1
-    }
-    return
-  }
-  if (command === "prove") {
-    const valueAfter = (flag: string): string | undefined => {
-      const index = argv.indexOf(flag)
-      const value = index === -1 ? undefined : argv[index + 1]
-      if (index !== -1 && (value === undefined || value.startsWith("-"))) {
-        throw new Error(`[nifra] ${flag} needs a value`)
-      }
-      return value
-    }
-    try {
-      const minRaw = valueAfter("--min")
-      const min = minRaw === undefined ? undefined : Number(minRaw)
-      if (min !== undefined && (!Number.isInteger(min) || min < 0 || min > 4)) {
-        throw new Error("[nifra] --min must be an integer level between 0 and 4")
-      }
-      const changedFiles: string[] = []
-      for (let index = 0; index < argv.length; index++) {
-        if (argv[index] !== "--file") continue
-        const file = argv[index + 1]
-        if (file === undefined || file.startsWith("-"))
-          throw new Error("[nifra] --file needs a path")
-        changedFiles.push(file)
-        index++
-      }
-      const { runWorkGraph } = await import("./work-graph.ts")
-      if (
-        !(await runWorkGraph(process.cwd(), {
-          json: argv.includes("--json"),
-          ...(changedFiles.length === 0 ? {} : { changedFiles }),
-          ...(min === undefined ? {} : { minLevel: min }),
-        }))
-      )
-        process.exitCode = 1
-    } catch (err) {
-      console.error(formatCliError(err))
-      process.exitCode = 1
-    }
-    return
-  }
   // `upgrade` is a pure cwd file-transformer (package.json pins + import moves) driven by a per-release
   // recipe, then verified with `nifra check`. Dispatch before the eager `loadApp` - it must run on any
   // repo (API-only, not built, or mid-upgrade with edits that don't yet typecheck under dry-run).
@@ -1042,36 +835,7 @@ async function main(): Promise<void> {
   }
   // `port` is a pure cwd-based portability linter (scans source, doesn't run the app) - like `check`/
   // `doctor`, dispatch before the eager `loadApp` so it runs on an API-only / not-yet-built project.
-  if (command === "port") {
-    const { runPort } = await import("./port.ts")
-    const targetIdx = argv.indexOf("--target")
-    const target = targetIdx !== -1 ? argv[targetIdx + 1] : undefined
-    if (targetIdx !== -1 && (target === undefined || target.startsWith("-"))) {
-      console.error("[nifra] --target needs a value: bun | node | deno | cf-pages | vercel")
-      process.exitCode = 1
-      return
-    }
-    try {
-      const passed = await runPort(process.cwd(), {
-        ...(target !== undefined ? { target } : {}),
-        json: argv.includes("--json"),
-        ci: argv.includes("--ci"),
-        strict: argv.includes("--strict"),
-      })
-      if (!passed) process.exitCode = 1
-    } catch (err) {
-      console.error(formatCliError(err))
-      process.exitCode = 1
-    }
-    return
-  }
-  if (
-    command !== "dev" &&
-    command !== "build" &&
-    command !== "start" &&
-    command !== "context" &&
-    command !== "routes"
-  ) {
+  if (command !== "dev" && command !== "build" && command !== "start") {
     console.error(`[nifra] unknown command: ${command}\n`)
     console.error(HELP)
     process.exitCode = 1
@@ -1081,36 +845,7 @@ async function main(): Promise<void> {
   const app = await loadApp(process.cwd(), flags.out)
   if (command === "dev") await dev(app, flags)
   else if (command === "build") await buildForTarget(app, flags.target, flags)
-  else if (command === "context") console.log(describeProject(app))
-  else if (command === "routes") {
-    if (argv.includes("--graph")) {
-      console.log(await describeRouteGraph(app, { json: argv.includes("--json") }))
-    } else if (argv.includes("--modes")) {
-      // `--modes` answers a different question than the default table: not "what URLs exist" but "how
-      // does each render, and can the target I'm about to deploy to actually honour that". Resolves
-      // against `--target` when given, so a `static` build's server-needing route fails here, in one
-      // place, instead of 404ing in production.
-      const { buildRouteManifest, renderRouteManifest } = await import(
-        "@nifrajs/web/route-manifest"
-      )
-      const manifest = discoverRoutes(app.routesDir)
-      // `flags.target` defaults to "bun" for `build`; here an EXPLICIT `--target` is what opts into
-      // gating, so read it from argv rather than inheriting the build default (which would silently gate
-      // every `nifra routes --modes` against bun).
-      const targetIdx = argv.indexOf("--target")
-      const target = targetIdx !== -1 ? argv[targetIdx + 1] : undefined
-      const routeManifest = await buildRouteManifest(manifest, {
-        ...(target !== undefined ? { target } : {}),
-      })
-      if (argv.includes("--json")) console.log(JSON.stringify(routeManifest, null, 2))
-      else console.log(renderRouteManifest(routeManifest))
-      // A target that cannot honour a route is a build-breaking fact, not a note: exit non-zero so the
-      // same command in CI gates the deploy it is warning about.
-      if (routeManifest.conflicts.length > 0) process.exitCode = 1
-    } else {
-      console.log(await describeRoutes(app, { json: argv.includes("--json") }))
-    }
-  } else await start(app, flags)
+  else await start(app, flags)
 }
 
 // Only run the CLI when invoked as the entry (`bun cli.ts …`), not when a test imports it for the