@nifrajs/cli 3.3.0 → 4.0.0

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/diagnostics.ts

@@ -7,6 +7,32 @@ export interface DiagnosticFix {
   readonly command?: string
 }
 
+/**
+ * The richer compatibility view used by the original `nifra check` renderer. It is deliberately
+ * kept out of the enumerable diagnostic shape: SARIF, MCP structured output, and JSON consumers get
+ * the small stable diagnostic contract, while the legacy text view can still explain an exact edit.
+ */
+export interface DiagnosticCompatibility {
+  /** The pre-registry rule name used by the human/legacy check result. */
+  readonly rule: string
+  /** The old human-facing fix text, when the rule had one. */
+  readonly fix?: string
+  /** A richer legacy suggestion (diff, command, or manual steps). */
+  readonly suggestion?: DiagnosticSuggestion
+  /** The import path evidence used by the legacy server-only-import view. */
+  readonly chain?: readonly string[]
+  /** Preserve the old optional `CheckDiagnostic.code` field exactly where it existed. */
+  readonly includeCode?: boolean
+}
+
+export interface DiagnosticSuggestion {
+  readonly kind: "edit" | "command" | "manual"
+  readonly title: string
+  readonly diff?: string
+  readonly command?: readonly string[]
+  readonly steps?: readonly string[]
+}
+
 export interface Diagnostic {
   /** Stable forever. Never renumber or reuse. */
   readonly code: string
@@ -21,6 +47,159 @@ export interface Diagnostic {
   readonly verify?: string
 }
 
+const DIAGNOSTIC_COMPATIBILITY = Symbol("nifra.diagnosticCompatibility")
+
+/** Attach legacy-only rendering metadata without widening the serialized diagnostic protocol. */
+export function diagnosticWithCompatibility(
+  value: Diagnostic,
+  compatibility: DiagnosticCompatibility,
+): Diagnostic {
+  const result = { ...value }
+  Object.defineProperty(result, DIAGNOSTIC_COMPATIBILITY, {
+    value: Object.freeze({
+      ...compatibility,
+      ...(compatibility.chain === undefined
+        ? {}
+        : { chain: Object.freeze([...compatibility.chain]) }),
+    }),
+    enumerable: false,
+  })
+  return Object.freeze(result)
+}
+
+/** Read legacy-only rendering metadata. Undefined means the diagnostic has no compatibility view. */
+export function diagnosticCompatibilityOf(value: Diagnostic): DiagnosticCompatibility | undefined {
+  return (
+    value as Diagnostic & {
+      readonly [DIAGNOSTIC_COMPATIBILITY]?: DiagnosticCompatibility
+    }
+  )[DIAGNOSTIC_COMPATIBILITY]
+}
+
+/** The subset of SARIF 2.1.0 emitted by {@link toSarifLog}. */
+export interface SarifLog {
+  readonly $schema: "https://json.schemastore.org/sarif-2.1.0.json"
+  readonly version: "2.1.0"
+  readonly runs: readonly SarifRun[]
+}
+
+export interface SarifRun {
+  readonly tool: {
+    readonly driver: {
+      readonly name: string
+      readonly version?: string
+      readonly rules: readonly SarifRule[]
+    }
+  }
+  readonly results: readonly SarifResult[]
+}
+
+export interface SarifRule {
+  readonly id: string
+  readonly shortDescription: { readonly text: string }
+}
+
+export interface SarifResult {
+  readonly ruleId: string
+  readonly level: "error" | "warning" | "note"
+  readonly message: { readonly text: string }
+  readonly locations?: readonly SarifLocation[]
+  readonly properties?: Readonly<Record<string, string | readonly string[]>>
+}
+
+export interface SarifLocation {
+  readonly physicalLocation: {
+    readonly artifactLocation: {
+      readonly uri: string
+      readonly uriBaseId?: string
+    }
+    readonly region?: { readonly startLine: number }
+  }
+}
+
+export interface SarifProjectionOptions {
+  /** Name shown by external review tools in the SARIF run metadata. Defaults to `nifra`. */
+  readonly toolName?: string
+  /** Optional CLI/framework version shown by external review tools. */
+  readonly toolVersion?: string
+  /** Base URI identifier for relative diagnostic file paths. */
+  readonly uriBaseId?: string
+}
+
+function sarifLevel(severity: Severity): SarifResult["level"] {
+  return severity === "error" ? "error" : severity === "warn" ? "warning" : "note"
+}
+
+function sarifProperties(
+  value: Diagnostic,
+): Readonly<Record<string, string | readonly string[]>> | undefined {
+  const properties: Record<string, string | readonly string[]> = {}
+  if (value.evidence !== undefined && value.evidence.length > 0)
+    properties["nifra.evidence"] = [...value.evidence]
+  if (value.verify !== undefined) properties["nifra.verify"] = value.verify
+  if (value.fix !== undefined) {
+    properties["nifra.fix.recipe"] = value.fix.recipe
+    if (value.fix.command !== undefined) properties["nifra.fix.command"] = value.fix.command
+  }
+  return Object.keys(properties).length === 0 ? undefined : properties
+}
+
+/**
+ * Project stable Nifra diagnostics into SARIF for code-host and external review surfaces.
+ *
+ * This is deliberately a pure projection: it does not run checks, read files, or reinterpret policy.
+ * Relative file names remain relative so callers can choose the review tool's checkout base through
+ * {@link SarifProjectionOptions.uriBaseId}.
+ */
+export function toSarifLog(
+  diagnostics: readonly Diagnostic[],
+  options: SarifProjectionOptions = {},
+): SarifLog {
+  const rules = new Map<string, SarifRule>()
+  const results: SarifResult[] = []
+  for (const value of diagnostics) {
+    if (!rules.has(value.code)) {
+      rules.set(value.code, {
+        id: value.code,
+        shortDescription: { text: value.message },
+      })
+    }
+    const location =
+      value.file === undefined
+        ? undefined
+        : {
+            physicalLocation: {
+              artifactLocation: {
+                uri: value.file.replaceAll("\\", "/"),
+                ...(options.uriBaseId === undefined ? {} : { uriBaseId: options.uriBaseId }),
+              },
+              ...(value.line !== undefined && Number.isInteger(value.line) && value.line >= 1
+                ? { region: { startLine: value.line } }
+                : {}),
+            },
+          }
+    const properties = sarifProperties(value)
+    results.push({
+      ruleId: value.code,
+      level: sarifLevel(value.severity),
+      message: { text: value.message },
+      ...(location === undefined ? {} : { locations: [location] }),
+      ...(properties === undefined ? {} : { properties }),
+    })
+  }
+
+  const driver = {
+    name: options.toolName ?? "nifra",
+    ...(options.toolVersion === undefined ? {} : { version: options.toolVersion }),
+    rules: [...rules.values()],
+  }
+  return {
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    version: "2.1.0",
+    runs: [{ tool: { driver }, results }],
+  }
+}
+
 export const diagnostic = (value: Diagnostic): Diagnostic => Object.freeze(value)
 
 export function severityFails(severity: Severity, strict = false): boolean {

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)