@nifrajs/cli 2.11.0 → 2.12.1

package/src/contracts.ts

@@ -0,0 +1,157 @@
+import { existsSync } from "node:fs"
+import { resolve } from "node:path"
+import { type ReflectedRoute, reflectRoutes } from "@nifrajs/core/reflection"
+
+export interface ContractDigest {
+  readonly request: string
+  readonly response: string
+}
+
+export interface ContractsLock {
+  readonly version: 1
+  readonly routes: Readonly<Record<string, ContractDigest>>
+}
+
+export const DEFAULT_CONTRACTS_LOCK = "contracts.lock.json"
+const DIGEST = /^[a-f0-9]{64}$/
+
+function recordOf(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? Object.fromEntries(Object.entries(value))
+    : undefined
+}
+
+function canonical(value: unknown, key?: string): unknown {
+  if (["description", "title", "default", "example", "examples"].includes(key ?? ""))
+    return undefined
+  if (Array.isArray(value)) return value.map((item) => canonical(item))
+  const record = recordOf(value)
+  if (record === undefined) return value
+  const out: Record<string, unknown> = {}
+  for (const name of Object.keys(record).sort()) {
+    const item = canonical(record[name], name)
+    if (item !== undefined) out[name] = item
+  }
+  return out
+}
+
+async function sha256(value: string): Promise<string> {
+  const bytes = new TextEncoder().encode(value)
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes))
+  return [...digest].map((item) => item.toString(16).padStart(2, "0")).join("")
+}
+
+function schemaValue(route: ReflectedRoute, side: "request" | "response"): unknown {
+  const schema = route.schema
+  if (schema === undefined) return {}
+  if (side === "request") {
+    return {
+      body: schema.body?.jsonSchema ?? schema.body?.fields ?? null,
+      query: schema.query?.jsonSchema ?? schema.query?.fields ?? null,
+      params: schema.params?.jsonSchema ?? schema.params?.fields ?? null,
+    }
+  }
+  return {
+    response: schema.response?.jsonSchema ?? schema.response?.fields ?? null,
+    sse: schema.sse?.jsonSchema ?? schema.sse?.fields ?? null,
+    errors: Object.fromEntries(
+      Object.entries(schema.errors ?? {}).map(([status, value]) => [
+        status,
+        value.jsonSchema ?? value.fields ?? null,
+      ]),
+    ),
+  }
+}
+
+export async function digestRoute(route: ReflectedRoute): Promise<ContractDigest> {
+  const request = JSON.stringify(canonical(schemaValue(route, "request")))
+  const response = JSON.stringify(canonical(schemaValue(route, "response")))
+  return { request: await sha256(request), response: await sha256(response) }
+}
+
+export async function buildContractsLock(source: unknown): Promise<ContractsLock> {
+  const routes = Object.fromEntries(
+    await Promise.all(
+      reflectRoutes(source).map(
+        async (route) => [`${route.method} ${route.path}`, await digestRoute(route)] as const,
+      ),
+    ),
+  )
+  return {
+    version: 1,
+    routes: Object.fromEntries(Object.entries(routes).sort(([a], [b]) => a.localeCompare(b))),
+  }
+}
+
+async function loadBackend(cwd: string): Promise<unknown> {
+  const backendPath = resolve(cwd, "backend.ts")
+  if (!existsSync(backendPath)) throw new Error(`[nifra] no backend.ts in ${cwd}`)
+  const loadedValue: unknown = await import(backendPath)
+  const loaded = recordOf(loadedValue)
+  if (loaded?.backend === undefined)
+    throw new Error(`[nifra] ${backendPath} does not export backend`)
+  return loaded.backend
+}
+
+export async function snapshotContracts(
+  cwd: string,
+  out = DEFAULT_CONTRACTS_LOCK,
+): Promise<ContractsLock> {
+  const lock = await buildContractsLock(await loadBackend(cwd))
+  await Bun.write(resolve(cwd, out), `${JSON.stringify(lock, null, 2)}\n`)
+  return lock
+}
+
+export function parseContractsLock(value: unknown): ContractsLock {
+  const record = recordOf(value)
+  if (record === undefined) throw new TypeError("contracts lock must be an object")
+  const routesValue = record.routes
+  const routesRecord = recordOf(routesValue)
+  if (record.version !== 1 || routesRecord === undefined)
+    throw new TypeError("contracts lock must have version 1 and routes")
+  const routes: Record<string, ContractDigest> = {}
+  for (const [key, raw] of Object.entries(routesRecord)) {
+    const item = recordOf(raw)
+    const request = item?.request
+    const response = item?.response
+    if (
+      request === undefined ||
+      typeof request !== "string" ||
+      response === undefined ||
+      typeof response !== "string" ||
+      !DIGEST.test(request) ||
+      !DIGEST.test(response)
+    )
+      throw new TypeError(`invalid contract ${key}`)
+    routes[key] = { request, response }
+  }
+  return { version: 1, routes }
+}
+
+export async function checkContractsLock(
+  cwd: string,
+  file = DEFAULT_CONTRACTS_LOCK,
+): Promise<{ present: boolean; diagnostics: Array<{ route?: string; message: string }> }> {
+  const path = resolve(cwd, file)
+  if (!existsSync(path)) return { present: false, diagnostics: [] }
+  const parsed = parseContractsLock(JSON.parse(await Bun.file(path).text()))
+  const current = await buildContractsLock(await loadBackend(cwd))
+  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()) {
+    const before = parsed.routes[key]
+    const after = current.routes[key]
+    if (
+      before === undefined ||
+      after === undefined ||
+      before.request !== after.request ||
+      before.response !== after.response
+    ) {
+      diagnostics.push({
+        route: key,
+        message: `contract changed for ${key}; if intentional run \`nifra contracts snapshot\` and include the lock update in the same change.`,
+      })
+    }
+  }
+  return { present: true, diagnostics }
+}

