@nifrajs/cli 5.0.0 → 5.1.0

package/src/cli.ts

@@ -126,6 +126,9 @@ Usage:
                                          one left. Exits 1 while current-code errors are open.
   nifra logs    [--since <n>] [--level <l>] [--grep <s>]  The dev server's console, server and
                                          browser, each line tagged with its request.
+  nifra explain [<message>] [--stack <s>] [--name <n>]  A structured diagnostic for an error: its
+                                         code, the frame in your source, and the cause and fix when
+                                         nifra knows them. No message: the dev server's latest error.
   nifra cdn-check <url>                  Check a deployed page behind a CDN: served from cache, no
                                          internal or CDN-only headers reaching the visitor, and soft
                                          navigations get page data, not the cached document. Exits 1
@@ -273,20 +276,23 @@ Usage:
                                          this CLI prints the command for that release's CLI. Fail-closed
                                          on an unknown version or a rollback (--allow-downgrade
                                          overrides). Deterministic + idempotent.
-  nifra migrate layout [--write] [--json]
+  nifra migrate layout [--write] [--zones] [--json]
                                          Move an app onto the frontend/backend split: split each route
                                          into x.tsx + x.backend.ts, fold _middleware.ts into
                                          _layout.backend.ts, move backend.ts/framework.ts under backend/,
-                                         and zone the other modules into frontend/, backend/ or shared/.
-                                         Dry-run by default; --write applies.
+                                         and zone the other modules into frontend/, backend/ or shared/
+                                         (--zones keeps them in place and lists them in package.json
+                                         "nifra.zones"). Dry-run by default; --write applies.
   nifra types   [--check] [--json]       Generate each route's ./+types module under .nifra/types: its
                                          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
