@nifrajs/cli 4.0.2 → 5.0.0

package/src/cli.ts

@@ -24,7 +24,7 @@ import { formatShadowedPages, shadowedPages } from "@nifrajs/web/route-manifest"
 import type { BunPlugin } from "bun"
 import { adapterFile, BACKEND_APP_FILE } from "./app-files.ts"
 import { bindCommandArgv, findCommandSpec, renderCommandCatalogHelp } from "./command-catalog.ts"
-import { applyEnvFiles, forgetAutoLoadedEnv, takeEnvFileFlags } from "./env-file.ts"
+import { applyEnvFiles, forgetAutoLoadedEnv, REFLECT_ENV, takeEnvFileFlags } from "./env-file.ts"
 import { FRAMEWORK_WEB_OPTIONS, type LoadedApp, loadApp, type NifraFramework } from "./load.ts"
 import { chooseBuildPipeline, describePipeline } from "./pipeline-guard.ts"
 import {
@@ -165,6 +165,10 @@ Usage:
                                          against it: a route the target can't honour (an ssr route on a
                                          static build, ISR where there's no revalidation) exits nonzero
                                          with the consequence - run in CI so it fails the build, not prod.
+  nifra routes --hooks [--json]          List the hooks each backend route and each prefix's unmatched
+               [--since <file>]          paths actually run: kind, plugin name, and where it was
+                                         registered (app, group, merge, mount). --since diffs against a
+                                         saved --json report.
   nifra init-agents [--force] [--json]   Retrofit an EXISTING app with the agent files a new app ships:
                                          .mcp.json + .cursor/mcp.json (register this project's nifra MCP),
                                          each agent's pointer to AGENTS.md (CLAUDE.md, GEMINI.md,
@@ -201,6 +205,8 @@ Usage:
                                          backend code in browser code). Run as "done"; --json for agents;
                                          --sarif emits the same stable diagnostics as SARIF 2.1.0 for external
                                          review tools; --lints-only skips tsc for a near-instant inner-loop pass.
+                                         With a contracts.lock.json, both modes import backend/app.ts
+                                         (running its top-level code) to compare the routes it serves.
   nifra verify   [--release] [--json]    Run the shared repository verification gate. --release runs the
                                          full build, test, coverage, corpus, consumer, and cross-runtime gate.
   nifra fix     [--code <NF-code>]       Apply a registered diagnostic recipe, then print the remaining
@@ -262,7 +268,8 @@ Usage:
                 [--list] [--json]        apply exact imports, pin every matching dependency (keeping
                 [--exact]                ^/~, or exact with --exact), then verify with nifra check.
                 [--allow-downgrade]      Dry-run by default; --write applies then verifies (--no-verify
-                                         to skip). --list shows available targets. A version newer than
+                [--no-hooks]             to skip), then prints how hook scope changed (--no-hooks to
+                                         skip). --list shows available targets. A version newer than
                                          this CLI prints the command for that release's CLI. Fail-closed
                                          on an unknown version or a rollback (--allow-downgrade
                                          overrides). Deterministic + idempotent.
@@ -276,6 +283,10 @@ Usage:
                                          params, the data its output schemas let through, and api typed
                                          by backend/app.ts. dev, build and check refresh them too;
                                          --check fails when one is stale.
+  nifra schemas [--write] [--json]       Draft loaderOutput/actionOutput from each loader's and
+                                         action's return type for review; --write adds the missing
+                                         ones (marked nifra:generated) and refreshes generated ones.
+                                         Lists the returned fields a hand-written schema drops.
   nifra port    [--target <t>] [--json]  Portability linter: print a feature × deploy-target capability
                 [--ci] [--strict]        matrix (in-memory stores, in-process cron/WebSocket, Bun/Deno
                                          globals, node: builtins) with file:line evidence. --target auto-