package/src/diagnostics.ts

@@ -0,0 +1,32 @@
+/** Stable, machine-actionable diagnostics shared by CLI gates and MCP renderers. */
+
+export type Severity = "error" | "warn" | "info"
+
+export interface DiagnosticFix {
+  readonly recipe: string
+  readonly command?: string
+}
+
+export interface Diagnostic {
+  /** Stable forever. Never renumber or reuse. */
+  readonly code: string
+  readonly severity: Severity
+  readonly message: string
+  readonly file?: string
+  readonly line?: number
+  /** Short evidence strings that help an agent act without exposing payloads. */
+  readonly evidence?: readonly string[]
+  readonly fix?: DiagnosticFix
+  /** Command that proves the fix worked. */
+  readonly verify?: string
+}
+
+export const diagnostic = (value: Diagnostic): Diagnostic => Object.freeze(value)
+
+export function severityFails(severity: Severity, strict = false): boolean {
+  return severity === "error" || (strict && severity === "warn")
+}
+
+export function normalizeSeverity(value: "error" | "warning" | "warn" | "info"): Severity {
+  return value === "warning" ? "warn" : value
+}

package/src/diff-tool.ts

@@ -82,7 +82,7 @@ export function formatDiff(diff: RoutesDiff): string {
 }
 
 /** Import `backend.ts` from `cwd` and snapshot its routes. */
