@nifrajs/cli 2.12.1 → 2.14.1

package/src/contracts.ts

@@ -41,8 +41,7 @@ async function sha256(value: string): Promise<string> {
   return [...digest].map((item) => item.toString(16).padStart(2, "0")).join("")
 }
 
-function schemaValue(route: ReflectedRoute, side: "request" | "response"): unknown {
-  const schema = route.schema
+function schemaValue(schema: ReflectedRoute["schema"], side: "request" | "response"): unknown {
   if (schema === undefined) return {}
   if (side === "request") {
     return {
@@ -64,11 +63,28 @@ function schemaValue(route: ReflectedRoute, side: "request" | "response"): unkno
 }
 
 export async function digestRoute(route: ReflectedRoute): Promise<ContractDigest> {
-  const request = JSON.stringify(canonical(schemaValue(route, "request")))
-  const response = JSON.stringify(canonical(schemaValue(route, "response")))
+  const request = JSON.stringify(canonical(schemaValue(route.schema, "request")))
+  const response = JSON.stringify(canonical(schemaValue(route.schema, "response")))
   return { request: await sha256(request), response: await sha256(response) }
 }
 
+/** The digest a route with NO declared schema produces on both sides - `sha256("{}")`. A lock whose
+ * every route hashes to this is guarding nothing: drift detection can only ever compare empty schema to
+ * empty schema. Computed through the same canonical/stringify path as {@link digestRoute} so it tracks
+ * that path rather than a hard-coded literal. */
+export async function emptySchemaDigest(): Promise<string> {
+  return sha256(JSON.stringify(canonical(schemaValue(undefined, "request"))))
+}
+
+/** Whether every route in `lock` hashes to the empty-schema digest (so no route declares a schema). An
+ * empty `routes` map is NOT vacuous in this sense - there is no route whose contract went unguarded. */
+export async function isVacuousLock(lock: ContractsLock): Promise<boolean> {
+  const digests = Object.values(lock.routes)
+  if (digests.length === 0) return false
+  const empty = await emptySchemaDigest()
+  return digests.every((d) => d.request === empty && d.response === empty)
+}
+
 export async function buildContractsLock(source: unknown): Promise<ContractsLock> {
   const routes = Object.fromEntries(
     await Promise.all(
@@ -131,11 +147,16 @@ export function parseContractsLock(value: unknown): ContractsLock {
 export async function checkContractsLock(
   cwd: string,
   file = DEFAULT_CONTRACTS_LOCK,
-): Promise<{ present: boolean; diagnostics: Array<{ route?: string; message: string }> }> {
+): Promise<{
+  present: boolean
+  vacuous: boolean
+  diagnostics: Array<{ route?: string; message: string }>
+}> {
   const path = resolve(cwd, file)
-  if (!existsSync(path)) return { present: false, diagnostics: [] }
+  if (!existsSync(path)) return { present: false, vacuous: false, diagnostics: [] }
   const parsed = parseContractsLock(JSON.parse(await Bun.file(path).text()))
   const current = await buildContractsLock(await loadBackend(cwd))
+  const vacuous = await isVacuousLock(current)
   const diagnostics: Array<{ route?: string; message: string }> = []
   const keys = new Set([...Object.keys(parsed.routes), ...Object.keys(current.routes)])
   for (const key of [...keys].sort()) {
@@ -153,5 +174,5 @@ export async function checkContractsLock(
       })
     }
   }
-  return { present: true, diagnostics }
+  return { present: true, vacuous, diagnostics }
 }

package/src/doctor.ts

@@ -17,10 +17,18 @@
  * undeclared import there fails a clean `bun install --frozen-lockfile` build just the same.
  */
 import type { Dirent } from "node:fs"
-import { lstat, readdir, realpath, stat } from "node:fs/promises"
+import { readdir, stat } from "node:fs/promises"
 import { builtinModules } from "node:module"
 import { dirname, join, relative, sep } from "node:path"
+import {
+  collectIdentityParity,
+  displayPath,
+  type IdentityParityCopy,
+  type IdentityParityFinding,
+  resolvedInstalledCopy,
+} from "@nifrajs/web/internal/parity"
 import { codePositionMask, type SourceFinding, stripComments, walkSource } from "./check.ts"
+import { detectToolingDrift, type ToolingDrift } from "./mcp-root.ts"
 import { collectPipelineReport, type PipelineReport } from "./pipeline-report.ts"
 import { type ResolvedTarget, resolveTarget } from "./port.ts"
 
@@ -137,6 +145,14 @@ export interface DoctorResult {
    * Advisory (never folded into `ok`): while actively editing a linked package its dist is always
    * momentarily behind - the finding matters when a dev server starts against it. */
   readonly staleDists: readonly StaleDistFinding[]
+  /**
+   * The running CLI is a different feature version than the `@nifrajs/cli` (or `@nifrajs/core`) the
+   * project installs. Advisory (never folded into `ok`): a stale global/bunx binary answering about a
+   * project it does not match is an environment problem, not a defect in the project - but every
+   * answer it gives (types, checks, docs) reads as authoritative. Present only when `cliVersion` was
+   * supplied and the feature versions disagree. Computed by {@link detectToolingDrift}.
+   */
+  readonly toolingDrift?: ToolingDrift
   /** Static production-readiness evidence for the selected deploy target. */
   readonly readiness?: DoctorReadiness
   /**
@@ -178,17 +194,8 @@ export interface DoctorReadiness {
   readonly items: readonly DoctorReadinessItem[]
 }
 
-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
+export interface DuplicateInstallCopy extends IdentityParityCopy {}
+export interface DuplicateInstallFinding extends Omit<IdentityParityFinding, "copies"> {
   readonly copies: readonly DuplicateInstallCopy[]
 }
 
@@ -229,8 +236,6 @@ 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)
@@ -343,251 +348,25 @@ const scopeForFile = (scopes: readonly DoctorPackageScope[], file: string): Doct
       (file === scope.relativeRoot || file.startsWith(`${scope.relativeRoot}/`)),
   ) ?? (scopes.find((scope) => scope.relativeRoot === "") as DoctorPackageScope)
 
-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 MAX_LINKED_PACKAGES = 64
-const MAX_LINK_PROBES = 4_096
-
-/** Is `path` inside `root` (or `root` itself)? Both must already be real paths. */
-const isInside = (root: string, path: string): boolean =>
-  path === root || path.startsWith(root.endsWith(sep) ? root : `${root}${sep}`)
-
-/**
- * The repo boundary for a linked package: the nearest ancestor holding a `.git`, so the upward
- * `node_modules` walk inside a sibling checkout stops where that checkout does instead of climbing
- * into a shared parent directory. Falls back to the package directory itself.
- */
-async function linkedRepoBoundary(packageRoot: string): Promise<string> {
-  let dir = packageRoot
-  for (let depth = 0; depth < 8; depth++) {
-    if (await pathExists(join(dir, ".git"))) return dir
-    const parent = dirname(dir)
-    if (parent === dir) break
-    dir = parent
-  }
-  return packageRoot
-}
-
-/**
- * Dependency roots that are symlinks OUT of the scanned workspace - a sibling checkout linked in with
- * `link:`/`file:`/`npm link`. Their own `node_modules` is a second physical install root, so a shared
- * package (`@nifrajs/core`, React) resolves to a different directory there than it does here. That is
- * a real duplicate: module identity is path-based, so registries, symbols, and hooks do not match
- * across the two copies - the exact split that reads as "my types collapsed for no reason".
- *
- * One level deep and bounded: links inside a linked package are not followed.
- */
-async function linkedPackageRoots(
-  importerRoots: readonly string[],
-  manifests: readonly Record<string, unknown>[],
-  scanRoot: string,
-): Promise<string[]> {
-  const realScanRoot = await realpath(scanRoot).catch(() => scanRoot)
-  const found = new Map<string, true>()
-  let probes = 0
-  for (const [index, importerRoot] of importerRoots.entries()) {
-    const pkg = manifests[index]
-    if (pkg === undefined) continue
-    const names = new Set<string>()
-    for (const field of DEPENDENCY_FIELDS) for (const name of depNames(pkg, field)) names.add(name)
-    for (const name of names) {
-      if (probes++ >= MAX_LINK_PROBES || found.size >= MAX_LINKED_PACKAGES) return [...found.keys()]
-      const candidate = join(importerRoot, "node_modules", ...name.split("/"))
-      // `lstat` first: on macOS `realpath` also rewrites symlinked ANCESTORS (`/tmp` ->
-      // `/private/tmp`), which would read as a link out of the workspace for every dependency.
-      const link = await lstat(candidate).catch(() => undefined)
-      if (link === undefined || !link.isSymbolicLink()) continue
-      const resolved = await realpath(candidate).catch(() => undefined)
-      if (resolved === undefined || isInside(realScanRoot, resolved)) continue
-      found.set(resolved, true)
-    }
-  }
-  return [...found.keys()]
-}
-
-const displayPath = (cwd: string, path: string): string => {
-  const rel = relative(cwd, path)
-  return rel === "" ? "." : rel
-}
-
-/**
- * Resolve the workspace root that actually governs `cwd`, or `undefined` when there is none.
- *
- * Everything below is anchored to a package that declares `workspaces`. In a monorepo you run
- * `nifra check` from the app - `apps/web` - and THAT manifest declares nothing, so the scan collapses
- * to the app itself and the sibling package holding the second copy is never probed. Running from an
- * app subdirectory is the normal case, which made this the configuration the check was blind in.
- *
- * An ancestor is adopted only when its `workspaces` patterns genuinely match `cwd`. A parent
- * directory that happens to contain a manifest is not automatically this project's root, and adopting
- * one would silently widen the scan to an unrelated tree. The walk also stops at a `.git` boundary
- * (checked after the manifest, so a repo root that IS the workspace root still counts) and at the
- * filesystem root.
- */
-/** Whether `path` exists at all. `stat`, not a file read: a `.git` is a directory in a normal
- * checkout and a FILE in a worktree or submodule, and both mark the same boundary. */
-const pathExists = (path: string): Promise<boolean> =>
-  stat(path).then(
-    () => true,
-    () => false,
-  )
-
-async function findWorkspaceRoot(
-  cwd: string,
-): Promise<{ root: string; package: Record<string, unknown> } | undefined> {
-  let dir = dirname(cwd)
-  for (;;) {
-    const manifestPath = join(dir, "package.json")
-    const manifest = await readJson(manifestPath)
-    if (manifest !== undefined) {
-      const patterns = workspacePatterns(manifest)
-      if (patterns.length > 0 && (await patternsCover(dir, patterns, cwd))) {
-        return { root: dir, package: manifest }
-      }
-    }
-    // A `.git` here means we have reached this project's boundary; anything above belongs to a
-    // different repo (or a parent checkout) and must not be adopted.
-    if (await pathExists(join(dir, ".git"))) return undefined
-    const parent = dirname(dir)
-    if (parent === dir) return undefined
-    dir = parent
-  }
-}
-
-/** Whether any of `root`'s workspace patterns resolves to a manifest inside `target`'s package. */
-async function patternsCover(root: string, patterns: string[], target: string): Promise<boolean> {
-  for (const pattern of patterns) {
-    const packagePattern = `${pattern.replace(/\/$/, "")}/package.json`
-    for await (const rel of new Bun.Glob(packagePattern).scan({ cwd: root, dot: false })) {
-      if (rel.split(/[\\/]/).includes("node_modules")) continue
-      if (dirname(join(root, rel)) === target) return true
-    }
-  }
-  return false
-}
+/* Identity-sensitive install resolution is owned by @nifrajs/web/internal/parity. */
 
 /** 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.
  *
  * `cwd` is where the user ran the check; the scan is anchored at the workspace root above it (see
- * {@link findWorkspaceRoot}) so sibling packages are probed, while paths are still REPORTED relative
- * to `cwd` so the findings read the way the user's terminal does. */
+ * The shared parity seam resolves the governing workspace root, while paths are still REPORTED
+ * relative to `cwd` so the findings read the way the user's terminal does. */
 export async function collectDuplicateInstalls(
   cwd: string,
   rootPackage: Record<string, unknown>,
 ): Promise<DuplicateInstallFinding[]> {
-  const workspace = await findWorkspaceRoot(cwd)
-  const scanRoot = workspace?.root ?? cwd
-  const importers = await workspaceImporters(scanRoot, workspace?.package ?? rootPackage)
-  const byPackage = new Map<string, Map<string, { version: string; importers: Set<string> }>>()
-  const record = (
-    name: string,
-    copy: { path: string; version: string },
-    importer: string,
-  ): void => {
-    let copies = byPackage.get(name)
-    if (copies === undefined) {
-      copies = new Map()
-      byPackage.set(name, copies)
-    }
-    const entry = copies.get(copy.path) ?? { version: copy.version, importers: new Set<string>() }
-    entry.importers.add(importer)
-    copies.set(copy.path, entry)
-  }
-
-  const targets = new Set<string>()
-  for (const importer of importers) {
-    for (const name of duplicateTargets(importer.package)) {
-      if (importer.package.name === name) continue
-      targets.add(name)
-      // Boundary is the SCAN root, not `cwd`: an importer can now sit beside or above the directory
-      // the user ran from, and stopping the upward walk at `cwd` would abandon it before reaching the
-      // hoisted copy it actually resolves.
-      const copy = await resolvedInstalledCopy(importer.root, scanRoot, name)
-      if (copy !== undefined) record(name, copy, displayPath(cwd, importer.root))
-    }
-  }
-
-  // Probe the workspace root for every target too, even when the root manifest doesn't declare it.
-  // A hoisted root copy is reachable from any package that lacks its own nested one, so leaving it
-  // out hides the very split it should catch: every declaring package nested onto one copy while the
-  // root resolved a different one, which reads as a single copy when only declarers are consulted.
-  for (const name of targets) {
-    const copy = await resolvedInstalledCopy(scanRoot, scanRoot, name)
-    if (copy !== undefined) record(name, copy, displayPath(cwd, scanRoot))
-  }
-
-  // Sibling checkouts linked in (`link:`/`file:`/`npm link`) install their own copies. Their
-  // resolution is what the runtime and `tsc` actually use for code that crosses the link, so a split
-  // there is as real as one inside this workspace - and invisible to a scan bounded by the workspace.
-  const linkedRoots = await linkedPackageRoots(
-    [...importers.map((importer) => importer.root), scanRoot],
-    [...importers.map((importer) => importer.package), workspace?.package ?? rootPackage],
-    scanRoot,
+  const result = await collectIdentityParity(cwd, rootPackage, { useWorkspaceRoot: true })
+  return result.findings.map(
+    (finding): DuplicateInstallFinding => ({
+      ...finding,
+      copies: finding.copies.map((copy): DuplicateInstallCopy => ({ ...copy })),
+    }),
   )
-  for (const linkedRoot of linkedRoots) {
-    const linkedPackage = await readJson(join(linkedRoot, "package.json"))
-    const boundary = await linkedRepoBoundary(linkedRoot)
-    const linkedTargets = new Set([
-      ...targets,
-      ...(linkedPackage === undefined ? [] : duplicateTargets(linkedPackage)),
-    ])
-    for (const name of linkedTargets) {
-      if (linkedPackage?.name === name) continue
-      const copy = await resolvedInstalledCopy(linkedRoot, boundary, name)
-      if (copy !== undefined) record(name, copy, displayPath(cwd, linkedRoot))
-    }
-  }
-
-  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
 }
 
 /** A workspace-linked dependency whose build artifact is older than its source. */
@@ -902,7 +681,7 @@ async function inferDependencyFix(
 /** Run doctor against the project at `cwd`: diff source imports vs declared deps. */
 export async function collectDoctorResult(
   cwd: string,
-  opts: { readonly target?: string; readonly strict?: boolean } = {},
+  opts: { readonly target?: string; readonly strict?: boolean; readonly cliVersion?: string } = {},
 ): Promise<DoctorResult> {
   const pkg = await readJson(join(cwd, "package.json"))
   if (pkg === undefined)
@@ -930,7 +709,12 @@ export async function collectDoctorResult(
   const pipeline = await collectPipelineReport(cwd)
   const pipelineErrors = pipeline.findings.filter((f) => f.severity === "error")
   const readiness = await collectDoctorReadiness(cwd, opts)
-  // `staleDists` is advisory (see DoctorResult): it never fails `ok`.
+  // A stale binary answering about a project it does not match is an environment condition, so like
+  // `staleDists` it is reported but never folded into `ok`. Skipped entirely when the caller did not
+  // pass its own version (e.g. the MCP server, which already annotates every result with the drift).
+  const toolingDrift =
+    opts.cliVersion !== undefined ? await detectToolingDrift(cwd, opts.cliVersion) : undefined
+  // `staleDists` and `toolingDrift` are advisory (see DoctorResult): they never fail `ok`.
   return {
     ok:
       findings.length === 0 &&
@@ -942,6 +726,7 @@ export async function collectDoctorResult(
     duplicateInstalls,
     staleDists,
     readiness,
+    ...(toolingDrift !== undefined ? { toolingDrift } : {}),
     ...(pipeline.ran ? { pipeline } : {}),
   }
 }
@@ -949,7 +734,7 @@ export async function collectDoctorResult(
 /** Safely add undeclared imports to package.json when the version can be inferred without network I/O. */
 export async function applyDoctorAutoFix(
   cwd: string,
-  opts: { readonly target?: string; readonly strict?: boolean } = {},
+  opts: { readonly target?: string; readonly strict?: boolean; readonly cliVersion?: string } = {},
 ): Promise<DoctorResult> {
   const before = await collectDoctorResult(cwd, opts)
   if (!before.ran || before.findings.length === 0) return before
@@ -1028,6 +813,8 @@ export async function runDoctor(
     readonly autoFix?: boolean
     readonly strict?: boolean
     readonly target?: string
+    /** The running CLI's own version, so doctor can flag a binary that mismatches the project. */
+    readonly cliVersion?: string
   } = {},
 ): Promise<boolean> {
   const result = opts.autoFix
@@ -1102,6 +889,19 @@ export async function runDoctor(
     }
     console.log("")
   }
+  // Advisory, printed regardless of ok: the binary answering is a different feature version than the
+  // one the project builds with, so its types/checks/docs describe a surface the code does not have.
+  if (result.toolingDrift !== undefined) {
+    const drift = result.toolingDrift
+    console.log(
+      `⚠ this CLI is nifra ${drift.cli}, but the project installs ${drift.package} ${drift.project} - ` +
+        "its types, checks, and docs may describe a different version than your code builds with.",
+    )
+    console.log(
+      "      fix: run the project's own CLI (`bunx --bun nifra doctor` from the project directory, " +
+        "or ./node_modules/.bin/nifra)\n",
+    )
+  }
   if (result.ok) {
     console.log(
       "✓ every imported package is declared and identity-sensitive installs are deduplicated",
@@ -1127,22 +927,14 @@ export async function runDoctor(
       `${byPkg.size > 0 ? "\n" : ""}✗ identity-sensitive packages resolve to multiple physical copies:\n`,
     )
     for (const finding of result.duplicateInstalls) {
-      console.log(`  ${finding.package}`)
+      console.log(`  ${finding.package} [${finding.cause}]`)
+      console.log(`      versions: ${finding.versions.join(", ")}`)
       for (const copy of finding.copies) {
         console.log(`      ${copy.version} at ${copy.path} ← ${copy.importers.join(", ")}`)
       }
-      if (finding.package === "@nifrajs/core") {
-        console.log(
-          "      ↳ a second @nifrajs/core breaks module identity: `typeof backend` collapses to `any`",
-        )
-        console.log(
-          "        at `.merge()` and route-type inference silently degrades - usually that error's root cause.",
-        )
-      }
+      console.log(`      ${finding.explanation}`)
+      console.log(`      fix: ${finding.remediation}`)
     }
-    console.log(
-      "\n  Align dependency ranges and reinstall from the workspace root; doctor never deletes installs.",
-    )
   }
   if (result.readiness?.strict === true && result.readiness.ok === false) {
     console.log("\n✗ production readiness is incomplete under --strict")

package/src/load.ts

@@ -13,7 +13,7 @@
  * reach the edge bundle. A simple single-target app with no edge build can put it all in `framework.ts`.
  */
 import { existsSync } from "node:fs"
-import { resolve } from "node:path"
+import { isAbsolute, resolve } from "node:path"
 import { checkPipelineSeparation } from "./pipeline-guard.ts"
 
 /**
@@ -210,11 +210,30 @@ export async function loadApp(
   // resolved to absolute here. It is embedded verbatim as an import specifier in the generated client
   // entry, and `nifra dev` and `nifra build` write that entry into DIFFERENT directories - so a relative
   // specifier would resolve against different bases and load in one phase but not the other. A bare or
-  // package specifier (`@nifrajs/web-react/client`) is location-independent and passes through unchanged.
-  const clientModule =
-    fw.clientModule.startsWith("./") || fw.clientModule.startsWith("../")
-      ? resolve(cwd, fw.clientModule)
-      : fw.clientModule
+  // package specifier (`@nifrajs/web-react/client`) or an already-absolute path is location-independent
+  // and passes through unchanged.
+  let clientModule: string
+  if (fw.clientModule.startsWith("./") || fw.clientModule.startsWith("../")) {
+    clientModule = resolve(cwd, fw.clientModule)
+  } else {
+    // A specifier that is neither `./`-relative, scoped (`@…`), nor absolute is read as a BARE PACKAGE
+    // specifier - resolved against `node_modules`, not `cwd`. If a real local file sits at that path
+    // (a `./` was forgotten: `src/client.tsx` instead of `./src/client.tsx`), the bundler would ignore
+    // the file, fail to find a package, and surface an opaque "cannot resolve" deep in the build. Reject
+    // it here with the one-character fix rather than letting it fail silently.
+    if (
+      !isAbsolute(fw.clientModule) &&
+      !fw.clientModule.startsWith("@") &&
+      existsSync(resolve(cwd, fw.clientModule))
+    ) {
+      throw new Error(
+        `[nifra] clientModule "${fw.clientModule}" has no "./" prefix, so it is read as a bare package ` +
+          `specifier - but a local file exists at that path. Prefix it with "./" (e.g. ` +
+          `"./${fw.clientModule}") so \`nifra dev\` and \`nifra build\` resolve the same local entry.`,
+      )
+    }
+    clientModule = fw.clientModule
+  }
   const [vitePlugins, clientPlugins, serverPlugins] = await Promise.all([
     resolvePlugins(fw.vitePlugins),
     resolvePlugins(fw.clientPlugins),

package/src/manifest-tool.ts

@@ -5,6 +5,7 @@ import { resolve } from "node:path"
 import {
   buildNifraManifest,
   diffNifraManifests,
+  type NifraManifest,
   type NifraManifestDiff,
   parseNifraManifest,
   serializeNifraManifest,
@@ -38,11 +39,18 @@ export function formatManifestDiff(diff: NifraManifestDiff): string {
   return lines.join("\n")
 }
 
-/** Build only after both assurance layers pass, then optionally create an operator-signed sidecar. */
-export async function runManifestEmit(
+export interface ManifestEmitCommandResult {
+  readonly ok: boolean
+  readonly path: string
+  readonly manifest?: NifraManifest
+  readonly signaturePath?: string
+}
+
+/** Emit the manifest without printing. This is the execution seam used by all adapters. */
+export async function collectManifestEmit(
   cwd: string,
   options: { readonly config?: string; readonly out?: string; readonly sign?: string } = {},
-): Promise<boolean> {
+): Promise<ManifestEmitCommandResult> {
   const verification = await collectProjectVerification(cwd, {
     ...(options.config !== undefined ? { config: options.config } : {}),
   })
@@ -58,9 +66,9 @@ export async function runManifestEmit(
   if (assurance === undefined) {
     throw new Error("[nifra] assurance evaluation was unavailable for manifest emission")
   }
+  const path = resolve(cwd, options.out ?? config.manifest?.path ?? DEFAULT_MANIFEST_FILE)
   if (!assurance.ok || (capabilityProject !== undefined && !capabilityProject.report.ok)) {
-    console.error("[nifra] refusing to emit a manifest from failing assurance")
-    return false
+    return { ok: false, path }
   }
   const manifest = await buildNifraManifest({
     source: config.source,
@@ -68,9 +76,9 @@ export async function runManifestEmit(
     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`)
 
+  let signaturePath: string | undefined
   if (options.sign !== undefined) {
     if (config.manifest?.signer === undefined) {
       throw new Error(
@@ -79,29 +87,52 @@ export async function runManifestEmit(
     }
     const signer = await config.manifest.signer(options.sign)
     const signature = await signNifraManifest(manifest, signer)
-    await Bun.write(`${path}.sig`, `${serializeNifraManifestSignature(signature)}\n`)
+    signaturePath = `${path}.sig`
+    await Bun.write(signaturePath, `${serializeNifraManifestSignature(signature)}\n`)
+  }
+  return { ok: true, path, manifest, ...(signaturePath === undefined ? {} : { signaturePath }) }
+}
+
+/** 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 result = await collectManifestEmit(cwd, options)
+  if (!result.ok) {
+    console.error("[nifra] refusing to emit a manifest from failing assurance")
+    return false
   }
   console.log(
-    `[nifra] wrote manifest to ${path}${options.sign === undefined ? "" : ` and ${path}.sig`}`,
+    `[nifra] wrote manifest to ${result.path}${result.signaturePath === undefined ? "" : ` and ${result.signaturePath}`}`,
   )
   return true
 }
 
 /** Diff two already-emitted, hash-verified artifacts. Suitable for deploy promotion gates. */
-export async function runManifestDiff(
+export async function collectManifestDiff(
   cwd: string,
   beforePath: string,
   afterPath: string,
-  options: { readonly json?: boolean } = {},
-): Promise<boolean> {
+): Promise<NifraManifestDiff> {
   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(
+  return diffNifraManifests(
     await parseNifraManifest(await Bun.file(before).text(), before),
     await parseNifraManifest(await Bun.file(after).text(), after),
   )
+}
+
+/** Diff two already-emitted, hash-verified artifacts and print the result. */
+export async function runManifestDiff(
+  cwd: string,
+  beforePath: string,
+  afterPath: string,
+  options: { readonly json?: boolean } = {},
+): Promise<boolean> {
+  const diff = await collectManifestDiff(cwd, beforePath, afterPath)
   console.log(
     options.json === true
       ? JSON.stringify({ hasBreaking: diff.hasBreaking, changes: diff.changes }, null, 2)

package/src/mcp-http.ts

@@ -29,7 +29,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 = "2.12.1"
+const VERSION = "2.14.1"
 const SERVER_INFO = { name: "nifra-docs", version: VERSION }
 // Derive the GET/health tool list from the tools actually served, so the line can never drift from them.
 const docsHealth = (tools: McpTool[]): string =>