@@ -304,12 +315,23 @@ set in the process environment is never overwritten by a file.
 ${renderCommandCatalogHelp()}`
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const CLI_VERSION = "4.0.2"
+const CLI_VERSION = "5.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
 const asBunPlugins = (v: readonly unknown[]): BunPlugin[] => v as BunPlugin[]
 
+// biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Trusted application configuration supplies native Vite plugins; the pinned pipeline validates their hooks.
+const asComponentPlugins = (
+  value: readonly unknown[],
+): NonNullable<
+  import("@nifrajs/web/server-components/build").ComponentPipelineOptions["plugins"]
+> =>
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Trusted config forwards the pinned Vite plugin ABI; this does not accept request data.
+  value as NonNullable<
+    import("@nifrajs/web/server-components/build").ComponentPipelineOptions["plugins"]
+  >
+
 /**
  * Render an error for the CLI, unwrapping the detail a bare `.message` drops.
  *
@@ -345,6 +367,27 @@ export function formatCliError(err: unknown): string {
 }
 
 async function dev(app: LoadedApp, flags: Flags): Promise<void> {
+  if (app.framework.componentPipeline !== undefined) {
+    if (flags.bun)
+      throw new Error(
+        "[nifra/components] Components require the Vite 8 pipeline; Bun remains a server runtime",
+      )
+    const { devServerComponents } = await import("@nifrajs/web/server-components/build")
+    if (
+      app.resolvedPlugins.clientPlugins.length > 0 ||
+      app.resolvedPlugins.serverPlugins.length > 0
+    )
+      throw new Error(
+        "[nifra/components] Use Vite equivalents for client/server Bun plugins in the component pipeline",
+      )
+    await devServerComponents({
+      ...app.framework.componentPipeline,
+      root: app.cwd,
+      port: flags.port,
+      plugins: asComponentPlugins(app.resolvedPlugins.vitePlugins),
+    })
+    return
+  }
   if (flags.vite && flags.bun) {
     throw new Error("[nifra] `nifra dev` takes `--vite` or `--bun`, not both.")
   }
@@ -511,6 +554,7 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
       ...(fw.conditions ? { conditions: fw.conditions } : {}),
       ...(fw.define ? { define: fw.define } : {}),
       indicator: showsIndicator(flags, fw),
+      allowedHosts: fw.dev?.allowedHosts ?? [],
       createApp: (clientEntry, importQuery, dev) =>
         createWebApp({
           adapter: asAdapter(fw.adapter),
@@ -693,7 +737,7 @@ async function assertFreshWorkspaceDists(cwd: string): Promise<void> {
   let rootPackage: Record<string, unknown>
   try {
     rootPackage = JSON.parse(readFileSync(pkgPath, "utf8")) as Record<string, unknown>
-    // @nifra-gate-reviewed: not a security gate. An unreadable/non-JSON package.json is a separate
+    // nifra-expect NF-S001: not a security gate. An unreadable/non-JSON package.json is a separate
     // build problem; returning here skips the freshness check rather than masking a denial.
   } catch {
     return // an unreadable/!JSON package.json is a separate problem; don't mask it as a stale-dist failure
@@ -727,6 +771,40 @@ async function buildForTarget(
     throw new Error("[nifra] `nifra build` takes `--vite` or `--bun`, not both.")
   }
   const { framework: fw } = app
+  if (fw.componentPipeline !== undefined) {
+    if (flags.bun)
+      throw new Error(
+        "[nifra/components] Components require the Vite 8 pipeline; Bun remains a server runtime",
+      )
+    if (target === "static")
+      throw new Error(
+        "[nifra/components] Component owners require private per-request execution; choose bun, node, deno, cloudflare, or vercel",
+      )
+    if (
+      app.resolvedPlugins.clientPlugins.length > 0 ||
+      app.resolvedPlugins.serverPlugins.length > 0
+    )
+      throw new Error(
+        "[nifra/components] Use Vite equivalents for client/server Bun plugins in the component pipeline",
+      )
+    const { buildServerComponents } = await import("@nifrajs/web/server-components/build")
+    const outDir =
+      target === "vercel" && flags.out === undefined
+        ? resolve(app.cwd, ".vercel/output")
+        : app.outDir
+    const result = await buildServerComponents({
+      ...fw.componentPipeline,
+      target,
+      root: app.cwd,
+      outDir,
+      plugins: asComponentPlugins(app.resolvedPlugins.vitePlugins),
+    })
+    await assertFreshWorkspaceDists(app.cwd)
+    console.log(
+      `[nifra/components] Built ${fw.componentPipeline.adapter} for ${target} (${result.build}) in ${outDir}`,
+    )
+    return
+  }
   const cssCodeSplitRequested = fw.cssCodeSplit === false
   const hasBunTransforms =
     app.resolvedPlugins.clientPlugins.length > 0 || app.resolvedPlugins.serverPlugins.length > 0
@@ -945,6 +1023,42 @@ function installReflectionExitHint(): (command: string | undefined) => void {
   }
 }
 
+/** Commands that import the app only to read what it declares, never sending it a request, so the
+ * app may skip connecting to its services. `assure` qualifies without its bundle lane, which renders. */
+const READ_ONLY_COMMANDS: ReadonlySet<string> = new Set([
+  "capabilities",
+  "check",
+  "context",
+  "contracts",
+  "diff",
+  "doctor",
+  "manifest",
+  "openapi",
+  "routes",
+  "sync-manifest",
+  "sync-routes",
+])
+
+const HELD_OPEN_GRACE_MS = 2_000
+
+/**
+ * A command that imports the app for its answer has already answered when the app's own work - a
+ * database or Redis client reconnecting, an interval - would keep the process alive indefinitely.
+ * A process that exits on its own never reaches this unref'd timer; a held one is ended with a note.
+ */
+function exitIfHeldOpen(command: string): void {
+  setTimeout(() => {
+    process.stderr.write(
+      `[nifra] \`nifra ${command}\` has finished, but something the app started when it was imported ` +
+        `(an open connection or a timer) is keeping the process alive, so nifra is exiting.` +
+        (process.env[REFLECT_ENV] === command
+          ? ` To skip that work while nifra only reads the app, check process.env.${REFLECT_ENV}, which is set to "${command}".\n`
+          : "\n"),
+    )
+    process.exit(typeof process.exitCode === "number" ? process.exitCode : 0)
+  }, HELD_OPEN_GRACE_MS).unref()
+}
+
 /** Set on the copy of `nifra mcp` that serves without `.env` files, so it does not restart again. */
 const MCP_WITHOUT_ENV_FILES = "NIFRA_MCP_WITHOUT_ENV_FILES"
 
