@nifrajs/cli 2.13.0 → 3.1.0

package/dist/cli.js

@@ -17,12 +17,13 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  *
  * 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 { createWebApp, DEFAULT_DEV_PORT, } from "@nifrajs/web";
 import { discoverRoutes } from "@nifrajs/web/fs";
-import { describeProject, describeRouteGraph, describeRoutes } from "./introspect.js";
+import { bindCommandArgv, findCommandSpec, renderCommandCatalogHelp } from "./command-catalog.js";
+import { applyEnvFiles, takeEnvFileFlags } from "./env-file.js";
 import { loadApp } from "./load.js";
 import { chooseBuildPipeline, describePipeline } from "./pipeline-guard.js";
 const HELP = `nifra - zero-config dev/build/start for a nifra app
@@ -36,6 +37,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
@@ -106,11 +111,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.
@@ -120,6 +127,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.
@@ -157,9 +166,17 @@ 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) => v;
 const asBunPlugins = (v) => v;
@@ -354,6 +371,7 @@ async function dev(app, flags) {
         ...(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
@@ -403,6 +421,34 @@ export async function assertUseIsEdgeExported(use, configPath, frameworkFile) {
         "  - Define `use` in framework.ts and re-export it from nifra.config.ts " +
         '(`export { use } from "./framework.ts"`) so `nifra dev` sees it too.');
 }
+/**
+ * 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) {
+    const pkgPath = resolve(cwd, "package.json");
+    if (!existsSync(pkgPath))
+        return;
+    let rootPackage;
+    try {
+        rootPackage = JSON.parse(readFileSync(pkgPath, "utf8"));
+    }
+    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.js");
+    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, target, flags) {
     const { isBuildTarget, renderSizeReport, BUILD_TARGETS } = await import("@nifrajs/web/build");
     if (!isBuildTarget(target)) {
@@ -460,6 +506,11 @@ async function buildForTarget(app, target, flags) {
         // 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.
@@ -515,6 +566,7 @@ export function parseFlags(args) {
     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])
@@ -531,14 +583,54 @@ export function parseFlags(args) {
             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) {
+    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() {
+    let inFlight;
+    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() {
-    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);
@@ -579,16 +671,33 @@ async function main() {
         console.log(renderLearnResult(stepArg !== undefined && /^\d+$/.test(stepArg) ? Number(stepArg) : undefined));
         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.js");
-        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;
+            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") {
@@ -601,30 +710,6 @@ async function main() {
             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.js");
-            const { applyDiagnosticRecipe } = await import("./fix-recipes.js");
-            const result = await collectCheckResult(process.cwd(), { lintsOnly: true });
-            const changed = [];
-            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.
@@ -636,77 +721,6 @@ async function main() {
         });
         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.js");
-        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.js");
-        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.js");
-        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.js");
-        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.js");
-        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];
@@ -732,241 +746,6 @@ async function main() {
         }
         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.js");
-        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.js");
-            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.js");
-            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) => {
-            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.js");
-            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) => {
-            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.js");
-            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) => {
-            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.js");
-            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) => {
-            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 = [];
-            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.js");
-            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).
@@ -993,36 +772,7 @@ async function main() {
     }
     // `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.js");
-        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;
@@ -1034,40 +784,6 @@ async function main() {
         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);
 }