-async function snapshotBackend(cwd: string): Promise<readonly RouteSnapshot[]> {
+export async function snapshotBackend(cwd: string): Promise<readonly RouteSnapshot[]> {
   const backendPath = resolve(cwd, "backend.ts")
   if (!existsSync(backendPath)) {
     throw new Error(

package/src/docs-search.ts

@@ -17,6 +17,13 @@ export interface DocSection {
   readonly body: string
 }
 
+export interface PreparedDocSection extends DocSection {
+  readonly headingTokens: ReadonlySet<string>
+  readonly bodyLower: string
+}
+
+const sectionCache = new Map<string, readonly PreparedDocSection[]>()
+
 /** Split the generated doc into its `##` sections (the `# title` intro becomes "Overview"). */
 export function splitSections(markdown: string): DocSection[] {
   const out: DocSection[] = []
@@ -40,6 +47,23 @@ export function splitSections(markdown: string): DocSection[] {
   return out
 }
 
+function prepareSection(section: DocSection): PreparedDocSection {
+  return {
+    ...section,
+    headingTokens: new Set(tokenize(section.heading)),
+    bodyLower: section.body.toLowerCase(),
+  }
+}
+
+/** Return the immutable-build section parse and derived search fields from the process cache. */
+export function getCachedDocSections(markdown: string): readonly PreparedDocSection[] {
+  const cached = sectionCache.get(markdown)
+  if (cached !== undefined) return cached
+  const prepared = splitSections(markdown).map(prepareSection)
+  sectionCache.set(markdown, prepared)
+  return prepared
+}
+
 export interface ScoredSection extends DocSection {
   readonly score: number
 }
@@ -48,7 +72,7 @@ export interface ScoredSection extends DocSection {
  * (headings are curated names for exactly these lookups); body occurrences cap per term so one
  * spammy section can't drown a precisely-titled one. */
 export function searchSections(
-  sections: readonly DocSection[],
+  sections: readonly (DocSection | PreparedDocSection)[],
   query: string,
   limit: number,
 ): ScoredSection[] {
@@ -56,14 +80,14 @@ export function searchSections(
   if (terms.length === 0) return []
   const scored: ScoredSection[] = []
   for (const section of sections) {
-    const headingTokens = new Set(tokenize(section.heading))
-    const bodyLower = section.body.toLowerCase()
+    const prepared =
+      "headingTokens" in section && "bodyLower" in section ? section : prepareSection(section)
     let score = 0
     for (const term of terms) {
-      if (tokenSetHas(headingTokens, term)) score += 8
-      score += countBodyHits(bodyLower, term, 5)
+      if (tokenSetHas(prepared.headingTokens, term)) score += 8
+      score += countBodyHits(prepared.bodyLower, term, 5)
     }
-    if (score > 0) scored.push({ ...section, score })
+    if (score > 0) scored.push({ heading: section.heading, body: section.body, score })
   }
   return scored.sort((a, b) => b.score - a.score).slice(0, limit)
 }
@@ -78,7 +102,7 @@ export function renderDocsResult(
   query: string | undefined,
   limit: number,
 ): string {
-  const sections = splitSections(markdown)
+  const sections = getCachedDocSections(markdown)
   if (query === undefined || query.trim() === "") {
     const index = sections.map((s) => `- ${s.heading}`).join("\n")
     return `# nifra docs - section index (pass \`query\` to fetch matching sections)\n\n${index}`
@@ -100,12 +124,18 @@ export function renderDocsResult(
 
 /** Load the bundled corpus. Resolves relative to this module so it works from `src/` (repo dev)
  * and `dist/` (published) alike - `docs/llms-full.txt` sits at the package root next to both. */
-export async function loadDocsCorpus(): Promise<string | undefined> {
-  const url = new URL("../docs/llms-full.txt", import.meta.url)
-  try {
-    const text = await Bun.file(url).text()
-    return text.length > 0 ? text : undefined
-  } catch {
-    return undefined
-  }
+let docsCorpusPromise: Promise<string | undefined> | undefined
+
+/** The published corpus is immutable, so one read and one parsed-section cache are sufficient. */
+export function loadDocsCorpus(): Promise<string | undefined> {
+  docsCorpusPromise ??= (async () => {
+    const url = new URL("../docs/llms-full.txt", import.meta.url)
+    try {
+      const text = await Bun.file(url).text()
+      return text.length > 0 ? text : undefined
+    } catch {
+      return undefined
+    }
+  })()
+  return docsCorpusPromise
 }

package/src/doctor.ts

@@ -17,11 +17,12 @@
  * undeclared import there fails a clean `bun install --frozen-lockfile` build just the same.
  */
 import type { Dirent } from "node:fs"
-import { readdir, realpath, stat } from "node:fs/promises"
+import { lstat, readdir, realpath, stat } from "node:fs/promises"
 import { builtinModules } from "node:module"
 import { dirname, join, relative, sep } from "node:path"
 import { codePositionMask, type SourceFinding, stripComments, walkSource } from "./check.ts"
 import { collectPipelineReport, type PipelineReport } from "./pipeline-report.ts"
+import { type ResolvedTarget, resolveTarget } from "./port.ts"
 
 // Runtime-provided modules that are never an npm dependency: Node core (bare + `node:` form) and Bun's
 // own `bun` module. `node:`/`bun:`-prefixed specifiers are filtered in packageOf by prefix.
@@ -136,6 +137,8 @@ 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[]
+  /** Static production-readiness evidence for the selected deploy target. */
+  readonly readiness?: DoctorReadiness
   /**
    * 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.
@@ -151,6 +154,30 @@ export interface DoctorResult {
   readonly skippedFixes?: readonly DoctorSkippedFix[]
 }
 
+export type DoctorReadinessStatus = "configured" | "absent" | "not-applicable"
+
+export interface DoctorReadinessItem {
+  readonly id:
+    | "request-timeout"
+    | "admission"
+    | "request-id-tracing"
+    | "health-route"
+    | "log-redaction"
+    | "graceful-lifecycle"
+  readonly label: string
+  readonly status: DoctorReadinessStatus
+  readonly evidence?: string
+}
+
+export interface DoctorReadiness {
+  readonly target: string
+  readonly targetSource: ResolvedTarget["source"] | null
+  readonly strict: boolean
+  /** True when every applicable rule has static evidence. */
+  readonly ok: boolean
+  readonly items: readonly DoctorReadinessItem[]
+}
+
 export interface DuplicateInstallCopy {
   /** Installed version, or `unknown` when package metadata is incomplete. */
   readonly version: string
@@ -352,6 +379,66 @@ async function resolvedInstalledCopy(
   }
 }
 
+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
@@ -464,6 +551,28 @@ export async function collectDuplicateInstalls(
     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,
+  )
+  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
@@ -631,6 +740,110 @@ export async function collectStaleWorkspaceDists(
   return findings.sort((a, b) => a.package.localeCompare(b.package))
 }
 
+interface ReadinessSource {
+  readonly file: string
+  readonly code: string
+  readonly source: string
+}
+
+function sourceLineAt(source: string, index: number): number {
+  let line = 1
+  for (let i = 0; i < index && i < source.length; i++) if (source[i] === "\n") line++
+  return line
+}
+
+function readinessEvidence(
+  files: readonly ReadinessSource[],
+  pattern: RegExp,
+  source = "code",
+): string | undefined {
+  for (const file of files) {
+    const content = source === "source" ? file.source : file.code
+    const match = pattern.exec(content)
+    if (match !== null) return `${file.file}:${sourceLineAt(content, match.index)}`
+  }
+  return undefined
+}
+
+/** Read only source shapes used to report production readiness. Values and secrets are never loaded. */
+async function collectDoctorReadiness(
+  cwd: string,
+  opts: { readonly target?: string; readonly strict?: boolean },
+): Promise<DoctorReadiness> {
+  const resolved = await resolveTarget(cwd, opts.target)
+  const files: ReadinessSource[] = []
+  await walkSource(cwd, (file, source) => {
+    files.push({ file, source, code: codePositionMask(source) })
+  })
+  const edgeTarget = /^(?:cf-pages|vercel|workers|edge|static)$/.test(resolved?.target ?? "")
+  const configured = (
+    id: DoctorReadinessItem["id"],
+    label: string,
+    pattern: RegExp,
+    sourcePattern?: RegExp,
+  ): DoctorReadinessItem => {
+    const evidence = readinessEvidence(files, pattern)
+    const routeEvidence =
+      evidence === undefined && sourcePattern !== undefined
+        ? readinessEvidence(files, sourcePattern, "source")
+        : undefined
+    const found = evidence ?? routeEvidence
+    return found === undefined
+      ? { id, label, status: "absent" }
+      : { id, label, status: "configured", evidence: found }
+  }
+
+  const items: DoctorReadinessItem[] = [
+    configured(
+      "request-timeout",
+      "request timeout or budget",
+      /\b(?:requestTimeoutMs|createRequestBudget|admitDeadline)\s*[:(]/,
+    ),
+    // `admission: controller`, the shorthand `{ admission }` (trailing comma or closing brace), or
+    // the documented constructor call - shorthand is the idiomatic form when the controller is an
+    // import or module const.
+    configured(
+      "admission",
+      "capacity admission",
+      /\badmission\s*[:,}]|\bcreateAdmissionController\s*\(/,
+    ),
+    configured(
+      "request-id-tracing",
+      "request id or tracing middleware",
+      /\b(?:requestId|tracing)\s*\(/,
+    ),
+    configured(
+      "health-route",
+      "health route",
+      /\bhealthcheck\s*\(/,
+      // Conventional health paths: /health, /healthz (the k8s form healthcheck() is most often
+      // configured to serve), /health-check, and the underscore-prefixed variants, each also
+      // matching as a prefix (`/health/live`). `/healthy` etc. stay non-matches: the path must end
+      // (closing quote) or continue with a segment right after the recognized name.
+      /\.(?:get|head)\s*\(\s*["']\/_?health(?:z|-check)?(?:["']|\/)/,
+    ),
+    // Asserts "a redacting logger is INSTALLED", so only the call forms count: the redacting
+    // constructors, or @nifrajs/middleware's `logger()` structured request logger (which logs only
+    // method/path/status/duration - nothing redactable). A bare `logger:` property proves nothing:
+    // `logger: console` matches it and redacts nothing.
+    configured("log-redaction", "log redaction", /\b(?:jsonLogger|redactLogFields|logger)\s*\(/),
+    edgeTarget
+      ? { id: "graceful-lifecycle", label: "graceful lifecycle", status: "not-applicable" }
+      : configured(
+          "graceful-lifecycle",
+          "graceful lifecycle",
+          /\bgracefulSignals\s*:\s*true\b|\bonStop\s*\(/,
+        ),
+  ]
+  return {
+    target: resolved?.target ?? "unknown",
+    targetSource: resolved?.source ?? null,
+    strict: opts.strict === true,
+    ok: items.every((item) => item.status !== "absent"),
+    items,
+  }
+}
+
 function depRecord(
   pkg: Record<string, unknown>,
   field: string,
@@ -687,7 +900,10 @@ async function inferDependencyFix(
 }
 
 /** Run doctor against the project at `cwd`: diff source imports vs declared deps. */
-export async function collectDoctorResult(cwd: string): Promise<DoctorResult> {
+export async function collectDoctorResult(
+  cwd: string,
+  opts: { readonly target?: string; readonly strict?: boolean } = {},
+): Promise<DoctorResult> {
   const pkg = await readJson(join(cwd, "package.json"))
   if (pkg === undefined)
     return { ok: true, ran: false, findings: [], duplicateInstalls: [], staleDists: [] }
@@ -713,20 +929,29 @@ export async function collectDoctorResult(cwd: string): Promise<DoctorResult> {
   const staleDists = await collectStaleWorkspaceDists(cwd, pkg)
   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`.
   return {
-    ok: findings.length === 0 && duplicateInstalls.length === 0 && pipelineErrors.length === 0,
+    ok:
+      findings.length === 0 &&
+      duplicateInstalls.length === 0 &&
+      pipelineErrors.length === 0 &&
+      (opts.strict !== true || readiness.ok),
     ran: true,
     findings,
     duplicateInstalls,
     staleDists,
+    readiness,
     ...(pipeline.ran ? { pipeline } : {}),
   }
 }
 
 /** Safely add undeclared imports to package.json when the version can be inferred without network I/O. */
-export async function applyDoctorAutoFix(cwd: string): Promise<DoctorResult> {
-  const before = await collectDoctorResult(cwd)
+export async function applyDoctorAutoFix(
+  cwd: string,
+  opts: { readonly target?: string; readonly strict?: boolean } = {},
+): Promise<DoctorResult> {
+  const before = await collectDoctorResult(cwd, opts)
   if (!before.ran || before.findings.length === 0) return before
 
   const rootPackage = await readJson(join(cwd, "package.json"))
@@ -787,7 +1012,7 @@ export async function applyDoctorAutoFix(cwd: string): Promise<DoctorResult> {
     if (changed) await Bun.write(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`)
   }
 
-  const after = fixed.length > 0 ? await collectDoctorResult(cwd) : before
+  const after = fixed.length > 0 ? await collectDoctorResult(cwd, opts) : before
   return {
     ...after,
     ...(fixed.length > 0 ? { fixed } : {}),
@@ -798,9 +1023,16 @@ export async function applyDoctorAutoFix(cwd: string): Promise<DoctorResult> {
 /** Run doctor; print a report (`--json` for machine output) and return whether it passed. */
 export async function runDoctor(
   cwd: string,
-  opts: { readonly json?: boolean; readonly autoFix?: boolean } = {},
+  opts: {
+    readonly json?: boolean
+    readonly autoFix?: boolean
+    readonly strict?: boolean
+    readonly target?: string
+  } = {},
 ): Promise<boolean> {
-  const result = opts.autoFix ? await applyDoctorAutoFix(cwd) : await collectDoctorResult(cwd)
+  const result = opts.autoFix
+    ? await applyDoctorAutoFix(cwd, opts)
+    : await collectDoctorResult(cwd, opts)
   if (opts.json) {
     console.log(JSON.stringify(result, null, 2))
     return result.ok
@@ -854,6 +1086,22 @@ export async function runDoctor(
     }
     console.log("")
   }
+  if (result.readiness !== undefined) {
+    const readiness = result.readiness
+    console.log(
+      `production readiness (${readiness.target}${readiness.targetSource === null ? "" : `, detected from ${readiness.targetSource}`}):\n`,
+    )
+    for (const item of readiness.items) {
+      const marker =
+        item.status === "configured" ? "✓" : item.status === "not-applicable" ? "-" : "✗"
+      const evidence = item.evidence === undefined ? "" : ` (${item.evidence})`
+      console.log(`  ${marker} ${item.label}: ${item.status}${evidence}`)
+    }
+    if (readiness.strict && !readiness.ok) {
+      console.log("\n  --strict: every applicable readiness rule must be configured")
+    }
+    console.log("")
+  }
   if (result.ok) {
     console.log(
       "✓ every imported package is declared and identity-sensitive installs are deduplicated",
@@ -896,6 +1144,9 @@ export async function runDoctor(
       "\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")
+  }
   if (byPkg.size > 0)
     console.log(
       "\nThese resolve at Bun runtime via hoisting/workspace but break `tsc` and a standalone install.",