@nifrajs/cli 1.6.0 → 1.12.0

package/src/doctor.ts

@@ -10,8 +10,9 @@
  * when a monorepo would hoist it. Relative paths, runtime builtins (node core, `node:`/`bun:`, `bun`),
  * the package's own name, and tsconfig `paths` aliases are excluded — none of them are npm deps.
  */
+import { realpath } from "node:fs/promises"
 import { builtinModules } from "node:module"
-import { dirname, join } from "node:path"
+import { dirname, join, relative } from "node:path"
 import { type SourceFinding, stripComments, walkSource } from "./check.ts"
 
 // Runtime-provided modules that are never an npm dependency: Node core (bare + `node:` form) and Bun's
@@ -117,12 +118,28 @@ export interface DoctorResult {
   /** `false` when no `package.json` was found at cwd — doctor can't run (reported, not a crash). */
   readonly ran: boolean
   readonly findings: readonly DoctorFinding[]
+  /** Packages that resolve to more than one physical install across this workspace. */
+  readonly duplicateInstalls: readonly DuplicateInstallFinding[]
   /** Dependencies written by `--auto-fix` / MCP `autoFix:true`. */
   readonly fixed?: readonly DoctorAppliedFix[]
   /** Findings that were safe to report but not safe to write automatically. */
   readonly skippedFixes?: readonly DoctorSkippedFix[]
 }
 