@@ -1051,6 +1165,9 @@ async function main(): Promise<void> {
   const catalogSpec = findCommandSpec(dbSub === undefined ? command : `db-${dbSub}`)
   if (catalogSpec?.transports.includes("cli")) {
     const markReflecting = installReflectionExitHint()
+    if (READ_ONLY_COMMANDS.has(command) || (command === "assure" && !assureBundleRequested(argv))) {
+      process.env[REFLECT_ENV] = command
+    }
     try {
       const input = bindCommandArgv(catalogSpec, argv.slice(dbSub === undefined ? 1 : 2))
       markReflecting(command)
@@ -1086,6 +1203,7 @@ async function main(): Promise<void> {
           ? candidate
           : 1
     }
+    exitIfHeldOpen(command)
     return
   }
   if (command === "verify") {
@@ -1150,6 +1268,7 @@ async function main(): Promise<void> {
         json: argv.includes("--json"),
         list: argv.includes("--list"),
         verify: !argv.includes("--no-verify"),
+        hooks: !argv.includes("--no-hooks"),
         allowDowngrade: argv.includes("--allow-downgrade"),
         exact: argv.includes("--exact"),
         cliVersion: CLI_VERSION,
@@ -1278,12 +1397,29 @@ function findCliCommand(values: readonly string[]): number {
   return values.findIndex((value) => isCliCommandToken(value))
 }
 
+/**
+ * The command vector from one runtime argv: the command, then its arguments. Arguments typed before
+ * the command (`nifra --json check`) follow the command's own, ahead of any `--`, rather than being
+ * dropped. Only when index 1 is the script: a runtime flag there means the leading entries are the
+ * runtime's own, not the caller's.
+ */
+export function commandArgv(values: readonly string[], commandIndex: number): readonly string[] {
+  const command = values.slice(commandIndex)
+  const script = values[1]
+  if (commandIndex <= 2 || script === undefined || script.startsWith("-")) return command
+  const leading = values.slice(2, commandIndex)
+  const separator = command.indexOf("--")
+  return separator === -1
+    ? [...command, ...leading]
+    : [...command.slice(0, separator), ...leading, ...command.slice(separator)]
+}
+
 function cliArgv(): readonly string[] {
   const reexec = reexecCliArgv()
   if (reexec !== undefined) return reexec
   for (const values of [Bun.argv, process.argv]) {
     const commandIndex = findCliCommand(values)
-    if (commandIndex >= 0) return values.slice(commandIndex)
+    if (commandIndex >= 0) return commandArgv(values, commandIndex)
   }
   return Bun.argv.slice(2)
 }

package/src/client-module.ts

@@ -0,0 +1,61 @@
+/**
+ * An app's `clientModule` when its config names a first-party file. The browser bundle's generated
+ * entry imports it, so the build classifies that file, and everything it imports, as browser code.
+ */
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import { CONFIG_FILE, FRAMEWORK_FILE } from "./app-files.ts"
+import { stripComments } from "./check-scan.ts"
+import type { SpecifierResolver } from "./internal/project-specifiers.ts"
+
+const CLIENT_MODULE_EXPORT =
+  /\bexport\s+const\s+clientModule\s*(?::\s*string\s*)?=\s*(?:"([^"\\\r\n]*)"|'([^'\\\r\n]*)')/
+
+export interface ClientModuleRoot {
+  /** The project-relative config file that names it. */
+  readonly config: string
+  readonly line: number
+  readonly specifier: string
+  /** The real path of the file it names. */
+  readonly file: string
+}
+
+/** The project-relative directory of every app among `files`: one holding a nifra config. */
+export function appDirs(files: readonly string[]): string[] {
+  const apps = new Set<string>()
+  for (const file of files) {
+    for (const config of [CONFIG_FILE, FRAMEWORK_FILE]) {
+      if (file === config) apps.add("")
+      else if (file.endsWith(`/${config}`)) apps.add(file.slice(0, -config.length - 1))
+    }
+  }
+  return [...apps]
+}
+
+/**
+ * The file `clientModule` names in `app`, read the way the loader reads it: from `nifra.config.ts`
+ * when it exists, else `backend/framework.ts`, and a relative path against the app root. `undefined`
+ * for a package specifier, a value that is not a string literal, or a path to no file.
+ */
+export function clientModuleRoot(
+  root: string,
+  app: string,
+  resolve: SpecifierResolver,
+): ClientModuleRoot | undefined {
+  const config = existsSync(join(root, app, CONFIG_FILE)) ? CONFIG_FILE : FRAMEWORK_FILE
+  const path = join(root, app, config)
+  if (!existsSync(path)) return undefined
+  const text = readFileSync(path, "utf8")
+  // `stripComments` keeps offsets, so the match index is a position in `text`.
+  const match = CLIENT_MODULE_EXPORT.exec(stripComments(text))
+  if (match === null) return undefined
+  const specifier = match[1] ?? match[2] ?? ""
+  const file = resolve(join(root, app, CONFIG_FILE), specifier)
+  if (file === undefined) return undefined
+  return {
+    config: app === "" ? config : `${app}/${config}`,
+    line: text.slice(0, match.index).split("\n").length,
+    specifier,
+    file,
+  }
+}

package/src/command-catalog.ts

@@ -22,9 +22,10 @@ import { type Diagnostic, diagnostic, normalizeSeverity, toSarifLog } from "./di
 import type { DoctorResult } from "./doctor.ts"
 import { type I18nCheckOutput, i18nCheckPassed, renderI18nCheck } from "./i18n-check.ts"
 import type { VerificationLevelsResult } from "./levels-tool.ts"
-import type { LoadedApp } from "./load.ts"
+import type { AppLoader, IntrospectedApp } from "./load.ts"
 import type { ManifestEmitCommandResult } from "./manifest-tool.ts"
 import type { LayoutMigrationResult } from "./migrate-layout.ts"
+import type { OutputSchemaStatus, OutputSchemasReport } from "./output-schemas.ts"
 import { collectPortResult, type PortResult, renderReport } from "./port.ts"
 import type { ReplayResult } from "./replay.ts"
 import { reviewSpec } from "./review.ts"
@@ -80,8 +81,8 @@ export interface CommandCtx {
   readonly signal?: AbortSignal
   readonly progress?: (message: string) => void
   readonly cliVersion?: string
-  /** Adapter-provided cache for commands that need the loaded web app. */
-  readonly loadApp?: () => Promise<LoadedApp>
+  /** Adapter-provided cache for commands that need the loaded app. */
+  readonly loadApp?: AppLoader
 }
 
 export interface CommandSpec<Input, Output> {
@@ -328,6 +329,8 @@ interface RoutesInput {
   readonly json?: boolean | undefined
   readonly graph?: boolean | undefined
   readonly modes?: boolean | undefined
+  readonly hooks?: boolean | undefined
+  readonly since?: string | undefined
   readonly target?: string | undefined
   readonly dir?: string | undefined
 }
@@ -390,6 +393,12 @@ interface TypesInput {
   readonly dir?: string | undefined
 }
 
+interface SchemasInput {
+  readonly write?: boolean | undefined
+  readonly json?: boolean | undefined
+  readonly dir?: string | undefined
+}
+
 interface SnapshotInput {
   readonly out?: string | undefined
   readonly json?: boolean | undefined
@@ -458,7 +467,7 @@ interface AssureCommandOutput {
 interface LevelsCommandOutput extends VerificationLevelsResult {}
 interface RoutesCommandOutput {
   readonly ok: boolean
-  readonly mode: "default" | "graph" | "modes"
+  readonly mode: "default" | "graph" | "modes" | "hooks"
   readonly data: unknown
   readonly text: string
 }
@@ -493,6 +502,9 @@ interface DiffCommandOutput {
   readonly hasBreaking: boolean
   readonly changes: readonly unknown[]
 }
+interface RouteDiffCommandOutput extends DiffCommandOutput {
+  readonly text: string
+}
 interface ContractsCommandOutput {
   readonly ok: boolean
   readonly lock?: ContractsLock
@@ -647,15 +659,20 @@ const ROUTES_SCHEMA = input<RoutesInput>(
     json: { type: "boolean" },
     graph: { type: "boolean" },
     modes: { type: "boolean" },
+    hooks: { type: "boolean" },
+    since: { type: "string" },
     target: { type: "string" },
     dir: { type: "string" },
   }),
   (value) => {
     const raw = withDir(record(value))
-    if (raw.graph === true && raw.modes === true)
-      throw new TypeError("graph and modes cannot be combined")
+    if ([raw.graph, raw.modes, raw.hooks].filter((flag) => flag === true).length > 1)
+      throw new TypeError("graph, modes and hooks cannot be combined")
+    if (raw.since !== undefined && raw.hooks !== true)
+      throw new TypeError("since compares hook reports and needs hooks")
     return {
-      ...parseBooleanFlags(raw, ["json", "graph", "modes"]),
+      ...parseBooleanFlags(raw, ["json", "graph", "modes", "hooks"]),
+      since: optionalString(raw.since, "since"),
       target: optionalString(raw.target, "target"),
       ...(raw.dir === undefined ? {} : { dir: raw.dir }),
     }
@@ -781,6 +798,17 @@ const TYPES_SCHEMA = input<TypesInput>(
   },
 )
 
+const SCHEMAS_SCHEMA = input<SchemasInput>(
+  objectSchema({ write: { type: "boolean" }, json: { type: "boolean" }, dir: { type: "string" } }),
+  (value) => {
+    const raw = withDir(record(value))
+    return {
+      ...parseBooleanFlags(raw, ["write", "json"]),
+      ...(raw.dir === undefined ? {} : { dir: raw.dir }),
+    }
+  },
+)
+
 const SNAPSHOT_SCHEMA = input<SnapshotInput>(
   objectSchema({ out: { type: "string" }, json: { type: "boolean" }, dir: { type: "string" } }),
   (value) => {
@@ -944,9 +972,10 @@ const I18N_SCHEMA = input<I18nInput>(
   },
 )
 
-function loadAppFor(ctx: CommandCtx): Promise<LoadedApp> {
-  if (ctx.loadApp !== undefined) return ctx.loadApp()
-  return import("./load.ts").then(({ loadApp }) => loadApp(ctx.cwd))
+/** The app as the backend readers see it: an API-only app is its `backend/app.ts` alone. */
+function backendAppFor(ctx: CommandCtx): Promise<IntrospectedApp> {
+  if (ctx.loadApp !== undefined) return ctx.loadApp.backend()
+  return import("./load.ts").then(({ loadBackendApp }) => loadBackendApp(ctx.cwd))
 }
 
 function structuredDiagnostics(out: CheckCommandOutput): readonly Diagnostic[] {
@@ -1195,7 +1224,8 @@ const manifestSpec: CommandSpec<ManifestInput, ManifestEmitCommandResult | DiffC
 
 const routesSpec: CommandSpec<RoutesInput, RoutesCommandOutput> = {
   name: "routes",
-  summary: "List, graph, or target-check every page and API route the app serves.",
+  summary:
+    "List, graph, or target-check every page and API route the app serves, or the hooks each runs.",
   input: ROUTES_SCHEMA,
   output: output({
     type: "object",
@@ -1209,12 +1239,47 @@ const routesSpec: CommandSpec<RoutesInput, RoutesCommandOutput> = {
       { name: "json", field: "json", type: "boolean" },
       { name: "graph", field: "graph", type: "boolean" },
       { name: "modes", field: "modes", type: "boolean" },
+      { name: "hooks", field: "hooks", type: "boolean" },
+      { name: "since", field: "since", type: "string" },
       { name: "target", field: "target", type: "string" },
     ],
   },
   async run(value, ctx) {
-    const app = await loadAppFor(ctx)
+    if (value.hooks === true) {
+      const app = await backendAppFor(ctx)
+      const hooks = await import("./hooks-report.ts")
+      const report = await hooks.collectHookReport(app.backend)
+      if (value.since === undefined) {
+        return { ok: true, mode: "hooks", data: report, text: hooks.renderHookReport(report) }
+      }
+      const saved = hooks.parseHookReport(
+        await Bun.file(resolve(ctx.cwd, value.since))
+          .text()
+          .catch(() => ""),
+      )
+      if (saved === undefined) {
+        return {
+          ok: false,
+          mode: "hooks",
+          data: { report, error: `${value.since} is not a saved hook report` },
+          text: `[nifra] ${value.since} is not a saved hook report (write one with \`nifra routes --hooks --json\`)`,
+        }
+      }
+      const changes = hooks.diffHookReports(saved, report)
+      return {
+        ok: true,
+        mode: "hooks",
+        data: { report, changes },
+        text: hooks.renderHookDiff(changes),
+      }
+    }
+    const app = await backendAppFor(ctx)
     if (value.modes === true) {
+      if (app.framework === undefined) {
+        throw new Error(
+          `[nifra] routes --modes reads page routes, and ${ctx.cwd} is an API-only app (backend/app.ts, no web config)`,
+        )
+      }
       const { buildRouteManifest, renderRouteManifest } = await import(
         "@nifrajs/web/route-manifest"
       )
@@ -1264,7 +1329,7 @@ const contextSpec: CommandSpec<ContextInput, ContextCommandOutput> = {
   async run(value, ctx) {
     return {
       ok: true,
-      text: (await import("./introspect.ts")).describeProject(await loadAppFor(ctx), {
+      text: (await import("./introspect.ts")).describeProject(await backendAppFor(ctx), {
         ...(value.path === undefined ? {} : { path: value.path }),
         ...(value.kind === undefined ? {} : { kind: value.kind }),
       }),
@@ -1292,10 +1357,7 @@ const openApiSpec: CommandSpec<OpenApiInput, OpenApiCommandOutput> = {
     ],
   },
   async run(value, ctx) {
-    const app =
-      ctx.loadApp !== undefined
-        ? await ctx.loadApp()
-        : await import("./load.ts").then(({ loadBackendApp }) => loadBackendApp(ctx.cwd))
+    const app = await backendAppFor(ctx)
     const { renderOpenApiWithTypes } = await import("./openapi-tool.ts")
     const format = value.format ?? "json"
     return {
@@ -1430,6 +1492,8 @@ const migrateSpec: CommandSpec<MigrateInput, MigrateCommandOutput> = {
       splits: { type: "array" },
       moves: { type: "array" },
       rewritten: { type: "array" },
+      tooling: { type: "array" },
+      mode: { type: "string" },
     },
     required: ["ok", "write", "issues"],
   }),
@@ -1459,13 +1523,14 @@ const migrateSpec: CommandSpec<MigrateInput, MigrateCommandOutput> = {
     if (out.kind === "layout") {
       return [
         out.ok
-          ? `✓ ${out.splits.length} route file${out.splits.length === 1 ? "" : "s"} split, ${out.moves.length} file${out.moves.length === 1 ? "" : "s"} moved`
+          ? `✓ ${out.mode === "api" ? "API-only app" : `${out.splits.length} route file${out.splits.length === 1 ? "" : "s"} split`}, ${out.moves.length} file${out.moves.length === 1 ? "" : "s"} moved`
           : `⚠ ${out.issues.length} issue${out.issues.length === 1 ? "" : "s"} need a decision; everything else is planned`,
         ...out.splits.map(
           (split) => `  split ${split.file} → ${split.backend} (${split.moved.join(", ")})`,
         ),
         ...out.moves.map((move) => `  move  ${move.from} → ${move.to}`),
         ...out.rewritten.map((file) => `  edit  ${file} (imports)`),
+        ...out.tooling.map((edit) => `  edit  ${edit.file} (${edit.change})`),
         ...out.issues.map((issue) => `  ⚠ ${issue.file}: ${issue.reason}`),
         ...(out.write ? [] : ["  dry run: pass --write to apply"]),
       ]
@@ -1586,6 +1651,75 @@ const typesSpec: CommandSpec<TypesInput, RouteTypesReport> = {
   success: (out) => out.ok,
 }
 
+const SCHEMA_STATUS_LINE: Readonly<Record<OutputSchemaStatus, string>> = {
+  missing: "+ would write",
+  generated: "+ wrote",
+  stale: "↻ stale",
+  regenerated: "↻ rewrote",
+  current: "✓ current",
+  declared: "· hand-written",
+  "no-data": "· no data",
+  unreadable: "⚠ unreadable",
+}
+
+const schemasSpec: CommandSpec<SchemasInput, OutputSchemasReport> = {
+  name: "schemas",
+  summary:
+    "Write a reviewable `loaderOutput`/`actionOutput` from the loader's or action's return type where a route has none (`--write`), keep generated ones current, and list returned fields a hand-written schema drops.",
+  input: SCHEMAS_SCHEMA,
+  output: output({
+    type: "object",
+    properties: {
+      ok: { type: "boolean" },
+      write: { type: "boolean" },
+      entries: { type: "array" },
+      written: { type: "array" },
+      warnings: { type: "array" },
+    },
+    required: ["ok", "write", "entries", "written", "warnings"],
+  }),
+  transports: ["cli"],
+  stability: "stable",
+  argv: {
+    flags: [
+      { name: "write", field: "write", type: "boolean" },
+      { name: "json", field: "json", type: "boolean" },
+      { name: "dir", field: "dir", type: "string" },
+    ],
+  },
+  async run(value, ctx) {
+    const { outputSchemas } = await import("./output-schemas.ts")
+    return outputSchemas(resolve(ctx.cwd, value.dir ?? "."), { write: value.write === true })
+  },
+  render: (out) => {
+    const shown = out.entries.filter(
+      (entry) =>
+        entry.status !== "current" &&
+        entry.status !== "no-data" &&
+        (entry.status !== "declared" || entry.dropped.length > 0),
+    )
+    const current = out.entries.filter((entry) => entry.status === "current").length
+    return [
+      ...out.warnings.map((warning) => `⚠ ${warning}`),
+      `${out.ok ? "✓" : "✖"} ${out.entries.length} output schema${out.entries.length === 1 ? "" : "s"} read, ${current} generated and current`,
+      ...shown.map((entry) => {
+        const detail =
+          entry.reason ??
+          (entry.edited === true
+            ? "edited by hand under its nifra:generated line"
+            : entry.dropped.length > 0
+              ? `drops ${entry.dropped.join(", ")}`
+              : undefined)
+        return `  ${SCHEMA_STATUS_LINE[entry.status]} ${entry.file}:${entry.line} ${entry.schema}${detail === undefined ? "" : ` - ${detail}`}`
+      }),
+      ...(out.write || !out.entries.some((e) => e.status === "missing" || e.status === "stale")
+        ? []
+        : ["  dry run: pass --write to apply"]),
+    ]
+  },
+  success: (out) => out.ok,
+}
+
 const snapshotSpec: CommandSpec<SnapshotInput, SnapshotCommandOutput> = {
   name: "snapshot",
   summary: "Write the backend API contract as a versioned JSON baseline.",
@@ -1610,18 +1744,16 @@ const snapshotSpec: CommandSpec<SnapshotInput, SnapshotCommandOutput> = {
   },
   async run(value, ctx) {
     const mod = await import("./diff-tool.ts")
-    const routes = await mod.snapshotBackend(ctx.cwd)
     const file = value.out ?? mod.DEFAULT_SNAPSHOT_FILE
-    const snapshot = { nifraSnapshot: 1 as const, routes }
-    await Bun.write(resolve(ctx.cwd, file), `${JSON.stringify(snapshot, null, 2)}\n`)
-    return { ok: true, file, routes: routes.length, snapshot }
+    const snapshot = await mod.writeSnapshot(ctx.cwd, file)
+    return { ok: true, file, routes: snapshot.routes.length, snapshot }
   },
   render: (out) => [
     `[nifra] wrote ${out.routes} route${out.routes === 1 ? "" : "s"} to ${out.file}`,
   ],
 }
 
-const diffSpec: CommandSpec<DiffInput, DiffCommandOutput> = {
+const diffSpec: CommandSpec<DiffInput, RouteDiffCommandOutput> = {
   name: "diff",
   summary: "Compare the current backend contract with a baseline and fail on breaking changes.",
   input: DIFF_SCHEMA,
@@ -1638,21 +1770,17 @@ const diffSpec: CommandSpec<DiffInput, DiffCommandOutput> = {
   stability: "stable",
   argv: { positionals: ["baseline"], flags: [{ name: "json", field: "json", type: "boolean" }] },
   async run(value, ctx) {
-    const mod = await import("./diff-tool.ts")
-    const baseline = value.baseline ?? mod.DEFAULT_SNAPSHOT_FILE
-    const file = await Bun.file(resolve(ctx.cwd, baseline)).text()
-    const before = mod.parseSnapshotFile(file, baseline)
-    const current = await mod.snapshotBackend(ctx.cwd)
-    const { diffRouteSnapshots } = await import("@nifrajs/core/diff")
-    const diff = diffRouteSnapshots(before.routes, current)
-    return { ok: !diff.hasBreaking, hasBreaking: diff.hasBreaking, changes: diff.changes }
+    const { diffAgainstBaseline, formatDiff } = await import("./diff-tool.ts")
+    const diff = await diffAgainstBaseline(ctx.cwd, value.baseline)
+    return {
+      ok: !diff.hasBreaking,
+      hasBreaking: diff.hasBreaking,
+      changes: diff.changes,
+      text: formatDiff(diff),
+    }
   },
-  render: (out) => [
-    out.ok ? "✓ no breaking changes" : "✖ breaking changes",
-    ...(out.changes as readonly { method: string; path: string; message: string }[]).map(
-      (c) => `${c.method} ${c.path}: ${c.message}`,
-    ),
-  ],
+  render: (out) => [out.text],
+  json: ({ ok, hasBreaking, changes }) => ({ ok, hasBreaking, changes }),
   success: (out) => out.ok,
 }
 
@@ -1880,6 +2008,7 @@ export const commandSpecs = Object.freeze([
   migrateSpec,
   targetSpec,
   typesSpec,
+  schemasSpec,
   snapshotSpec,
   diffSpec,
   contractsSpec,