@nifrajs/cli 3.5.0 → 4.0.2

package/src/dev-server-client.ts

@@ -0,0 +1,267 @@
+/**
+ * Finds the running `nifra dev` server a tool should read, and reads its agent feed.
+ *
+ * A dev server writes `.nifra/dev-server.json` (owner-only) with its port and a per-run token. A
+ * record alone proves nothing - the process may have died and the port been reused - so a server
+ * counts as live only after it answers the identity endpoint with the record's own pid and root.
+ */
+
+import { existsSync, readdirSync } from "node:fs"
+import { join, resolve } from "node:path"
+import {
+  DEV_FEED_HEADER,
+  DEV_FEED_PATHS,
+  DEV_SERVER_LOG_FILE,
+  DEV_SERVER_RECORD_FILE,
+  DEV_TOKEN_HEADER,
+  type DevPipeline,
+  type DevServerIdentity,
+  type DevServerRecord,
+  isProcessAlive,
+  readDevServerRecord,
+} from "@nifrajs/web/dev-feed"
+import { LOCAL_TOOL_FETCH_TIMEOUT_MS, readBoundedResponse, validateLocalPort } from "./mcp-io.ts"
+
+export interface LiveDevServer {
+  readonly root: string
+  readonly port: number
+  readonly origin: string
+  readonly pipeline: DevPipeline
+  readonly pid: number
+  readonly startedAt: string
+  readonly token: string
+  readonly identity: DevServerIdentity
+}
+
+/** A dev server whose record survived it: it crashed or was killed before it could clean up. */
+export interface DeadDevServer {
+  readonly root: string
+  readonly port: number
+  readonly pid: number
+  readonly startedAt: string
+}
+
+export type DevServerLookup =
+  | { readonly status: "live"; readonly server: LiveDevServer }
+  /** An explicit port no record under the project names: reachable only through token-free paths. */
+  | { readonly status: "unverified"; readonly port: number; readonly origin: string }
+  | {
+      readonly status: "ambiguous"
+      readonly servers: readonly Pick<LiveDevServer, "root" | "port" | "pipeline">[]
+    }
+  | {
+      readonly status: "down"
+      /** Project roots holding a persisted feed from an earlier run, nearest first. */
+      readonly persisted: readonly string[]
+      readonly dead: readonly DeadDevServer[]
+      /** Servers whose record and process exist but which did not answer as themselves. */
+      readonly unreachable: readonly {
+        readonly root: string
+        readonly port: number
+        readonly reason: string
+      }[]
+    }
+  | { readonly status: "invalid-port" }
+
+export interface FindDevServerOptions {
+  readonly port?: number | undefined
+}
+
+// Where a workspace keeps its apps. One level only: the scan runs on every tool call.
+const SCAN_PARENTS = [".", "apps", "packages", "examples"] as const
+const MAX_SCANNED_ROOTS = 512
+
+function candidateRoots(cwd: string): string[] {
+  const roots = [cwd]
+  for (const parent of SCAN_PARENTS) {
+    const base = join(cwd, parent)
+    let names: string[]
+    try {
+      names = readdirSync(base, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .filter((name) => !name.startsWith(".") && name !== "node_modules")
+        .sort()
+    } catch {
+      continue
+    }
+    for (const name of names) {
+      if (roots.length >= MAX_SCANNED_ROOTS) return roots
+      const root = join(base, name)
+      if (!roots.includes(root)) roots.push(root)
+    }
+  }
+  return roots
+}
+
+const originOf = (port: number): string => `http://127.0.0.1:${port}`
+
+function isIdentity(value: unknown): value is DevServerIdentity {
+  if (typeof value !== "object" || value === null) return false
+  return (
+    "pid" in value &&
+    typeof value.pid === "number" &&
+    "root" in value &&
+    typeof value.root === "string" &&
+    "port" in value &&
+    typeof value.port === "number" &&
+    "cursor" in value &&
+    typeof value.cursor === "number"
+  )
+}
+
+type Verified =
+  | { readonly ok: true; readonly server: LiveDevServer }
+  | { readonly ok: false; readonly reason: string }
+
+async function verify(record: DevServerRecord, signal?: AbortSignal): Promise<Verified> {
+  const origin = originOf(record.port)
+  let body: unknown
+  try {
+    const response = await fetch(`${origin}${DEV_FEED_PATHS.identity}`, {
+      headers: { [DEV_TOKEN_HEADER]: record.token },
+      signal: anySignal(signal),
+    })
+    if (response.headers.get(DEV_FEED_HEADER) !== "true")
+      return { ok: false, reason: `port ${record.port} is not a nifra dev server` }
+    if (!response.ok) return { ok: false, reason: `identity check returned ${response.status}` }
+    body = JSON.parse(await readBoundedResponse(response))
+  } catch (cause) {
+    return { ok: false, reason: cause instanceof Error ? cause.message : String(cause) }
+  }
+  // A recycled port can host a different nifra server; its pid and root give it away.
+  if (!isIdentity(body) || body.pid !== record.pid || resolve(body.root) !== resolve(record.root))
+    return { ok: false, reason: `port ${record.port} now belongs to another server` }
+  return {
+    ok: true,
+    server: {
+      root: record.root,
+      port: record.port,
+      origin,
+      pipeline: record.pipeline,
+      pid: record.pid,
+      startedAt: record.startedAt,
+      token: record.token,
+      identity: body,
+    },
+  }
+}
+
+function anySignal(signal: AbortSignal | undefined): AbortSignal {
+  const timeout = AbortSignal.timeout(LOCAL_TOOL_FETCH_TIMEOUT_MS)
+  return signal === undefined ? timeout : AbortSignal.any([signal, timeout])
+}
+
+/**
+ * The dev server for the project at `cwd`: its own record first, else the one live server among the
+ * workspace's apps. An explicit `port` picks among them, and still works when no record names it.
+ */
+export async function findDevServer(
+  cwd: string,
+  options: FindDevServerOptions = {},
+  signal?: AbortSignal,
+): Promise<DevServerLookup> {
+  let port: number | undefined
+  if (options.port !== undefined) {
+    port = validateLocalPort(options.port)
+    if (port === undefined) return { status: "invalid-port" }
+  }
+  // The project's own live server wins outright, whatever else the workspace runs.
+  const own = readDevServerRecord(cwd)
+  if (own !== undefined && (port === undefined || own.port === port) && isProcessAlive(own.pid)) {
+    const result = await verify(own, signal)
+    if (result.ok) return { status: "live", server: result.server }
+  }
+  const roots = candidateRoots(cwd)
+  const records: DevServerRecord[] = []
+  const dead: DeadDevServer[] = []
+  for (const root of roots) {
+    if (!existsSync(join(root, DEV_SERVER_RECORD_FILE))) continue
+    const record = readDevServerRecord(root)
+    if (record === undefined) continue
+    if (port !== undefined && record.port !== port) continue
+    if (isProcessAlive(record.pid)) records.push(record)
+    else dead.push({ root, port: record.port, pid: record.pid, startedAt: record.startedAt })
+  }
+  const checked = await Promise.all(records.map((record) => verify(record, signal)))
+  const live: LiveDevServer[] = []
+  const unreachable: { root: string; port: number; reason: string }[] = []
+  checked.forEach((result, index) => {
+    const record = records[index]
+    if (record === undefined) return
+    if (result.ok) live.push(result.server)
+    else unreachable.push({ root: record.root, port: record.port, reason: result.reason })
+  })
+  const [first] = live
+  if (first !== undefined && live.length === 1) return { status: "live", server: first }
+  if (live.length > 1) {
+    return {
+      status: "ambiguous",
+      servers: live.map(({ root, port: livePort, pipeline }) => ({
+        root,
+        port: livePort,
+        pipeline,
+      })),
+    }
+  }
+  if (port !== undefined && unreachable.length === 0)
+    return { status: "unverified", port, origin: originOf(port) }
+  const persisted = roots.filter((root) => existsSync(join(root, DEV_SERVER_LOG_FILE)))
+  return { status: "down", persisted, dead, unreachable }
+}
+
+export type FeedQuery = Readonly<
+  Record<string, string | number | boolean | readonly string[] | undefined>
+>
+
+/** GET one feed endpoint as the authenticated agent. Throws when the server does not answer with JSON. */
+export async function readDevFeed(
+  server: LiveDevServer,
+  path: string,
+  query: FeedQuery = {},
+  signal?: AbortSignal,
+): Promise<unknown> {
+  const url = new URL(path, server.origin)
+  for (const [name, value] of Object.entries(query)) {
+    if (value === undefined) continue
+    url.searchParams.set(name, Array.isArray(value) ? value.join(",") : String(value))
+  }
+  const response = await fetch(url, {
+    headers: { [DEV_TOKEN_HEADER]: server.token },
+    signal: anySignal(signal),
+  })
+  if (response.headers.get(DEV_FEED_HEADER) !== "true")
+    throw new Error(`${server.origin} did not answer as a nifra dev server`)
+  const text = await readBoundedResponse(response)
+  if (!response.ok) throw new Error(`${path} returned ${response.status}: ${text.slice(0, 200)}`)
+  return JSON.parse(text)
+}
+
+/** One line telling a caller how to get past a lookup that did not yield a single live server. */
+export function describeLookup(
+  lookup: Exclude<DevServerLookup, { status: "live" }>,
+  cwd: string,
+): string {
+  switch (lookup.status) {
+    case "invalid-port":
+      return "port must be an integer from 1 to 65535."
+    case "unverified":
+      return `No ${DEV_SERVER_RECORD_FILE} under ${cwd} names port ${lookup.port}. Pass \`dir\` (the project that server runs) so its token can be read.`
+    case "ambiguous":
+      return `${lookup.servers.length} dev servers are running: ${lookup.servers.map((s) => `${s.root} (:${s.port})`).join(", ")}. Pass \`dir\` or \`port\` to pick one.`
+    case "down": {
+      const parts: string[] = []
+      for (const server of lookup.dead)
+        parts.push(
+          `the dev server for ${server.root} (:${server.port}, pid ${server.pid}) is gone without cleaning up - it crashed or was killed`,
+        )
+      for (const server of lookup.unreachable)
+        parts.push(
+          `the dev server for ${server.root} (:${server.port}) did not answer: ${server.reason}`,
+        )
+      if (parts.length === 0)
+        parts.push(`no nifra dev server is running for ${cwd}; start one with \`nifra dev\``)
+      return `${parts.join("; ")}.`
+    }
+  }
+}

package/src/diff-tool.ts

@@ -8,9 +8,9 @@
  * The CI loop: commit a snapshot on main, run `nifra diff api-snapshot.json` on every PR, and an
  * accidental contract break (removed route, new required field, retyped response) fails the build
  * before it ships. Classification lives in `@nifrajs/core/diff` (direction-aware, fails closed);
- * this module only loads `backend.ts` and renders the result.
+ * this module only loads `backend/app.ts` and renders the result.
  *
- * Loads ONLY `backend.ts` - the API contract - so it works on an API-only project with no
+ * Loads ONLY `backend/app.ts` - the API contract - so it works on an API-only project with no
  * framework config or routes/ directory (unlike the eager `loadApp`).
  */
 
@@ -23,6 +23,7 @@ import {
   type RoutesDiff,
   snapshotRoutes,
 } from "@nifrajs/core/diff"
+import { BACKEND_APP_FILE } from "./app-files.ts"
 
 /** Snapshot file envelope - versioned so a future format change can migrate instead of misparse. */
 export interface SnapshotFile {
@@ -81,12 +82,12 @@ export function formatDiff(diff: RoutesDiff): string {
   return `${lines.join("\n")}\n\n${summary}`
 }
 
-/** Import `backend.ts` from `cwd` and snapshot its routes. */
+/** Import `backend/app.ts` from `cwd` and snapshot its routes. */
 export async function snapshotBackend(cwd: string): Promise<readonly RouteSnapshot[]> {
-  const backendPath = resolve(cwd, "backend.ts")
+  const backendPath = resolve(cwd, BACKEND_APP_FILE)
   if (!existsSync(backendPath)) {
     throw new Error(
-      `[nifra] no backend.ts in ${cwd} - \`nifra snapshot\`/\`nifra diff\` compare the API contract, which lives in backend.ts.`,
+      `[nifra] no backend/app.ts in ${cwd} - \`nifra snapshot\`/\`nifra diff\` compare the API contract, which lives in backend/app.ts.`,
     )
   }
   const backend = ((await import(backendPath)) as { backend?: unknown }).backend

package/src/docs-search.ts

@@ -10,7 +10,7 @@
  * embedding infra would be complexity without a payoff.
  */
 
-import { countBodyHits, queryTermGroups, tokenize, tokenSetHas } from "./search-terms.ts"
+import { countBodyHits, queryTermGroups, tokenize, tokenSetScore } from "./search-terms.ts"
 
 export interface DocSection {
   readonly heading: string
@@ -83,10 +83,17 @@ export function searchSections(
     const prepared =
       "headingTokens" in section && "bodyLower" in section ? section : prepareSection(section)
     let score = 0
+    let matchedTerms = 0
     for (const term of terms) {
-      if (tokenSetHas(prepared.headingTokens, term)) score += 8
-      score += countBodyHits(prepared.bodyLower, term, 5)
+      const headingScore = tokenSetScore(prepared.headingTokens, term)
+      if (headingScore > 0) score += 8 + headingScore * 12
+      const bodyHits = countBodyHits(prepared.bodyLower, term, 5)
+      if (headingScore > 0 || bodyHits > 0) matchedTerms += 1
+      score += bodyHits
     }
+    // A result that matches every query concept should beat a section that only happens to repeat
+    // one highly frequent word, even when that single word appears in a curated heading.
+    score += matchedTerms * 26
     if (score > 0) scored.push({ heading: section.heading, body: section.body, score })
   }
   return scored.sort((a, b) => b.score - a.score).slice(0, limit)

package/src/doctor.ts

@@ -19,7 +19,7 @@
 import type { Dirent } from "node:fs"
 import { readdir, stat } from "node:fs/promises"
 import { builtinModules } from "node:module"
-import { dirname, join, relative, sep } from "node:path"
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
 import {
   collectIdentityParity,
   displayPath,
@@ -29,7 +29,9 @@ 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 { collectStaleMcpPins, type StaleMcpPin } from "./init-agents.ts"
+import { codeUnitOrder } from "./internal/code-unit-order.ts"
+import { detectToolingDrift, syncMcpCommand, type ToolingDrift } from "./mcp-root.ts"
 import { collectPipelineReport, type PipelineReport } from "./pipeline-report.ts"
 import { type ResolvedTarget, resolveTarget } from "./port.ts"
 import { buildScriptName } from "./workspace-link.ts"
@@ -46,8 +48,10 @@ const BUILTINS: ReadonlySet<string> = new Set<string>([
 // import, and CJS require. Anchored with `(?<![.\w$])` so `myimport`/`.import`/`foorequire` never match.
 // Comments are stripped before these run (see stripComments) - else a doc-comment usage example would be
 // flagged as a real import.
+// The clause before `from` is spelled out rather than scanned lazily: a lazy scan restarts at every
+// `export const` line and is quadratic on a long module with no string literal.
 const IMPORT_PATTERNS: readonly RegExp[] = [
-  /(?<![.\w$])(?:import|export)\b[^'"]*?\bfrom\s*['"]([^'"]+)['"]/g,
+  /(?<![.\w$])(?:import|export)\b\s*(?:type\b\s*)?(?:[\w$]+\s*,?\s*)?(?:\*\s*(?:as\b\s*[\w$]+\s*)?|\{[^{}'"]*\}\s*)?from\s*['"]([^'"]+)['"]/g,
   /(?<![.\w$])import\s+['"]([^'"]+)['"]/g,
   /(?<![.\w$])import\s*\(\s*['"]([^'"]+)['"]/g,
   /(?<![.\w$])require\s*\(\s*['"]([^'"]+)['"]/g,
@@ -126,7 +130,7 @@ export function scanUndeclaredImports(
       out.push({ file, line, snippet: pkg })
     }
   }
-  return out.sort((a, b) => a.line - b.line || a.snippet.localeCompare(b.snippet))
+  return out.sort((a, b) => a.line - b.line || codeUnitOrder(a.snippet, b.snippet))
 }
 
 export interface DoctorFinding {
@@ -174,8 +178,16 @@ export interface DoctorResult {
    * supplied and the feature versions disagree. Computed by {@link detectToolingDrift}.
    */
   readonly toolingDrift?: ToolingDrift
+  /**
+   * Agent files whose MCP launch pins an `@nifrajs/cli` other than the one the project installs, so
+   * the agent's server answers for a release the code no longer builds with. Advisory (never folded
+   * into `ok`). Present only when at least one file is stale. Computed by {@link collectStaleMcpPins}.
+   */
+  readonly staleMcpPins?: { readonly target: string; readonly files: readonly StaleMcpPin[] }
   /** Static production-readiness evidence for the selected deploy target. */
   readonly readiness?: DoctorReadiness
+  /** The explicit source boundary used by the dependency scan. */
+  readonly scanScope?: DoctorScanScope
   /**
    * Which bundler this app's `dev`/`build` phases run on, read statically, plus the config hazards
    * that exist only because there are two. Absent when the directory is not a nifra app.
@@ -191,6 +203,12 @@ export interface DoctorResult {
   readonly skippedFixes?: readonly DoctorSkippedFix[]
 }
 
+export interface DoctorScanScope {
+  readonly kind: "standalone" | "workspace-production"
+  readonly includeTests: boolean
+  readonly excluded: readonly string[]
+}
+
 export type DoctorReadinessStatus = "configured" | "absent" | "not-applicable"
 
 export interface DoctorReadinessItem {
@@ -577,7 +595,7 @@ export async function collectStaleWorkspaceDists(
       if (worst !== undefined) findings.push(worst)
     }
   }
-  return findings.sort((a, b) => a.package.localeCompare(b.package))
+  return findings.sort((a, b) => codeUnitOrder(a.package, b.package))
 }
 
 interface ReadinessSource {
@@ -615,7 +633,7 @@ async function collectDoctorReadiness(
   await walkSource(cwd, (file, source) => {
     files.push({ file, source, code: codePositionMask(source) })
   })
-  const edgeTarget = /^(?:cf-pages|vercel|workers|edge|static)$/.test(resolved?.target ?? "")
+  const edgeTarget = /^(?:cloudflare|vercel|workers|edge|static)$/.test(resolved?.target ?? "")
   const configured = (
     id: DoctorReadinessItem["id"],
     label: string,
@@ -705,13 +723,27 @@ async function ancestorDependencySpec(cwd: string, name: string): Promise<string
     const pkg = await readJson(join(dir, "package.json"))
     if (pkg !== undefined) {
       const spec = dependencySpec(pkg, name)
-      if (spec !== undefined) return spec
+      if (spec !== undefined) return rebaseDependencySpec(spec, dir, cwd)
     }
     const parent = dirname(dir)
     if (parent === dir) return undefined
   }
 }
 
+/**
+ * A path spec (`file:packages/x`, `link:../x`, `./vendor/x.tgz`) resolves against the package.json
+ * that declares it, so a spec copied from an ancestor is re-pointed to the same target from `cwd`.
+ */
+function rebaseDependencySpec(spec: string, declaredIn: string, cwd: string): string {
+  const protocol = /^(?:file|link|portal):/.exec(spec)?.[0] ?? ""
+  const path = spec.slice(protocol.length)
+  const relativePath =
+    protocol === "" ? /^\.\.?(?:[\\/]|$)/.test(path) : !isAbsolute(path) && !path.startsWith("~")
+  if (!relativePath) return spec
+  const rebased = relative(cwd, resolve(declaredIn, path)).replaceAll("\\", "/")
+  return protocol + (rebased === ".." || rebased.startsWith("../") ? rebased : `./${rebased}`)
+}
+
 async function installedPackageSpec(cwd: string, name: string): Promise<string | undefined> {
   if (!isNpmPackageName(name)) return undefined
   const parts = name.split("/")
@@ -751,9 +783,29 @@ export async function collectDoctorResult(
   const scopes = await doctorPackageScopes(cwd, pkg)
 
   const findings: DoctorFinding[] = []
-  // `includeTests`: tests are part of the typechecked surface, so an import they declare nowhere is a
-  // real break. Excluding them is what let an undeclared `zod` in a `*.test.ts` pass doctor, pass a
-  // hoisted local `tsc`, and then fail CI on a clean install with `TS2307: Cannot find module 'zod'`.
+  // A standalone app owns its tests, so they remain in the declaration check. A workspace root owns
+  // the published package source while its root devDependencies intentionally own shared tests,
+  // benchmarks, and scaffold copy-surfaces. Keep that boundary explicit instead of reporting a
+  // monorepo-wide false failure or silently dropping files from the result.
+  const workspaceProduction = workspacePatterns(pkg).length > 0
+  const scanScope: DoctorScanScope = Object.freeze({
+    kind: workspaceProduction ? "workspace-production" : "standalone",
+    includeTests: !workspaceProduction,
+    excluded: workspaceProduction
+      ? Object.freeze([
+          "**/test/**",
+          "**/test-node/**",
+          "bench/**",
+          "packages/create-nifra/template*/**",
+        ])
+      : Object.freeze([]),
+  })
+  const workspaceSurface = (rel: string): boolean =>
+    workspaceProduction &&
+    (/(^|\/)(?:test|test-node)\//.test(rel) ||
+      rel === "bench" ||
+      rel.startsWith("bench/") ||
+      rel.startsWith("packages/create-nifra/template"))
   await walkSource(
     cwd,
     (rel, content) => {
@@ -762,9 +814,9 @@ export async function collectDoctorResult(
         findings.push({ file: f.file, line: f.line, package: f.snippet })
       }
     },
-    { includeTests: true },
+    { includeTests: scanScope.includeTests, ignore: workspaceSurface },
   )
-  findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line)
+  findings.sort((a, b) => codeUnitOrder(a.file, b.file) || a.line - b.line)
   const identity = await collectAllDuplicateInstalls(cwd, pkg)
   const duplicateInstalls = identity.duplicates
   const staleDists = await collectStaleWorkspaceDists(cwd, pkg)
@@ -776,7 +828,8 @@ export async function collectDoctorResult(
   // 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`.
+  const staleMcpPins = await collectStaleMcpPins(cwd).catch(() => undefined)
+  // `staleDists`, `toolingDrift` and `staleMcpPins` are advisory (see DoctorResult): they never fail `ok`.
   return {
     ok:
       findings.length === 0 &&
@@ -791,7 +844,9 @@ export async function collectDoctorResult(
     ...(identity.truncated ? { identityScanTruncated: true } : {}),
     staleDists,
     readiness,
+    scanScope,
     ...(toolingDrift !== undefined ? { toolingDrift } : {}),
+    ...(staleMcpPins !== undefined && staleMcpPins.files.length > 0 ? { staleMcpPins } : {}),
     ...(pipeline.ran ? { pipeline } : {}),
   }
 }
@@ -817,7 +872,7 @@ export async function applyDoctorAutoFix(
 
   const fixed: DoctorAppliedFix[] = []
   const skippedFixes: DoctorSkippedFix[] = []
-  for (const [root, names] of [...byRoot.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+  for (const [root, names] of [...byRoot.entries()].sort(([a], [b]) => codeUnitOrder(a, b))) {
     const pkgPath = join(root, "package.json")
     const pkg = await readJson(pkgPath)
     if (pkg === undefined) continue
@@ -922,6 +977,14 @@ export async function runDoctor(
       console.log(`      fix: ${f.fix}\n`)
     }
   }
+  if (result.scanScope !== undefined) {
+    console.log(
+      `• dependency scan scope: ${result.scanScope.kind} (${result.scanScope.includeTests ? "includes tests" : "production package source only"})`,
+    )
+    if (result.scanScope.excluded.length > 0)
+      console.log(`  excluded: ${result.scanScope.excluded.join(", ")}`)
+    console.log("")
+  }
   // Advisory, printed regardless of ok: a stale linked dist doesn't fail doctor, but silently eating
   // it costs an hour of misdiagnosis when the dev server 500s inside the package.
   if (result.staleDists.length > 0) {
@@ -963,10 +1026,28 @@ export async function runDoctor(
         "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, " +
+      `      fix: \`${syncMcpCommand(drift.cli)}\` re-pins the project's MCP launch to the nifra it installs; ` +
+        "for the CLI itself, run the project's own (`bunx --bun nifra doctor` from the project directory, " +
         "or ./node_modules/.bin/nifra)\n",
     )
   }
+  // Advisory: the agent's MCP server is launched from these pins, so a stale one answers for an old
+  // release even when the CLI running doctor matches the project.
+  if (result.staleMcpPins !== undefined) {
+    const { target, files } = result.staleMcpPins
+    console.log(
+      `⚠ the MCP launch pins a nifra other than the project's ${target} - an agent's nifra server answers for that release:`,
+    )
+    for (const file of files)
+      console.log(`    ${file.path}: @nifrajs/cli@${file.pinned.join(", ")}`)
+    const command =
+      opts.cliVersion !== undefined
+        ? syncMcpCommand(opts.cliVersion)
+        : "nifra init-agents --sync-mcp"
+    console.log(
+      `      fix: \`${command}\` rewrites only the pinned version, then restart the agent\n`,
+    )
+  }
   if (result.ok) {
     console.log(
       "✓ every imported package is declared and identity-sensitive installs are deduplicated",
@@ -1007,6 +1088,8 @@ export async function runDoctor(
         console.log(`      ${copy.version} at ${copy.path} ← ${copy.importers.join(", ")}`)
       }
       console.log(`      ${finding.explanation}`)
+      // A planted symlink is the cause no reinstall here can see, so it is named before the fix.
+      if (finding.provenance !== undefined) console.log(`      links: ${finding.provenance}`)
       // The shape of the split decides which fix can work, so it is printed above the fix itself.
       if (finding.topology !== undefined) console.log(`      topology: ${finding.topology}`)
       // Why a copy this directory never imports still counts. Without it, a workspace-wide answer

package/src/env-file.ts

@@ -15,7 +15,7 @@
  *   - A missing file is an error, never a silent no-op. `--env-file .env.prod` that quietly did nothing
  *     would make the command look like it verified an environment it never loaded.
  */
-import { readFile } from "node:fs/promises"
+import { readdir, readFile } from "node:fs/promises"
 import { resolve } from "node:path"
 
 const ENV_FILE_FLAG = "--env-file"
@@ -119,3 +119,80 @@ export async function applyEnvFiles(
   }
   return applied
 }
+
+/**
+ * Remove from `process.env` what Bun loaded from the `.env` files in `cwd` when this process started,
+ * keeping every variable the environment itself set. Returns the names removed. `nifra mcp` runs it
+ * first and, when anything was removed, serves from a `bun --no-env-file` copy of itself given the
+ * result: Bun hands the values it loaded to every subprocess whatever `process.env` says later. The
+ * server is long-lived and runs no project code, so it holds none of the project's `.env`; the project
+ * subprocesses it starts load those files again themselves.
+ *
+ * Bun applies the files under the environment (a variable already set wins) and expands `${NAME}`
+ * references, so Bun itself says which values came from a file: a subprocess with an empty
+ * environment reports what the files add to it, and a variable with that value is removed. A value that
+ * differs is asked again with the rest of the environment, for an expansion that read it; one that
+ * still differs was set by the environment, and stays.
+ */
+export async function forgetAutoLoadedEnv(cwd = process.cwd()): Promise<readonly string[]> {
+  const names = await readdir(cwd).catch(() => [])
+  if (!names.some((name) => name.startsWith(".env"))) return []
+  const mode = process.env.NODE_ENV
+  const fromFiles = await envFromFiles(cwd, mode === undefined ? {} : { NODE_ENV: mode })
+  const removed: string[] = []
+  const differing: string[] = []
+  for (const [name, value] of Object.entries(fromFiles)) {
+    if (name === "NODE_ENV" || process.env[name] === undefined) continue
+    if (process.env[name] === value) removed.push(name)
+    else differing.push(name)
+  }
+  if (differing.length > 0) {
+    const rest = { ...process.env }
+    for (const name of differing) delete rest[name]
+    const expanded = await envFromFiles(cwd, rest)
+    for (const name of differing) if (process.env[name] === expanded[name]) removed.push(name)
+  }
+  for (const name of removed) delete process.env[name]
+  return removed
+}
+
+/** What the `.env` files in `cwd` add to a Bun process started there with `env`. */
+async function envFromFiles(
+  cwd: string,
+  env: Record<string, string | undefined>,
+): Promise<Record<string, string>> {
+  // A child holds more than `env`: Windows copies PATH, SYSTEMROOT and a few more from the parent,
+  // and a bunfig preload can set others. A `--no-env-file` copy of the child holds those as well.
+  const [loaded, bare] = await Promise.all([
+    childEnv(cwd, env, []),
+    childEnv(cwd, env, ["--no-env-file"]),
+  ])
+  const added: Record<string, string> = {}
+  for (const [name, value] of Object.entries(loaded)) if (bare[name] !== value) added[name] = value
+  return added
+}
+
+/** What `process.env` holds in a Bun process started in `cwd` with `env` and the runtime `flags`. */
+async function childEnv(
+  cwd: string,
+  env: Record<string, string | undefined>,
+  flags: readonly string[],
+): Promise<Record<string, string>> {
+  const proc = Bun.spawn(
+    [process.execPath, ...flags, "-e", "process.stdout.write(JSON.stringify(process.env))"],
+    { cwd, env, stdin: "ignore", stdout: "pipe", stderr: "ignore" },
+  )
+  const [text] = await Promise.all([new Response(proc.stdout).text(), proc.exited])
+  let value: unknown
+  try {
+    value = JSON.parse(text)
+  } catch {
+    return {}
+  }
+  if (typeof value !== "object" || value === null) return {}
+  return Object.fromEntries(
+    Object.entries(value).filter(
+      (entry): entry is [string, string] => typeof entry[1] === "string",
+    ),
+  )
+}