@nifrajs/cli 1.11.0 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/cli",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "The nifra CLI — zero-config dev/build/start for a nifra app (`nifra dev`, `nifra build`, `nifra start`).",
   "keywords": [
     "bun",
@@ -41,13 +41,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/client": "1.11.0",
-    "@nifrajs/core": "1.11.0",
-    "@nifrajs/mcp": "1.11.0",
-    "@nifrajs/runner": "1.11.0",
-    "@nifrajs/schema": "1.11.0",
-    "@nifrajs/web": "1.11.0",
-    "create-nifra": "1.11.0"
+    "@nifrajs/client": "1.12.0",
+    "@nifrajs/core": "1.12.0",
+    "@nifrajs/mcp": "1.12.0",
+    "@nifrajs/runner": "1.12.0",
+    "@nifrajs/schema": "1.12.0",
+    "@nifrajs/testing": "1.12.0",
+    "@nifrajs/web": "1.12.0",
+    "create-nifra": "1.12.0"
   },
   "repository": {
     "type": "git",

package/src/check.ts

@@ -770,6 +770,7 @@ export interface CheckDiagnostic {
     | "server-only-import"
     | "response-route"
     | "undeclared-dependency"
+    | "duplicate-install"
     | "server-manifest-drift"
     | "manifest-drift"
     | "capability-assurance"
@@ -1139,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) {
@@ -1317,6 +1336,7 @@ 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"],

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("…"),
@@ -91,8 +91,8 @@ Usage:
                                          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 packages imported in source but missing from package.json
-                                         (resolve at Bun runtime, break tsc + standalone install);
+  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
@@ -114,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.11.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

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

@@ -15,8 +15,8 @@ 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 { runContractInvariants } from "@nifrajs/core/invariants"
 import { buildNifraManifest, parseNifraManifest } from "@nifrajs/core/manifest"
+import { type ContractTestApp, runAdversarialContract } from "@nifrajs/testing"
 import { loadAssuranceConfig } from "./assure.ts"
 import {
   collectCapabilityProjectReport,
@@ -153,17 +153,27 @@ export async function collectVerificationLevels(
       "no isolated invariant executor configured — add `invariants.executor` in nifra.assurance.ts",
     )
   } else {
-    const invariants = await runContractInvariants(config.source as object, {
+    const invariants = await runAdversarialContract(config.source as ContractTestApp, {
       seed: options.seed ?? 1,
-      executor: config.invariants.executor,
+      runtimes: [{ name: "isolated", fetch: config.invariants.executor }],
+      expectedValidationStatuses: [400, 422],
+      requireCoverage: true,
     })
-    if (!invariants.ok) l4Reasons.push(...invariants.findings.map((f) => f.message).slice(0, 5))
-    if (invariants.skipped.length > 0) {
+    if (!invariants.ok) {
       l4Reasons.push(
-        ...invariants.skipped
+        ...invariants.failures
           .slice(0, 5)
           .map(
-            (route) => `${route.method} ${route.path} was not invariant-tested: ${route.reason}`,
+            (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}`,
           ),
       )
     }

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.11.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."