+export interface DuplicateInstallCopy {
+  /** Installed version, or `unknown` when package metadata is incomplete. */
+  readonly version: string
+  /** Physical package directory, relative to the doctor root when possible. */
+  readonly path: string
+  /** Workspace package roots whose normal Node/Bun resolution selects this copy. */
+  readonly importers: readonly string[]
+}
+
+export interface DuplicateInstallFinding {
+  readonly package: string
+  readonly copies: readonly DuplicateInstallCopy[]
+}
+
 export interface DoctorAppliedFix {
   readonly package: string
   readonly field: "dependencies"
@@ -159,6 +176,132 @@ const depNames = (pkg: Record<string, unknown>, field: string): string[] => {
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value)
 
+const MAX_WORKSPACE_IMPORTERS = 2_048
+const IDENTITY_SENSITIVE_PACKAGES = new Set(["@nifrajs/core", "react", "react-dom"])
+
+function workspacePatterns(pkg: Record<string, unknown>): string[] {
+  const raw = pkg.workspaces
+  const entries = Array.isArray(raw)
+    ? raw
+    : isRecord(raw) && Array.isArray(raw.packages)
+      ? raw.packages
+      : []
+  return entries
+    .filter((entry): entry is string => typeof entry === "string" && entry.length > 0)
+    .sort()
+}
+
+/** Discover package roots declared by npm/Bun's two workspace manifest shapes. Bounded so a hostile
+ * `**` pattern cannot turn a diagnostic into an unbounded filesystem crawl. */
+async function workspaceImporters(
+  cwd: string,
+  rootPackage: Record<string, unknown>,
+): Promise<Array<{ root: string; package: Record<string, unknown> }>> {
+  const manifests = new Set<string>([join(cwd, "package.json")])
+  for (const pattern of workspacePatterns(rootPackage)) {
+    const packagePattern = `${pattern.replace(/\/$/, "")}/package.json`
+    for await (const rel of new Bun.Glob(packagePattern).scan({ cwd, dot: false })) {
+      if (rel.split(/[\\/]/).includes("node_modules")) continue
+      manifests.add(join(cwd, rel))
+      // A pathological workspace pattern should not make doctor unbounded. Duplicate detection is
+      // skipped, while the existing source/declaration diagnostic still runs normally.
+      if (manifests.size > MAX_WORKSPACE_IMPORTERS) return []
+    }
+  }
+
+  const out: Array<{ root: string; package: Record<string, unknown> }> = []
+  for (const manifest of [...manifests].sort()) {
+    const pkg = await readJson(manifest)
+    if (pkg !== undefined) out.push({ root: dirname(manifest), package: pkg })
+  }
+  return out
+}
+
+function duplicateTargets(pkg: Record<string, unknown>): string[] {
+  const targets = new Set<string>()
+  for (const field of DEPENDENCY_FIELDS) {
+    for (const name of depNames(pkg, field)) {
+      if (name.startsWith("@nifrajs/") || IDENTITY_SENSITIVE_PACKAGES.has(name)) targets.add(name)
+    }
+  }
+  return [...targets].sort()
+}
+
+async function resolvedInstalledCopy(
+  importer: string,
+  boundary: string,
+  name: string,
+): Promise<{ path: string; version: string } | undefined> {
+  const parts = name.split("/")
+  for (let dir = importer; ; dir = dirname(dir)) {
+    const packageDir = join(dir, "node_modules", ...parts)
+    const meta = await readJson(join(packageDir, "package.json"))
+    if (meta !== undefined) {
+      try {
+        return {
+          path: await realpath(packageDir),
+          version:
+            typeof meta.version === "string" && meta.version.length > 0 ? meta.version : "unknown",
+        }
+      } catch {
+        return undefined
+      }
+    }
+    if (dir === boundary) return undefined
+    const parent = dirname(dir)
+    if (parent === dir) return undefined
+  }
+}
+
+const displayPath = (cwd: string, path: string): string => {
+  const rel = relative(cwd, path)
+  return rel === "" ? "." : rel
+}
+
+/** Find identity-sensitive dependencies that resolve to multiple physical directories. Two copies at
+ * the same version still fail: module identity (React hooks, Nifra symbols/registries) is path-based. */
+export async function collectDuplicateInstalls(
+  cwd: string,
+  rootPackage: Record<string, unknown>,
+): Promise<DuplicateInstallFinding[]> {
+  const importers = await workspaceImporters(cwd, rootPackage)
+  const byPackage = new Map<string, Map<string, { version: string; importers: Set<string> }>>()
+  for (const importer of importers) {
+    for (const name of duplicateTargets(importer.package)) {
+      if (importer.package.name === name) continue
+      const copy = await resolvedInstalledCopy(importer.root, cwd, name)
+      if (copy === undefined) continue
+      let copies = byPackage.get(name)
+      if (copies === undefined) {
+        copies = new Map()
+        byPackage.set(name, copies)
+      }
+      const record = copies.get(copy.path) ?? {
+        version: copy.version,
+        importers: new Set<string>(),
+      }
+      record.importers.add(displayPath(cwd, importer.root))
+      copies.set(copy.path, record)
+    }
+  }
+
+  const findings: DuplicateInstallFinding[] = []
+  for (const [name, copies] of [...byPackage.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    if (copies.size < 2) continue
+    findings.push({
+      package: name,
+      copies: [...copies.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([path, copy]) => ({
+          version: copy.version,
+          path: displayPath(cwd, path),
+          importers: [...copy.importers].sort(),
+        })),
+    })
+  }
+  return findings
+}
+
 function depRecord(
   pkg: Record<string, unknown>,
   field: string,
@@ -217,7 +360,7 @@ async function inferDependencyFix(
 /** Run doctor against the project at `cwd`: diff source imports vs declared deps. */
 export async function collectDoctorResult(cwd: string): Promise<DoctorResult> {
   const pkg = await readJson(join(cwd, "package.json"))
-  if (pkg === undefined) return { ok: true, ran: false, findings: [] }
+  if (pkg === undefined) return { ok: true, ran: false, findings: [], duplicateInstalls: [] }
 
   const declared = new Set<string>()
   if (typeof pkg.name === "string") declared.add(pkg.name) // a package may import its own name (exports map)
@@ -238,7 +381,13 @@ export async function collectDoctorResult(cwd: string): Promise<DoctorResult> {
     }
   })
   findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line)
-  return { ok: findings.length === 0, ran: true, findings }
+  const duplicateInstalls = await collectDuplicateInstalls(cwd, pkg)
+  return {
+    ok: findings.length === 0 && duplicateInstalls.length === 0,
+    ran: true,
+    findings,
+    duplicateInstalls,
+  }
 }
 
 /** Safely add undeclared imports to package.json when the version can be inferred without network I/O. */
@@ -327,7 +476,9 @@ export async function runDoctor(
     console.log("")
   }
   if (result.ok) {
-    console.log("✓ every imported package is declared in package.json")
+    console.log(
+      "✓ every imported package is declared and identity-sensitive installs are deduplicated",
+    )
     return true
   }
   // Group by package so the fix ("add X to dependencies") is stated once with its import sites.
@@ -337,13 +488,30 @@ export async function runDoctor(
     list.push(f)
     byPkg.set(f.package, list)
   }
-  console.log(`✗ ${byPkg.size} package(s) imported but not declared in package.json:\n`)
-  for (const [pkg, sites] of [...byPkg.entries()].sort()) {
-    console.log(`  ${pkg} — add to dependencies (\`bun add ${pkg}\`)`)
-    for (const s of sites) console.log(`      ${s.file}:${s.line}`)
+  if (byPkg.size > 0) {
+    console.log(`✗ ${byPkg.size} package(s) imported but not declared in package.json:\n`)
+    for (const [pkg, sites] of [...byPkg.entries()].sort()) {
+      console.log(`  ${pkg} - add to dependencies (\`bun add ${pkg}\`)`)
+      for (const s of sites) console.log(`      ${s.file}:${s.line}`)
+    }
   }
-  console.log(
-    "\nThese resolve at Bun runtime via hoisting/workspace but break `tsc` and a standalone install.",
-  )
+  if (result.duplicateInstalls.length > 0) {
+    console.log(
+      `${byPkg.size > 0 ? "\n" : ""}✗ identity-sensitive packages resolve to multiple physical copies:\n`,
+    )
+    for (const finding of result.duplicateInstalls) {
+      console.log(`  ${finding.package}`)
+      for (const copy of finding.copies) {
+        console.log(`      ${copy.version} at ${copy.path} ← ${copy.importers.join(", ")}`)
+      }
+    }
+    console.log(
+      "\n  Align dependency ranges and reinstall from the workspace root; doctor never deletes installs.",
+    )
+  }
+  if (byPkg.size > 0)
+    console.log(
+      "\nThese resolve at Bun runtime via hoisting/workspace but break `tsc` and a standalone install.",
+    )
   return false
 }

package/src/levels-tool.ts

@@ -0,0 +1,232 @@
+/**
+ * `nifra levels` — the verification ladder, computed from gates that already exist:
+ *
+ *   L0 typed contract      — `nifra check` passes (compiler-enforced frontend↔backend contract)
+ *   L1 route assurance     — `nifra.assurance.ts` present and every route satisfies its policy
+ *   L2 capability lockfile — capability/effect assurance passes and the lockfile is in sync
+ *   L3 route manifest      — the emitted manifest hash-verifies and matches the current app
+ *   L4 invariant-tested    — every route passes through an explicitly isolated executor
+ *
+ * A level counts only when every level below it holds — the ladder is cumulative, so "L3" is one
+ * honest word for a whole posture. Levels are computed, never self-declared.
+ */
+
+import { existsSync } from "node:fs"
+import { resolve } from "node:path"
+import { evaluateRouteAssurance } from "@nifrajs/core/assurance"
+import { type evaluateCapabilityAssurance, snapshotCapabilities } from "@nifrajs/core/capabilities"
+import { buildNifraManifest, parseNifraManifest } from "@nifrajs/core/manifest"
+import { type ContractTestApp, runAdversarialContract } from "@nifrajs/testing"
+import { loadAssuranceConfig } from "./assure.ts"
+import {
+  collectCapabilityProjectReport,
+  diffCapabilitySnapshots,
+  parseCapabilityLockfile,
+} from "./capabilities-tool.ts"
+import { collectCheckResult } from "./check.ts"
+import { DEFAULT_MANIFEST_FILE } from "./manifest-tool.ts"
+
+export interface VerificationLevelStatus {
+  readonly level: number
+  readonly name: string
+  readonly ok: boolean
+  /** Why the level does not hold — a gate failure or a missing prerequisite. Empty when ok. */
+  readonly reasons: readonly string[]
+}
+
+export interface VerificationLevelsResult {
+  /** Highest level whose whole ladder holds; -1 when even L0 fails. */
+  readonly achieved: number
+  readonly levels: readonly VerificationLevelStatus[]
+}
+
+export interface CollectLevelsOptions {
+  readonly config?: string
+  /** Deterministic seed for the L4 invariant run. Default 1. */
+  readonly seed?: number
+}
+
+/** Compute the ladder. Each level is evaluated independently, then gated on the levels below. */
+export async function collectVerificationLevels(
+  cwd: string,
+  options: CollectLevelsOptions = {},
+): Promise<VerificationLevelsResult> {
+  const statuses: { level: number; name: string; ok: boolean; reasons: string[] }[] = []
+
+  // L0 — typed contract (`nifra check`).
+  const check = await collectCheckResult(cwd, { maxDiagnostics: 5 })
+  statuses.push({
+    level: 0,
+    name: "typed contract",
+    ok: check.ok,
+    reasons: check.ok ? [] : check.diagnostics.map((d) => `${d.rule}: ${d.message}`).slice(0, 5),
+  })
+
+  // L1-L4 all hang off the assurance config; without it the ladder stops at L0 by definition.
+  let config: Awaited<ReturnType<typeof loadAssuranceConfig>> | undefined
+  try {
+    config = await loadAssuranceConfig(cwd, options.config)
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    for (const [level, name] of [
+      [1, "route assurance"],
+      [2, "capability lockfile"],
+      [3, "route manifest"],
+      [4, "invariant-tested"],
+    ] as const) {
+      statuses.push({ level, name, ok: false, reasons: [reason] })
+    }
+    return finalize(statuses)
+  }
+
+  // L1 — route assurance.
+  const assurance = evaluateRouteAssurance(config.source, config.policy)
+  statuses.push({
+    level: 1,
+    name: "route assurance",
+    ok: assurance.ok,
+    reasons: assurance.findings.map((f) => f.message).slice(0, 5),
+  })
+
+  // L2 — capability assurance + lockfile in sync.
+  const l2Reasons: string[] = []
+  let capabilityReport: ReturnType<typeof evaluateCapabilityAssurance> | undefined
+  if (config.capabilities === undefined) {
+    l2Reasons.push("nifra.assurance.ts declares no capabilities policy")
+  } else {
+    const project = await collectCapabilityProjectReport(cwd, config.source, config.capabilities)
+    capabilityReport = project.report
+    if (!project.report.ok) {
+      l2Reasons.push(...project.report.findings.map((f) => f.message).slice(0, 5))
+    }
+    const lockfilePath = resolve(cwd, config.capabilities.lockfile ?? "capabilities.lock.json")
+    if (!existsSync(lockfilePath)) {
+      l2Reasons.push(`capability lockfile missing (${lockfilePath})`)
+    } else if (project.report.ok) {
+      const recorded = parseCapabilityLockfile(await Bun.file(lockfilePath).text(), lockfilePath)
+      const drift = diffCapabilitySnapshots(recorded, snapshotCapabilities(project.report))
+      if (drift.length > 0) l2Reasons.push(...drift.slice(0, 5))
+    }
+  }
+  statuses.push({
+    level: 2,
+    name: "capability lockfile",
+    ok: l2Reasons.length === 0,
+    reasons: l2Reasons,
+  })
+
+  // L3 — emitted manifest hash-verifies AND matches the current app.
+  const l3Reasons: string[] = []
+  const manifestPath = resolve(cwd, config.manifest?.path ?? DEFAULT_MANIFEST_FILE)
+  if (!existsSync(manifestPath)) {
+    l3Reasons.push(`manifest missing (${manifestPath}) — run \`nifra manifest emit\``)
+  } else {
+    try {
+      const recorded = await parseNifraManifest(await Bun.file(manifestPath).text(), manifestPath)
+      if (assurance.ok && (capabilityReport === undefined || capabilityReport.ok)) {
+        const current = await buildNifraManifest({
+          source: config.source,
+          assurance,
+          ...(capabilityReport !== undefined ? { capabilities: capabilityReport } : {}),
+        })
+        if (current.contentHash !== recorded.contentHash) {
+          l3Reasons.push("manifest is stale — the app changed since it was emitted")
+        }
+      } else {
+        l3Reasons.push("manifest cannot be validated while assurance is failing")
+      }
+    } catch (err) {
+      l3Reasons.push(err instanceof Error ? err.message : String(err))
+    }
+  }
+  statuses.push({
+    level: 3,
+    name: "route manifest",
+    ok: l3Reasons.length === 0,
+    reasons: l3Reasons,
+  })
+
+  // L4 — contract-generated invariants against an explicitly isolated executor.
+  const l4Reasons: string[] = []
+  if (config.invariants === undefined) {
+    l4Reasons.push(
+      "no isolated invariant executor configured — add `invariants.executor` in nifra.assurance.ts",
+    )
+  } else {
+    const invariants = await runAdversarialContract(config.source as ContractTestApp, {
+      seed: options.seed ?? 1,
+      runtimes: [{ name: "isolated", fetch: config.invariants.executor }],
+      expectedValidationStatuses: [400, 422],
+      requireCoverage: true,
+    })
+    if (!invariants.ok) {
+      l4Reasons.push(
+        ...invariants.failures
+          .slice(0, 5)
+          .map(
+            (failure) =>
+              `${failure.runtime}: ${failure.id} - ${failure.message} (replay seed ${failure.replay.seed})`,
+          ),
+      )
+      l4Reasons.push(
+        ...invariants.gaps
+          .slice(0, Math.max(0, 5 - l4Reasons.length))
+          .map(
+            (gap) =>
+              `${gap.route ?? "contract"}${gap.target ? ` ${gap.target}` : ""}: ${gap.message}`,
+          ),
+      )
+    }
+  }
+  statuses.push({
+    level: 4,
+    name: "invariant-tested",
+    ok: l4Reasons.length === 0,
+    reasons: l4Reasons,
+  })
+
+  return finalize(statuses)
+}
+
+function finalize(
+  statuses: readonly { level: number; name: string; ok: boolean; reasons: string[] }[],
+): VerificationLevelsResult {
+  // Cumulative: the achieved level is the last rung with every rung below it also holding.
+  let achieved = -1
+  for (const status of statuses) {
+    if (!status.ok) break
+    achieved = status.level
+  }
+  return Object.freeze({
+    achieved,
+    levels: Object.freeze(
+      statuses.map((status) =>
+        Object.freeze({ ...status, reasons: Object.freeze([...status.reasons]) }),
+      ),
+    ),
+  })
+}
+
+/** CLI entry: print the ladder (or JSON) and return whether the requested floor is met. */
+export async function runLevels(
+  cwd: string,
+  options: CollectLevelsOptions & { readonly json?: boolean; readonly min?: number } = {},
+): Promise<boolean> {
+  const result = await collectVerificationLevels(cwd, options)
+  if (options.json === true) {
+    console.log(JSON.stringify(result, null, 2))
+  } else {
+    for (const status of result.levels) {
+      const mark = status.ok ? "✓" : "✗"
+      console.log(`${mark} L${status.level} ${status.name}`)
+      for (const reason of status.reasons) console.log(`    - ${reason}`)
+    }
+    console.log(
+      result.achieved < 0
+        ? "[nifra] verification level: none (L0 failing)"
+        : `[nifra] verification level: L${result.achieved}`,
+    )
+  }
+  const min = options.min ?? 0
+  return result.achieved >= min
+}

package/src/manifest-tool.ts

@@ -0,0 +1,103 @@
+/** `nifra manifest` — emit/sign/diff the deployable route trust artifact. */
+
+import { existsSync } from "node:fs"
+import { resolve } from "node:path"
+import { evaluateRouteAssurance } from "@nifrajs/core/assurance"
+import {
+  buildNifraManifest,
+  diffNifraManifests,
+  type NifraManifestDiff,
+  parseNifraManifest,
+  serializeNifraManifest,
+  serializeNifraManifestSignature,
+  signNifraManifest,
+} from "@nifrajs/core/manifest"
+import { loadAssuranceConfig } from "./assure.ts"
+import { collectCapabilityProjectReport } from "./capabilities-tool.ts"
+
+export const DEFAULT_MANIFEST_FILE = "nifra.manifest.json"
+
+export function formatManifestDiff(diff: NifraManifestDiff): string {
+  if (diff.changes.length === 0) return "No manifest changes."
+  const weight = { breaking: 0, compatible: 1, info: 2 } as const
+  const lines = [...diff.changes]
+    .sort(
+      (a, b) =>
+        weight[a.severity] - weight[b.severity] ||
+        a.path.localeCompare(b.path) ||
+        a.method.localeCompare(b.method),
+    )
+    .map(
+      (change) =>
+        `${change.severity === "breaking" ? "✖" : change.severity === "compatible" ? "✓" : "•"} ${change.method} ${change.path} [${change.section}] ${change.message}`,
+    )
+  const breaking = diff.changes.filter((change) => change.severity === "breaking").length
+  lines.push(
+    diff.hasBreaking
+      ? `${breaking} breaking manifest change${breaking === 1 ? "" : "s"}.`
+      : "No breaking manifest changes.",
+  )
+  return lines.join("\n")
+}
+
+/** Build only after both assurance layers pass, then optionally create an operator-signed sidecar. */
+export async function runManifestEmit(
+  cwd: string,
+  options: { readonly config?: string; readonly out?: string; readonly sign?: string } = {},
+): Promise<boolean> {
+  const config = await loadAssuranceConfig(cwd, options.config)
+  const assurance = evaluateRouteAssurance(config.source, config.policy)
+  const capabilityProject =
+    config.capabilities === undefined
+      ? undefined
+      : await collectCapabilityProjectReport(cwd, config.source, config.capabilities)
+  if (!assurance.ok || (capabilityProject !== undefined && !capabilityProject.report.ok)) {
+    console.error("[nifra] refusing to emit a manifest from failing assurance")
+    return false
+  }
+  const manifest = await buildNifraManifest({
+    source: config.source,
+    assurance,
+    ...(capabilityProject !== undefined ? { capabilities: capabilityProject.report } : {}),
+  })
+  const path = resolve(cwd, options.out ?? config.manifest?.path ?? DEFAULT_MANIFEST_FILE)
+  await Bun.write(path, `${serializeNifraManifest(manifest)}\n`)
+
+  if (options.sign !== undefined) {
+    if (config.manifest?.signer === undefined) {
+      throw new Error(
+        "[nifra] --sign requires manifest.signer in nifra.assurance.ts; keep private keys behind that KMS/HSM callback.",
+      )
+    }
+    const signer = await config.manifest.signer(options.sign)
+    const signature = await signNifraManifest(manifest, signer)
+    await Bun.write(`${path}.sig`, `${serializeNifraManifestSignature(signature)}\n`)
+  }
+  console.log(
+    `[nifra] wrote manifest to ${path}${options.sign === undefined ? "" : ` and ${path}.sig`}`,
+  )
+  return true
+}
+
+/** Diff two already-emitted, hash-verified artifacts. Suitable for deploy promotion gates. */
+export async function runManifestDiff(
+  cwd: string,
+  beforePath: string,
+  afterPath: string,
+  options: { readonly json?: boolean } = {},
+): Promise<boolean> {
+  const before = resolve(cwd, beforePath)
+  const after = resolve(cwd, afterPath)
+  if (!existsSync(before)) throw new Error(`[nifra] manifest not found: ${before}`)
+  if (!existsSync(after)) throw new Error(`[nifra] manifest not found: ${after}`)
+  const diff = diffNifraManifests(
+    await parseNifraManifest(await Bun.file(before).text(), before),
+    await parseNifraManifest(await Bun.file(after).text(), after),
+  )
+  console.log(
+    options.json === true
+      ? JSON.stringify({ hasBreaking: diff.hasBreaking, changes: diff.changes }, null, 2)
+      : formatManifestDiff(diff),
+  )
+  return !diff.hasBreaking
+}

package/src/mcp-http.ts

@@ -26,7 +26,7 @@ export { docsTools } from "./mcp-docs-tools.ts"
 export type { TypeEntry } from "./types-search.ts"
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const VERSION = "1.6.0"
+const VERSION = "1.12.0"
 const SERVER_INFO = { name: "nifra-docs", version: VERSION }
 const DOCS_HEALTH =
   "nifra docs MCP — POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call). Tools: nifra_docs, nifra_example."

package/src/mcp.ts

@@ -14,6 +14,7 @@
  *     so it can't hallucinate a drifted nifra API).
  *   - `nifra_scaffold`— map a URL path to the correct `routes/` file + a contract-correct page stub.
  *   - `nifra_check`   — the drift gate (typecheck + lints, each with a structured fix), for an agent to fix against.
+ *   - `nifra_assure`  — route classification + enforcement-evidence gate.
  *   - `nifra_doctor`  — package.json dependency drift detector, with safe local-version auto-fix.
  *
  * Wire it into a client (e.g. Claude Desktop / Cursor) as: command `nifra`, args `["mcp"]`, run in the
@@ -951,6 +952,42 @@ export function projectTools(
         )
       },
     },
