@nifrajs/cli 2.13.0 → 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

@@ -28,6 +28,7 @@ import {
   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"
 
@@ -144,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
   /**
@@ -672,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)
@@ -700,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 &&
@@ -712,6 +726,7 @@ export async function collectDoctorResult(
     duplicateInstalls,
     staleDists,
     readiness,
+    ...(toolingDrift !== undefined ? { toolingDrift } : {}),
     ...(pipeline.ran ? { pipeline } : {}),
   }
 }
@@ -719,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
@@ -798,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
@@ -872,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",
@@ -897,7 +927,8 @@ 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(", ")}`)
       }

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.13.0"
+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 =>