+  nifra schemas [--write] [--check] [--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.
+                                         Lists the returned fields a hand-written schema drops;
+                                         --check fails on a missing, stale or any-typed one.
   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-
@@ -315,7 +321,7 @@ 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 = "5.0.0"
+const CLI_VERSION = "5.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
@@ -366,6 +372,14 @@ export function formatCliError(err: unknown): string {
   return String(err)
 }
 
+/** A failed command's message on stderr and, for a `--json` caller parsing stdout, as JSON there. */
+function reportFailure(err: unknown, argv: readonly string[]): void {
+  const message = formatCliError(err)
+  console.error(message)
+  if (argv.includes("--json") || argv.includes("--json=true"))
+    console.log(JSON.stringify({ ok: false, error: message }, null, 2))
+}
+
 async function dev(app: LoadedApp, flags: Flags): Promise<void> {
   if (app.framework.componentPipeline !== undefined) {
     if (flags.bun)
@@ -954,35 +968,73 @@ async function start(app: LoadedApp, flags: Flags): Promise<void> {
   await import(serverFile)
 }
 
+const VALUE_FLAGS: Readonly<Record<string, "port" | "out" | "target">> = {
+  "--port": "port",
+  "-p": "port",
+  "--out": "out",
+  "--target": "target",
+}
+
+type SwitchField = "poll" | "report" | "vite" | "bun" | "allowDuplicateIdentity" | "noIndicator"
+
+const SWITCH_FLAGS: Readonly<Record<string, SwitchField>> = {
+  "--poll": "poll",
+  "--report": "report",
+  "--vite": "vite",
+  "--bun": "bun",
+  "--allow-duplicate-identity": "allowDuplicateIdentity",
+  "--no-indicator": "noIndicator",
+}
+
+/** The flags of `nifra dev`, `build` and `start`, as `--flag value` or `--flag=value`. Anything else is
+ * refused: an ignored `--target=vercel` would build the default target and exit 0. */
 export function parseFlags(args: readonly string[]): Flags {
   // Port precedence: `--port`/`-p` (most specific) > `PORT` env > the framework default. The default is
   // the SAME uncommon port for `nifra dev` and `nifra start` (DEFAULT_DEV_PORT) so a project's URL is
   // stable across commands and doesn't collide with the usual 3000/5173/8080 crowd.
   let port = Number(Bun.env.PORT ?? DEFAULT_DEV_PORT)
   let out: string | undefined
-  let poll = Bun.env.CHOKIDAR_USEPOLLING === "1"
   let target: string | undefined
-  let report = false
-  let vite = false
-  let bun = false
-  let allowDuplicateIdentity = false
-  let noIndicator = false
+  const switches: Record<SwitchField, boolean> = {
+    poll: Bun.env.CHOKIDAR_USEPOLLING === "1",
+    report: false,
+    vite: false,
+    bun: false,
+    allowDuplicateIdentity: false,
+    noIndicator: false,
+  }
   for (let i = 0; i < args.length; i++) {
-    const a = args[i]
-    if ((a === "--port" || a === "-p") && args[i + 1]) port = Number(args[++i])
-    else if (a === "--out" && args[i + 1]) out = args[++i] as string
-    else if (a === "--poll") poll = true
-    else if (a === "--target" && args[i + 1]) target = args[++i] as string
-    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
-    else if (a === "--no-indicator") noIndicator = true
+    const arg = args[i] as string
+    const equals = arg.startsWith("--") ? arg.indexOf("=") : -1
+    const name = equals === -1 ? arg : arg.slice(0, equals)
+    const valueField = Object.hasOwn(VALUE_FLAGS, name) ? VALUE_FLAGS[name] : undefined
+    if (valueField !== undefined) {
+      const value = equals === -1 ? args[++i] : arg.slice(equals + 1)
+      if (value === undefined || value === "" || (equals === -1 && value.startsWith("-")))
+        throw new Error(`[nifra] ${name} needs a value`)
+      if (valueField === "port") port = Number(value)
+      else if (valueField === "out") out = value
+      else target = value
+      continue
+    }
+    const switchField = Object.hasOwn(SWITCH_FLAGS, name) ? SWITCH_FLAGS[name] : undefined
+    if (switchField !== undefined) {
+      const value = equals === -1 ? "true" : arg.slice(equals + 1)
+      if (value !== "true" && value !== "false")
+        throw new Error(`[nifra] ${name} takes no value (or =true / =false)`)
+      switches[switchField] = value === "true"
+      continue
+    }
+    throw new Error(
+      arg.startsWith("-")
+        ? `[nifra] unknown option: ${arg} - see \`nifra help\``
+        : `[nifra] unexpected argument: ${arg} - see \`nifra help\``,
+    )
   }
   if (!Number.isFinite(port) || port < 0 || port > 65535) {
     throw new Error(`[nifra] invalid --port: ${port}`)
   }
-  return { port, out, poll, target, report, vite, bun, allowDuplicateIdentity, noIndicator }
+  return { port, out, target, ...switches }
 }
 
 /**
@@ -1190,7 +1242,7 @@ async function main(): Promise<void> {
       // 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))
+      reportFailure(err, argv)
       const candidate =
         typeof err === "object" && err !== null && "exitCode" in err
           ? (err as { readonly exitCode?: unknown }).exitCode
@@ -1253,6 +1305,7 @@ async function main(): Promise<void> {
       console.error(formatCliError(err))
       process.exitCode = 1
     }
+    exitIfHeldOpen(command)
     return
   }
   // `upgrade` is a pure cwd file-transformer (package.json pins + import moves) driven by a per-release
@@ -1275,9 +1328,10 @@ async function main(): Promise<void> {
       })
       if (!ok) process.exitCode = 1
     } catch (err) {
-      console.error(formatCliError(err))
+      reportFailure(err, argv)
       process.exitCode = 1
     }
+    exitIfHeldOpen(command)
     return
   }
   // `port` is a pure cwd-based portability linter (scans source, doesn't run the app) - like `check`/
@@ -1288,17 +1342,32 @@ async function main(): Promise<void> {
     process.exitCode = 1
     return
   }
+  if (argv.includes("--help") || argv.includes("-h")) {
+    console.log(HELP)
+    return
+  }
   const flags = parseFlags(argv.slice(1))
-  const app = await loadApp(process.cwd(), flags.out)
-  if (command !== "start") {
-    const { refreshRouteTypes, watchRouteTypes } = await import("./route-types.ts")
-    refreshRouteTypes(app.cwd)
-    // A relaunched `nifra dev --bun` child runs beside its parent, which already watches.
-    if (command === "dev" && process.env.NIFRA_BUN_DEV_TOKEN === undefined) watchRouteTypes(app.cwd)
+  try {
+    const app = await loadApp(process.cwd(), flags.out)
+    if (command !== "start" && process.env.NIFRA_BUN_DEV_TOKEN === undefined) {
+      const { unservedRoutesWarning } = await import("./introspect.ts")
+      const unserved = unservedRoutesWarning(app)
+      if (unserved !== undefined) console.warn(unserved)
+    }
+    if (command !== "start") {
+      const { refreshRouteTypes, watchRouteTypes } = await import("./route-types.ts")
+      refreshRouteTypes(app.cwd)
+      // A relaunched `nifra dev --bun` child runs beside its parent, which already watches.
+      if (command === "dev" && process.env.NIFRA_BUN_DEV_TOKEN === undefined)
+        watchRouteTypes(app.cwd)
+    }
+    if (command === "dev") await dev(app, flags)
+    else if (command === "build") await buildForTarget(app, flags.target, flags)
+    else await start(app, flags)
+  } finally {
+    // `dev` and `start` keep serving after they return; a build is over.
+    if (command === "build") exitIfHeldOpen(command)
   }
-  if (command === "dev") await dev(app, flags)
-  else if (command === "build") await buildForTarget(app, flags.target, flags)
-  else await start(app, flags)
 }
 
 /**
@@ -1485,7 +1554,7 @@ if (isMainModule() || isBunDevReexecChild() || hasCliCommandToken()) {
   try {
     await main()
   } catch (err) {
-    console.error(formatCliError(err))
+    reportFailure(err, cliArgv())
     process.exitCode = 1
   }
 }

package/src/client-module.ts

@@ -4,8 +4,10 @@
  */
 import { existsSync, readFileSync } from "node:fs"
 import { join } from "node:path"
+import type * as TS from "typescript"
 import { CONFIG_FILE, FRAMEWORK_FILE } from "./app-files.ts"
 import { stripComments } from "./check-scan.ts"
+import { configPathReader, exportedInitializer } from "./internal/config-paths.ts"
 import type { SpecifierResolver } from "./internal/project-specifiers.ts"
 
 const CLIENT_MODULE_EXPORT =
@@ -34,28 +36,62 @@ export function appDirs(files: readonly string[]): string[] {
 
 /**
  * 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.
+ * when it exists, else `backend/framework.ts`; a string against the app root, and, with `ts`, a
+ * `resolve`/`join` of the config's own folder against that folder. `undefined` for a package
+ * specifier, a value built any other way, or a path to no file.
  */
 export function clientModuleRoot(
   root: string,
   app: string,
   resolve: SpecifierResolver,
+  ts?: typeof TS,
 ): 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)
+  const found = ts === undefined ? literalClientModule(text) : staticClientModule(ts, path, text)
+  if (found === undefined) return undefined
+  const file =
+    found.base === "app"
+      ? resolve(join(root, app, CONFIG_FILE), found.specifier)
+      : resolve(path, found.specifier.startsWith("../") ? found.specifier : `./${found.specifier}`)
   if (file === undefined) return undefined
   return {
     config: app === "" ? config : `${app}/${config}`,
-    line: text.slice(0, match.index).split("\n").length,
-    specifier,
+    line: text.slice(0, found.index).split("\n").length,
+    specifier: found.specifier,
     file,
   }
 }
+
+interface FoundClientModule {
+  readonly base: "app" | "config"
+  readonly specifier: string
+  readonly index: number
+}
+
+function literalClientModule(text: string): FoundClientModule | undefined {
+  // `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
+  return { base: "app", specifier: match[1] ?? match[2] ?? "", index: match.index }
+}
+
+function staticClientModule(
+  ts: typeof TS,
+  path: string,
+  text: string,
+): FoundClientModule | undefined {
+  let sf: TS.SourceFile
+  try {
+    sf = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+  } catch {
+    // TypeScript 7 parses only what its session preloaded; the literal form still reads.
+    return literalClientModule(text)
+  }
+  const initializer = exportedInitializer(ts, sf, "clientModule")
+  const found = configPathReader(ts, sf)(initializer)
+  if (initializer === undefined || found === undefined) return undefined
+  return { base: found.base, specifier: found.path, index: initializer.getStart(sf) }
+}

package/src/command-catalog.ts

@@ -17,7 +17,7 @@ import { cdnCheckSpec } from "./cdn-check.ts"
 import { type CheckResult, renderCheckReport } from "./check.ts"
 import type { ContractsLock } from "./contracts.ts"
 import { dbAuditSpec, dbQuerySpec, dbRoleSpec, dbSchemaSpec } from "./db-tool.ts"
-import { errorsSpec, logsSpec } from "./dev-feed-tool.ts"
+import { errorsSpec, explainSpec, logsSpec } from "./dev-feed-tool.ts"
 import { type Diagnostic, diagnostic, normalizeSeverity, toSarifLog } from "./diagnostics.ts"
 import type { DoctorResult } from "./doctor.ts"
 import { type I18nCheckOutput, i18nCheckPassed, renderI18nCheck } from "./i18n-check.ts"
@@ -367,6 +367,8 @@ interface MigrateInput {
   readonly from?: "tailwind" | undefined
   readonly to?: "stylex" | undefined
   readonly write?: boolean | undefined
+  /** `migrate layout`: list the folders modules would leave in package.json zones instead. */
+  readonly zones?: boolean | undefined
   readonly json?: boolean | undefined
   readonly dir?: string | undefined
 }
@@ -395,6 +397,7 @@ interface TypesInput {
 
 interface SchemasInput {
   readonly write?: boolean | undefined
+  readonly check?: boolean | undefined
   readonly json?: boolean | undefined
   readonly dir?: string | undefined
 }
@@ -486,6 +489,8 @@ interface FixCommandOutput {
   /** Recipes that refused, with the reason. A recipe that cannot act says so here instead of
    * aborting the run or - worse - reporting nothing at all. */
   readonly failed: readonly { readonly code: string; readonly reason: string }[]
+  /** Findings whose recipe runs only when its code is named, because its change needs review. */
+  readonly skipped: readonly { readonly code: string; readonly reason: string }[]
   readonly diagnostics: readonly unknown[]
 }
 type MigrateCommandOutput =
@@ -751,13 +756,14 @@ const MIGRATE_SCHEMA = input<MigrateInput>(
     from: { type: "string", enum: ["tailwind"] },
     to: { type: "string", enum: ["stylex"] },
     write: { type: "boolean" },
+    zones: { type: "boolean" },
     json: { type: "boolean" },
     dir: { type: "string" },
   }),
   (value) => {
     const raw = withDir(record(value))
     const flags = {
-      ...parseBooleanFlags(raw, ["write", "json"]),
+      ...parseBooleanFlags(raw, ["write", "zones", "json"]),
       ...(raw.dir === undefined ? {} : { dir: raw.dir }),
     }
     const kind = optionalString(raw.kind, "kind")
@@ -766,6 +772,7 @@ const MIGRATE_SCHEMA = input<MigrateInput>(
         throw new TypeError("the migration must be `layout` (or --from tailwind --to stylex)")
       return { kind, ...flags }
     }
+    if (raw.zones === true) throw new TypeError("--zones applies to `migrate layout` only")
     const from = optionalString(raw.from, "from")
     const to = optionalString(raw.to, "to")
     if (from !== "tailwind") throw new TypeError("from must be tailwind")
@@ -799,11 +806,16 @@ const TYPES_SCHEMA = input<TypesInput>(
 )
 
 const SCHEMAS_SCHEMA = input<SchemasInput>(
-  objectSchema({ write: { type: "boolean" }, json: { type: "boolean" }, dir: { type: "string" } }),
+  objectSchema({
+    write: { type: "boolean" },
+    check: { type: "boolean" },
+    json: { type: "boolean" },
+    dir: { type: "string" },
+  }),
   (value) => {
     const raw = withDir(record(value))
     return {
-      ...parseBooleanFlags(raw, ["write", "json"]),
+      ...parseBooleanFlags(raw, ["write", "check", "json"]),
       ...(raw.dir === undefined ? {} : { dir: raw.dir }),
     }
   },
@@ -1418,6 +1430,7 @@ const fixSpec: CommandSpec<FixInput, FixCommandOutput> = {
       ok: { type: "boolean" },
       changed: { type: "array" },
       failed: { type: "array" },
+      skipped: { type: "array" },
       diagnostics: { type: "array" },
     },
     required: ["ok", "diagnostics"],
@@ -1432,25 +1445,37 @@ const fixSpec: CommandSpec<FixInput, FixCommandOutput> = {
   },
   async run(value, ctx) {
     const { collectCheckResult } = await import("./check.ts")
-    const { applyDiagnosticRecipe } = await import("./fix-recipes.ts")
+    const { applyDiagnosticRecipe, getFixRecipe } = await import("./fix-recipes.ts")
     const result = await collectCheckResult(ctx.cwd, {
       lintsOnly: true,
       ...(ctx.signal === undefined ? {} : { signal: ctx.signal }),
     })
     const changed: string[] = []
     const failed: { code: string; reason: string }[] = []
-    for (const diagnostic of result.structuredDiagnostics ?? [])
-      if (value.code === undefined || diagnostic.code === value.code)
-        // One recipe that cannot act must not cancel the others, and must not pass silently either:
-        // record why and keep going, so a run over many diagnostics still reports every outcome.
-        try {
-          changed.push(...(await applyDiagnosticRecipe(ctx.cwd, diagnostic)))
-        } catch (error) {
-          failed.push({
+    const skipped: { code: string; reason: string }[] = []
+    for (const diagnostic of result.structuredDiagnostics ?? []) {
+      if (value.code !== undefined && diagnostic.code !== value.code) continue
+      const recipe =
+        diagnostic.fix?.recipe === undefined ? undefined : getFixRecipe(diagnostic.fix.recipe)
+      if (value.code === undefined && recipe?.onlyWhenNamed === true) {
+        if (!skipped.some((entry) => entry.code === diagnostic.code))
+          skipped.push({
             code: diagnostic.code,
-            reason: error instanceof Error ? error.message : String(error),
+            reason: `${recipe.description} Review the finding, then run \`nifra fix --code ${diagnostic.code}\`.`,
           })
-        }
+        continue
+      }
+      // One recipe that cannot act must not cancel the others, and must not pass silently either:
+      // record why and keep going, so a run over many diagnostics still reports every outcome.
+      try {
+        changed.push(...(await applyDiagnosticRecipe(ctx.cwd, diagnostic)))
+      } catch (error) {
+        failed.push({
+          code: diagnostic.code,
+          reason: error instanceof Error ? error.message : String(error),
+        })
+      }
+    }
     const final = await collectCheckResult(ctx.cwd, {
       lintsOnly: true,
       ...(ctx.signal === undefined ? {} : { signal: ctx.signal }),
@@ -1459,6 +1484,7 @@ const fixSpec: CommandSpec<FixInput, FixCommandOutput> = {
       ok: final.ok,
       changed,
       failed,
+      skipped,
       diagnostics: final.structuredDiagnostics ?? final.diagnostics,
     }
   },
@@ -1466,6 +1492,7 @@ const fixSpec: CommandSpec<FixInput, FixCommandOutput> = {
     out.ok ? "✓ fixes applied" : "✖ unresolved diagnostics remain",
     ...out.changed.map((file) => `  changed ${file}`),
     ...out.failed.map((f) => `  could not fix ${f.code}: ${f.reason}`),
+    ...out.skipped.map((s) => `  needs review ${s.code}: ${s.reason}`),
     ...out.diagnostics.map((d) => `  ${String((d as { code?: unknown }).code ?? "diagnostic")}`),
   ],
   success: (out) => out.ok,
@@ -1493,6 +1520,7 @@ const migrateSpec: CommandSpec<MigrateInput, MigrateCommandOutput> = {
       moves: { type: "array" },
       rewritten: { type: "array" },
       tooling: { type: "array" },
+      followUps: { type: "array" },
       mode: { type: "string" },
     },
     required: ["ok", "write", "issues"],
@@ -1505,6 +1533,7 @@ const migrateSpec: CommandSpec<MigrateInput, MigrateCommandOutput> = {
       { name: "from", field: "from", type: "string" },
       { name: "to", field: "to", type: "string" },
       { name: "write", field: "write", type: "boolean" },
+      { name: "zones", field: "zones", type: "boolean" },
       { name: "json", field: "json", type: "boolean" },
       { name: "dir", field: "dir", type: "string" },
     ],
@@ -1514,7 +1543,8 @@ const migrateSpec: CommandSpec<MigrateInput, MigrateCommandOutput> = {
     const write = value.write === undefined ? {} : { write: value.write }
     if (value.kind === "layout") {
       const { migrateLayout } = await import("./migrate-layout.ts")
-      return { kind: "layout" as const, ...(await migrateLayout(dir, write)) }
+      const options = { ...write, zones: value.zones === true }
+      return { kind: "layout" as const, ...(await migrateLayout(dir, options)) }
     }
     const { migrateTailwindToStylex } = await import("./stylex-migrate.ts")
     return migrateTailwindToStylex(dir, write)
@@ -1526,12 +1556,22 @@ const migrateSpec: CommandSpec<MigrateInput, MigrateCommandOutput> = {
           ? `✓ ${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(", ")})`,
+          (split) =>
+            `  split ${split.file} → ${split.backend} (${split.moved.join(", ")})${split.shared === undefined ? "" : `, shared data → ${split.shared}`}`,
         ),
         ...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.schemas
+          .filter((entry) => entry.reason === undefined)
+          .map(
+            (entry) =>
+              `  draft ${entry.file} ${entry.schema} - review what it lets the browser see${entry.omitted === undefined ? "" : `; leaves out ${entry.omitted.join(", ")}`}${entry.open === undefined ? "" : `; admits any value at ${entry.open.join(", ")}, typed any or unknown`}`,
+          ),
         ...out.issues.map((issue) => `  ⚠ ${issue.file}: ${issue.reason}`),
+        ...out.followUps.map(
+          (step) => `  next  ${step.file}: ${step.reason} - \`${step.command}\``,
+        ),
         ...(out.write ? [] : ["  dry run: pass --write to apply"]),
       ]
     }
@@ -1683,18 +1723,22 @@ const schemasSpec: CommandSpec<SchemasInput, OutputSchemasReport> = {
   argv: {
     flags: [
       { name: "write", field: "write", type: "boolean" },
+      { name: "check", field: "check", 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 })
+    return outputSchemas(resolve(ctx.cwd, value.dir ?? "."), {
+      write: value.write === true,
+      check: value.check === true,
+    })
   },
   render: (out) => {
     const shown = out.entries.filter(
       (entry) =>
-        entry.status !== "current" &&
+        (entry.status !== "current" || entry.open !== undefined) &&
         entry.status !== "no-data" &&
         (entry.status !== "declared" || entry.dropped.length > 0),
     )
@@ -1709,8 +1753,19 @@ const schemasSpec: CommandSpec<SchemasInput, OutputSchemasReport> = {
             ? "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}`}`
+              : entry.omitted !== undefined
+                ? `leaves out ${entry.omitted.join(", ")}`
+                : undefined)
+        const open =
+          entry.open === undefined
+            ? []
+            : [
+                `      admits any value at ${entry.open.join(", ")}: the type there is any or unknown, so the output guard drops nothing below it`,
+              ]
+        return [
+          `  ${SCHEMA_STATUS_LINE[entry.status]} ${entry.file}:${entry.line} ${entry.schema}${detail === undefined ? "" : ` - ${detail}`}`,
+          ...open,
+        ].join("\n")
       }),
       ...(out.write || !out.entries.some((e) => e.status === "missing" || e.status === "stale")
         ? []
@@ -2020,6 +2075,7 @@ export const commandSpecs = Object.freeze([
   portSpec,
   i18nSpec,
   errorsSpec,
+  explainSpec,
   logsSpec,
   cdnCheckSpec,
   dbSchemaSpec,