+    {
+      name: "nifra_assure",
+      description:
+        "Evaluate nifra.assurance.ts and return the complete route-assurance report: every reflected route's first matching policy rule, enforcement evidence, missing/forbidden evidence, and the fail-closed ok bit. Use after adding or changing routes/security middleware; fix every finding before finishing.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          config: {
+            type: "string",
+            description:
+              "Config path relative to the selected project directory. Default: nifra.assurance.ts.",
+          },
+          dir: {
+            type: "string",
+            description:
+              'Evaluate this project subdirectory (relative to the MCP root), e.g. "apps/api". Default: the project root.',
+          },
+        },
+        additionalProperties: false,
+      },
+      handler: async (args) => {
+        const opts = args as { config?: string; dir?: string }
+        const target = resolveProjectDir(cwd, opts.dir)
+        if (target === null) return dirError(opts.dir)
+        const config = opts.config === undefined ? undefined : resolve(target, opts.config)
+        if (config !== undefined && config !== target && !config.startsWith(target + sep)) {
+          return JSON.stringify(
+            { ok: false, error: "config must stay inside the selected project directory" },
+            null,
+            2,
+          )
+        }
+        const { collectAssuranceReport } = await import("./assure.ts")
+        return JSON.stringify(await collectAssuranceReport(target, config), null, 2)
+      },
+    },
     {
       name: "nifra_doctor",
       description:

package/src/recipes/1.8.0.ts

@@ -0,0 +1,21 @@
+import type { UpgradeRecipe } from "./index.ts"
+
+/**
+ * Upgrade recipe for nifra 1.8.0.
+ *
+ * 1.8.0 is a fixed-group bump: every `@nifrajs/*` package moves in lockstep. The pin sweep sets them
+ * all to 1.8.0 (preserving each spec's `^`/`~`/exact style). 1.8.0 introduced no breaking import moves
+ * in the public packages — the new surfaces (route assurance, adversarial testing, `@nifrajs/events`)
+ * are additive — so `importMoves` is empty. The notes flag the additive follow-ups a bump can't do for
+ * you (wiring the new assurance config), keeping the runner honest about what it did and didn't touch.
+ */
+export const recipe: UpgradeRecipe = {
+  version: "1.8.0",
+  pins: [{ match: "@nifrajs/", to: "1.8.0" }],
+  importMoves: [],
+  notes: [
+    "1.8.0 adds route assurance (@nifrajs/core + middleware) — optional. To enforce it in CI, add a `nifra.assurance.ts` policy and run `nifra assure`.",
+    "New package @nifrajs/events (portable versioned event contracts) — add it to package.json only if you adopt it; the pin sweep won't introduce a dependency you don't already declare.",
+    "@nifrajs/testing gained the adversarial contract lab — no migration needed; existing tests are unchanged.",
+  ],
+}