@nifrajs/cli 1.6.0 → 1.12.0

package/src/check.ts

@@ -16,8 +16,8 @@
  * anything fails. Pure scanners (`scanFetchText`, `scanServerOnlyImports`) are unit-tested.
  */
 
-import { readFileSync } from "node:fs"
-import { dirname, isAbsolute, join } from "node:path"
+import { existsSync, readFileSync } from "node:fs"
+import { dirname, isAbsolute, join, resolve } from "node:path"
 import { Glob } from "bun"
 
 export interface SourceFinding {
@@ -195,8 +195,13 @@ function parseSimpleFetchCall(snippet: string): SimpleFetchCall | undefined {
   return { path, method, start: match.index, end: close + 1 }
 }
 
-function isPotentialNifraBackendSource(code: string): boolean {
-  return code.includes("@nifrajs/core") || /(?<![.\w])server\s*\(/.test(code)
+function isPotentialBackendSource(code: string): boolean {
+  return (
+    code.includes("@nifrajs/core") ||
+    /(?<![.\w])server\s*\(/.test(code) ||
+    /(?:from\s*|import\s*)["']hono["']/.test(code) ||
+    /new\s+Hono(?:<[^>]+>)?\s*\(/.test(code)
+  )
 }
 
 function scanRoutePattern(
@@ -289,7 +294,7 @@ export function scanFetchText(file: string, content: string): SourceFinding[] {
 /** Statically collect simple Nifra route registrations from source, without importing app code. */
 export function scanStaticRouteText(file: string, content: string): StaticRouteFinding[] {
   const code = stripComments(content)
-  if (!isPotentialNifraBackendSource(code)) return []
+  if (!isPotentialBackendSource(code)) return []
   return [
     ...scanRoutePattern(file, content, code, ROUTE_REGISTRATION_DQ),
     ...scanRoutePattern(file, content, code, ROUTE_REGISTRATION_SQ),
@@ -765,7 +770,11 @@ export interface CheckDiagnostic {
     | "server-only-import"
     | "response-route"
     | "undeclared-dependency"
+    | "duplicate-install"
     | "server-manifest-drift"
+    | "manifest-drift"
+    | "capability-assurance"
+    | "capability-config"
   /** `error` fails the gate (a real contract break); `warning` is advisory — surfaced to the agent but
    * does NOT fail `nifra check`, for patterns that are sometimes intentional (a route returning a raw
    * `Response`, which silently drops the typed client to `data: never` but is valid for files/redirects). */
@@ -826,6 +835,10 @@ const UNDECLARED_DEP_HINT =
   "imported package is not declared in package.json dependencies — run bun add to declare it"
 const MANIFEST_DRIFT_HINT =
   "server-manifest.ts is out of sync with routes/ — re-run the build to regenerate it (a disk-less worker bakes this route table, so the drift is a silent edge break), then commit it"
+const TRUST_MANIFEST_DRIFT_HINT =
+  "nifra.manifest.json is missing, invalid, or out of sync — run `nifra manifest emit`, review it, and commit the regenerated trust artifact"
+const CAPABILITY_HINT =
+  "effect/capability assurance failed — align the route declaration with approved adapter provenance; never bypass an owned effect seam"
 
 function oneLineDiff(file: string, line: number, before: string, after: string): string {
   return `--- ${file}:${line}\n+++ ${file}:${line}\n@@\n-${before}\n+${after}`
@@ -1127,6 +1140,24 @@ export async function collectCheckResult(
         },
       })
     }
+    for (const finding of dr.duplicateInstalls) {
+      const copies = finding.copies.map((copy) => `${copy.version} at ${copy.path}`).join("; ")
+      diagnostics.push({
+        rule: "duplicate-install",
+        severity: "error",
+        message: `${finding.package} resolves to multiple physical copies (${copies}) - module identity is unsafe`,
+        fix: "align dependency ranges and reinstall from the workspace root",
+        suggestion: {
+          kind: "manual",
+          title: `Deduplicate ${finding.package}`,
+          steps: [
+            "Align workspace dependency and peer ranges on one compatible version.",
+            "Remove stale nested installs and run the package manager from the workspace root.",
+            "Run `nifra doctor` again; do not suppress same-version duplicate paths.",
+          ],
+        },
+      })
+    }
   }
   // #7: a committed server-manifest.ts that drifted from routes/ — name the exact missing/extra routes.
   for (const f of manifestDrift) {
@@ -1150,19 +1181,127 @@ export async function collectCheckResult(
     })
   }
 
+  // G+B+D+F: when the project opts into capability assurance, `nifra check` becomes the static
+  // provenance firewall as well as the typed-contract gate. Loading is explicit/config-owned; projects
+  // without nifra.assurance.ts retain the historical scan and hot path unchanged.
+  const assuranceConfigPath = join(cwd, "nifra.assurance.ts")
+  if (existsSync(assuranceConfigPath)) {
+    try {
+      const { loadAssuranceConfig } = await import("./assure.ts")
+      const config = await loadAssuranceConfig(cwd)
+      let capabilityReport:
+        | Awaited<
+            ReturnType<typeof import("./capabilities-tool.ts")["collectCapabilityProjectReport"]>
+          >["report"]
+        | undefined
+      if (config.capabilities !== undefined) {
+        const { collectCapabilityProjectReport } = await import("./capabilities-tool.ts")
+        const project = await collectCapabilityProjectReport(
+          cwd,
+          config.source,
+          config.capabilities,
+        )
+        capabilityReport = project.report
+        for (const finding of project.report.findings) {
+          const violation =
+            finding.code === "forbidden-effect-import"
+              ? project.violations.find(
+                  (candidate) =>
+                    candidate.method === finding.method && candidate.path === finding.path,
+                )
+              : undefined
+          diagnostics.push({
+            rule: "capability-assurance",
+            severity: "error",
+            ...(violation !== undefined ? { file: violation.module, chain: violation.chain } : {}),
+            message: `${finding.message} — ${CAPABILITY_HINT}`,
+            fix: CAPABILITY_HINT,
+            suggestion: {
+              kind: "manual",
+              title: "Restore declared effect provenance",
+              steps: [
+                "Route effectful work through an import listed in capabilities.provenance.imports.",
+                "Declare the exact capability token on the route; do not widen unrelated routes in the same file.",
+                "For domain writes, add the request-idempotency or durable-command adapter required by the capability definition.",
+                "Run `nifra capabilities snapshot` only after assurance passes, then review the lockfile diff.",
+              ],
+            },
+          })
+        }
+      }
+      if (config.manifest !== undefined) {
+        const { evaluateRouteAssurance } = await import("@nifrajs/core/assurance")
+        const { buildNifraManifest, parseNifraManifest, serializeNifraManifest } = await import(
+          "@nifrajs/core/manifest"
+        )
+        const assurance = evaluateRouteAssurance(config.source, config.policy)
+        const path = resolve(cwd, config.manifest.path ?? "nifra.manifest.json")
+        let message: string | undefined
+        if (!assurance.ok || (capabilityReport !== undefined && !capabilityReport.ok)) {
+          message =
+            "the configured assurance policy is failing, so a trusted manifest cannot be built"
+        } else if (!existsSync(path)) {
+          message = "the configured trust manifest is missing"
+        } else {
+          try {
+            const current = await buildNifraManifest({
+              source: config.source,
+              assurance,
+              ...(capabilityReport !== undefined ? { capabilities: capabilityReport } : {}),
+            })
+            const storedText = await Bun.file(path).text()
+            const stored = await parseNifraManifest(storedText, path)
+            const expectedText = `${serializeNifraManifest(current)}\n`
+            if (storedText !== expectedText || stored.contentHash !== current.contentHash) {
+              message = "the configured trust manifest does not match live route reflection"
+            }
+          } catch (error) {
+            message = `the configured trust manifest is invalid: ${error instanceof Error ? error.message : String(error)}`
+          }
+        }
+        if (message !== undefined) {
+          diagnostics.push({
+            rule: "manifest-drift",
+            severity: "error",
+            file: path,
+            message: `${message} — ${TRUST_MANIFEST_DRIFT_HINT}`,
+            fix: TRUST_MANIFEST_DRIFT_HINT,
+            suggestion: {
+              kind: "command",
+              title: "Regenerate the signed-manifest input artifact",
+              command: ["nifra", "manifest", "emit"],
+              steps: [
+                "Review the route, assurance, capability, and classification delta before committing it.",
+              ],
+            },
+          })
+        }
+      }
+    } catch (err) {
+      diagnostics.push({
+        rule: "capability-config",
+        severity: "error",
+        file: "nifra.assurance.ts",
+        message: `capability assurance config could not be evaluated: ${err instanceof Error ? err.message : String(err)}`,
+        suggestion: {
+          kind: "manual",
+          title: "Repair the assurance config",
+          steps: [
+            "Ensure nifra.assurance.ts default-exports defineAssuranceConfig({ source, policy, capabilities }).",
+            "Fix configuration/import errors; the provenance firewall fails closed when its policy cannot load.",
+          ],
+        },
+      })
+    }
+  }
+
   // Cap the diagnostics when asked (the MCP path), so a project with thousands of findings can't return a
   // message that breaks the stdio transport. `ok` reflects the FULL set — truncation never flips it.
   const total = diagnostics.length
   const max = opts.maxDiagnostics
   const shown = max !== undefined && total > max ? diagnostics.slice(0, max) : diagnostics
   return {
-    ok:
-      tc.ok &&
-      fetches.length === 0 &&
-      untypedClients.length === 0 &&
-      serverImports.length === 0 &&
-      manifestDrift.length === 0 &&
-      (!dr.ran || dr.findings.length === 0),
+    ok: !diagnostics.some((diagnostic) => diagnostic.severity === "error"),
     typecheck: tc.ran ? (tc.ok ? "pass" : "fail") : "skipped",
     diagnostics: shown,
     ...(shown.length < total ? { truncated: { shown: shown.length, total } } : {}),
@@ -1197,7 +1336,11 @@ export async function runCheck(
     ["server-only-import", "server-only import in a route module"],
     ["response-route", "route returns a raw Response (typed client → data: never)"],
     ["undeclared-dependency", "undeclared dependency in package.json"],
+    ["duplicate-install", "duplicate identity-sensitive dependency install"],
     ["server-manifest-drift", "server-manifest.ts drifted from routes/"],
+    ["manifest-drift", "versioned trust manifest drift"],
+    ["capability-assurance", "effect/capability assurance"],
+    ["capability-config", "capability assurance config"],
   ] as const) {
     const ds = counts(rule)
     if (rule === "response-route") {

package/src/cli.ts

@@ -59,7 +59,7 @@ Usage:
                                          agent: nifra_context, nifra_routes (routes+schemas as JSON),
                                          nifra_run (backend), nifra_render (SSR a page), nifra_docs,
                                          nifra_example (verified snippets), nifra_scaffold (route→file),
-                                         nifra_check (drift gate + fixes), nifra_doctor (undeclared deps).
+                                         nifra_check (drift gate + fixes), nifra_doctor (deps + duplicate installs).
   nifra docs-mcp [--port <n>]            Serve the PUBLIC docs MCP over HTTP (nifra_docs + nifra_example) —
                                          self-host on a VPS so any remote agent can learn nifra. Default :8787.
   nifra check   [--json] [--lints-only]  Gate: typecheck + lints (hand-rolled fetch(), untyped client("…"),
@@ -72,9 +72,34 @@ Usage:
                                          request field or a removed response field breaks; widening a
                                          request enum or adding a response field doesn't) and fails
                                          closed. Exits non-zero on any breaking change — run it in CI.
-  nifra doctor  [--json] [--auto-fix]    Flag packages imported in source but missing from package.json
-                                         (resolve at Bun runtime, break tsc + standalone install);
+  nifra assure  [--config <file>] [--json]  Route-assurance gate: load nifra.assurance.ts, classify every
+                                         reflected backend route, and fail when required enforcement
+                                         evidence is missing/forbidden or a route is unclassified.
+  nifra capabilities snapshot [--out <file>] [--config <file>]
+                                         Write the deterministic, token-only capability lockfile, but
+                                         only after provenance + idempotency assurance passes.
+  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 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.
+  nifra manifest diff <before> <after> [--json]
+                                         Hash-verify and compare two manifests; fail on contract, assurance,
+                                         capability, or response-classification regressions.
+  nifra levels  [--json] [--min <n>] [--config <file>]
+                                         Compute the verification ladder (L0 typed contract → L1 route
+                                         assurance → L2 capability lockfile → L3 route manifest → L4
+                                         invariant-tested); --min <n> fails the exit code below level n.
+  nifra doctor  [--json] [--auto-fix]    Flag undeclared imports and multiple physical copies of
+                                         @nifrajs/core/React identity-sensitive dependencies;
                                          --auto-fix writes safe local-version dependency fixes.
+  nifra upgrade <version>                Run the per-release upgrade recipe for <version>: sweep every
+                [--write] [--no-verify]  matching dependency pin (preserving ^/~/exact) + apply exact
+                [--list] [--json]        import moves across the workspace, then verify with nifra check.
+                                         Dry-run by default; --write applies then verifies (--no-verify
+                                         to skip). --list shows available targets. Fail-closed on an
+                                         unknown version. Deterministic + idempotent.
   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-
@@ -89,7 +114,7 @@ Port: \`dev\` and \`start\` share the default ${DEFAULT_DEV_PORT}. Override with
 \`PORT\` env var (\`--port\` wins over \`PORT\`, which wins over the default).`
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const CLI_VERSION = "1.6.0"
+const CLI_VERSION = "1.12.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
@@ -181,24 +206,28 @@ async function buildForTarget(app: LoadedApp, target: string, report: boolean):
   if (report) console.log(`\n${renderSizeReport(result.size)}`)
 }
 
-/** Build a fetch-capable app instance for the `static` target's prerender pass. Mirrors `nifra start`:
- * register the framework's SSR Bun plugins (so `.vue`/`.svelte`/Solid routes import), discover routes,
- * and wire the in-process backend so build-time loaders can read data. The returned `Server` already
- * satisfies `buildTarget`'s `PrerenderAppLike` (a `fetch(req)` yielding a `Response`). */
+/** Build the app FACTORY for the `static` target's prerender pass. Mirrors `nifra start`: register the
+ * framework's SSR Bun plugins (so `.vue`/`.svelte`/Solid routes import) once, then return a factory that
+ * `createWebApp`s the app for the client build's manifest. The client entry MUST be the real content-hashed
+ * bundle (`client.entry`) — it's the hydration `<script src>` the prerendered HTML emits, so a placeholder
+ * would 404 and the pages would render but never hydrate (inert controls). Styles/route-preload are wired
+ * from the same manifest so the static HTML matches what `nifra start` serves. */
 async function buildPrerenderApp(
   app: LoadedApp,
-): Promise<{ fetch(req: Request): Response | Promise<Response> }> {
+): Promise<(client: BuiltManifest) => { fetch(req: Request): Response | Promise<Response> }> {
   const { plugin } = await import("bun")
   const { framework: fw, routesDir, backend } = app
   for (const p of asBunPlugins(await resolvePlugins(fw.serverPlugins))) plugin(p)
-  return createWebApp({
-    adapter: asAdapter(fw.adapter),
-    manifest: discoverRoutes(routesDir),
-    // The client entry is irrelevant to the static HTML (it's a hydration script tag) — a placeholder
-    // is fine; the real hashed bundle is emitted to /assets by buildTarget's client build.
-    clientEntry: "/assets/_nifra-entry.js",
-    ...apiOf(backend),
-  })
+  return (client) =>
+    createWebApp({
+      adapter: asAdapter(fw.adapter),
+      manifest: discoverRoutes(routesDir),
+      clientEntry: client.entry,
+      ...(client.routes ? { routePreload: client.routes } : {}),
+      ...(client.css ? { styles: client.css } : {}),
+      ...(client.routeStyles ? { routeStyles: client.routeStyles } : {}),
+      ...apiOf(backend),
+    })
 }
 
 interface BuiltManifest {
@@ -371,6 +400,166 @@ async function main(): Promise<void> {
     }
     return
   }
+  // Route assurance intentionally loads only its explicit config (which imports the backend it audits),
+  // not the full SSR app. Like snapshot/diff, this works for API-only projects.
+  if (command === "assure") {
+    const { runAssurance } = await import("./assure.ts")
+    const configIdx = argv.indexOf("--config")
+    const config = configIdx !== -1 ? argv[configIdx + 1] : undefined
+    if (configIdx !== -1 && (config === undefined || config.startsWith("-"))) {
+      console.error("[nifra] --config needs a file path")
+      process.exitCode = 1
+      return
+    }
+    try {
+      if (
+        !(await runAssurance(process.cwd(), {
+          json: argv.includes("--json"),
+          ...(config !== undefined ? { config } : {}),
+        }))
+      )
+        process.exitCode = 1
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err))
+      process.exitCode = 1
+    }
+    return
+  }
+  if (command === "capabilities") {
+    const action = argv[1]
+    const valueAfter = (flag: string): string | undefined => {
+      const index = argv.indexOf(flag)
+      const value = index === -1 ? undefined : argv[index + 1]
+      if (index !== -1 && (value === undefined || value.startsWith("-"))) {
+        throw new Error(`[nifra] ${flag} needs a file path`)
+      }
+      return value
+    }
+    try {
+      const { runCapabilityCheck, runCapabilitySnapshot } = await import("./capabilities-tool.ts")
+      const config = valueAfter("--config")
+      if (action === "snapshot") {
+        const out = valueAfter("--out")
+        if (
+          !(await runCapabilitySnapshot(process.cwd(), {
+            ...(config !== undefined ? { config } : {}),
+            ...(out !== undefined ? { out } : {}),
+          }))
+        )
+          process.exitCode = 1
+      } else if (action === "check") {
+        const lockfile = valueAfter("--lockfile")
+        if (
+          !(await runCapabilityCheck(process.cwd(), {
+            ...(config !== undefined ? { config } : {}),
+            ...(lockfile !== undefined ? { lockfile } : {}),
+            json: argv.includes("--json"),
+          }))
+        )
+          process.exitCode = 1
+      } else {
+        throw new Error("[nifra] capabilities needs `snapshot` or `check`")
+      }
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err))
+      process.exitCode = 1
+    }
+    return
+  }
+  if (command === "manifest") {
+    const action = argv[1]
+    const valueAfter = (flag: string): string | undefined => {
+      const index = argv.indexOf(flag)
+      const value = index === -1 ? undefined : argv[index + 1]
+      if (index !== -1 && (value === undefined || value.startsWith("-"))) {
+        throw new Error(`[nifra] ${flag} needs a value`)
+      }
+      return value
+    }
+    try {
+      const { runManifestDiff, runManifestEmit } = await import("./manifest-tool.ts")
+      if (action === "emit") {
+        const config = valueAfter("--config")
+        const out = valueAfter("--out")
+        const sign = valueAfter("--sign")
+        if (
+          !(await runManifestEmit(process.cwd(), {
+            ...(config !== undefined ? { config } : {}),
+            ...(out !== undefined ? { out } : {}),
+            ...(sign !== undefined ? { sign } : {}),
+          }))
+        )
+          process.exitCode = 1
+      } else if (action === "diff") {
+        const paths = argv.slice(2).filter((arg) => !arg.startsWith("-"))
+        if (paths.length !== 2) throw new Error("[nifra] manifest diff needs <before> <after>")
+        if (
+          !(await runManifestDiff(process.cwd(), paths[0]!, paths[1]!, {
+            json: argv.includes("--json"),
+          }))
+        )
+          process.exitCode = 1
+      } else {
+        throw new Error("[nifra] manifest needs `emit` or `diff`")
+      }
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err))
+      process.exitCode = 1
+    }
+    return
+  }
+  if (command === "levels") {
+    const valueAfter = (flag: string): string | undefined => {
+      const index = argv.indexOf(flag)
+      const value = index === -1 ? undefined : argv[index + 1]
+      if (index !== -1 && (value === undefined || value.startsWith("-"))) {
+        throw new Error(`[nifra] ${flag} needs a value`)
+      }
+      return value
+    }
+    try {
+      const { runLevels } = await import("./levels-tool.ts")
+      const config = valueAfter("--config")
+      const minRaw = valueAfter("--min")
+      const min = minRaw === undefined ? undefined : Number(minRaw)
+      if (min !== undefined && (!Number.isInteger(min) || min < 0 || min > 4)) {
+        throw new Error("[nifra] --min must be an integer level between 0 and 4")
+      }
+      if (
+        !(await runLevels(process.cwd(), {
+          json: argv.includes("--json"),
+          ...(config !== undefined ? { config } : {}),
+          ...(min !== undefined ? { min } : {}),
+        }))
+      )
+        process.exitCode = 1
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(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).
+  if (command === "upgrade") {
+    const { runUpgrade } = await import("./upgrade.ts")
+    const version = argv.slice(1).find((arg) => !arg.startsWith("-"))
+    try {
+      const ok = await runUpgrade(process.cwd(), {
+        ...(version !== undefined ? { version } : {}),
+        write: argv.includes("--write"),
+        json: argv.includes("--json"),
+        list: argv.includes("--list"),
+        verify: !argv.includes("--no-verify"),
+      })
+      if (!ok) process.exitCode = 1
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err))
+      process.exitCode = 1
+    }
+    return
+  }
   // `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") {