@nifrajs/cli 4.0.2 → 5.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/cli",
-  "version": "4.0.2",
+  "version": "5.1.0",
   "description": "The nifra CLI - zero-config dev/build/start for a nifra app (`nifra dev`, `nifra build`, `nifra start`).",
   "keywords": [
     "bun",
@@ -69,17 +69,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/client": "4.0.2",
-    "@nifrajs/core": "4.0.2",
-    "@nifrajs/agent-review": "4.0.2",
-    "@nifrajs/i18n": "4.0.2",
-    "@nifrajs/mcp": "4.0.2",
-    "@nifrajs/mcp-db": "4.0.2",
-    "@nifrajs/runner": "4.0.2",
-    "@nifrajs/schema": "4.0.2",
-    "@nifrajs/testing": "4.0.2",
-    "@nifrajs/web": "4.0.2",
-    "create-nifra": "4.0.2"
+    "@nifrajs/client": "5.1.0",
+    "@nifrajs/core": "5.1.0",
+    "@nifrajs/agent-review": "5.1.0",
+    "@nifrajs/i18n": "5.1.0",
+    "@nifrajs/mcp": "5.1.0",
+    "@nifrajs/mcp-db": "5.1.0",
+    "@nifrajs/runner": "5.1.0",
+    "@nifrajs/schema": "5.1.0",
+    "@nifrajs/testing": "5.1.0",
+    "@nifrajs/web": "5.1.0"
   },
   "repository": {
     "type": "git",

package/src/agent-files.ts

@@ -0,0 +1,203 @@
+/**
+ * The canonical generators for the agent files an app ships. `AGENTS.md` is the single source of agent
+ * guidance; every other agent's file is a thin pointer to it, so no two copies can drift:
+ *
+ *   AGENTS.md                         - the guidance (read natively by Codex, Cursor, Copilot and others)
+ *   CLAUDE.md                         - Claude Code: `@AGENTS.md` import
+ *   GEMINI.md                         - Gemini CLI: `@./AGENTS.md` import
+ *   .cursor/rules/nifra.mdc           - Cursor: an always-applied rule pointing at AGENTS.md
+ *   .github/copilot-instructions.md   - GitHub Copilot: points at AGENTS.md
+ *   .mcp.json, .cursor/mcp.json       - the nifra MCP server, registered for Claude Code and Cursor
+ *
+ * `create-nifra` (scaffold time) and `@nifrajs/cli`'s `nifra init-agents` (retrofit an existing app) each
+ * ship this file byte-identical - `packages/cli/test/init-agents.test.ts` holds the two copies equal - so
+ * the generated files can never drift apart and neither package needs the other at runtime. It stays
+ * dependency-free (pure string + object generation) on purpose: `create-nifra` ships with no runtime deps.
+ *
+ * Why `bunx @nifrajs/cli mcp` (not `bunx nifra mcp`): the `nifra` binary is provided by the
+ * `@nifrajs/cli` package, and the bare npm package literally named `nifra` (this monorepo's
+ * `@nifrajs/web` shim) exposes NO `nifra` bin, so `bunx nifra mcp` would fetch the wrong package in an
+ * app that does not carry `@nifrajs/cli`. Naming the bin-owning package resolves the locally-installed
+ * bin when present and otherwise fetches the package that actually provides the `nifra` command.
+ */
+
+import { readFileSync } from "node:fs"
+
+/** The MCP launch command, shared by `.mcp.json` and `.cursor/mcp.json`. See the module header for why
+ * the package is named explicitly rather than relying on the bare `nifra` bin. */
+export const MCP_SERVER_COMMAND = "bunx" as const
+
+/**
+ * The `@nifrajs/cli` version the launch command pins to - DERIVED at load time from this package's own
+ * `version`, never hardcoded. `fixed` changeset versioning ([["@nifrajs/*", "create-nifra", "nifra"]] in
+ * `.changeset/config.json`) bumps `create-nifra` and `@nifrajs/cli` in lockstep, so `create-nifra@x`
+ * always means `@nifrajs/cli@x`. Deriving it here means a release bump has nothing to forget to update -
+ * there is no stale literal to drift (the 1.0.0 cut shipped a beta pin exactly this way). `check:publish`
+ * still asserts it equals `@nifrajs/cli`'s version as a belt-and-suspenders guard on the `fixed` link.
+ *
+ * Resolves correctly under BOTH export conditions: the `bun` export runs `src/agent-files.ts`
+ * (`../package.json` → the package root) and the tsc `default` export runs `dist/agent-files.js`
+ * (`../package.json` → the same root, since `dist/` sits beside the manifest). npm always ships a
+ * package's own `package.json`, so the read can't miss at install time.
+ *
+ * Why pin at all instead of `bunx @nifrajs/cli mcp`: `bunx` keys its cache on the exact version spec.
+ * An UNPINNED spec resolves to the `latest` tag once, then `bunx` reuses that cached copy on every
+ * later spawn WITHOUT re-checking the registry - so an editor that once launched an older `@nifrajs/cli`
+ * keeps respawning the stale binary even after a newer one is published (the MCP server silently runs
+ * old code). Pinning the exact version makes the version part of the cache key, so each release fetches
+ * fresh and a stale cache can never shadow it. The cost: an already-scaffolded app's `.mcp.json` freezes
+ * at its scaffold-time version until `nifra init-agents --sync-mcp` re-pins it to the nifra the project
+ * installs - an acceptable, deterministic trade.
+ */
+export const MCP_CLI_VERSION: string = ownVersion()
+
+function ownVersion(): string {
+  const manifest: unknown = JSON.parse(
+    readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+  )
+  if (
+    typeof manifest === "object" &&
+    manifest !== null &&
+    "version" in manifest &&
+    typeof manifest.version === "string"
+  )
+    return manifest.version
+  throw new Error("[nifra] agent-files: this package's package.json has no version")
+}
+export const MCP_SERVER_ARGS = [`@nifrajs/cli@${MCP_CLI_VERSION}`, "mcp"] as const
+
+/** The server entry registered under the `nifra` key in both Claude Code's and Cursor's MCP config. */
+export interface McpServerConfig {
+  readonly command: string
+  readonly args: readonly string[]
+}
+
+/** Claude Code / Cursor MCP config shape: a map of server name → launch config. */
+export interface McpConfig {
+  readonly mcpServers: Readonly<Record<string, McpServerConfig>>
+}
+
+/** The one canonical MCP config object both registries serialize - the anti-drift seam. */
+export const MCP_CONFIG: McpConfig = {
+  mcpServers: {
+    nifra: { command: MCP_SERVER_COMMAND, args: [...MCP_SERVER_ARGS] },
+  },
+}
+
+/** Serialize the canonical MCP config as the JSON written to `.mcp.json` and `.cursor/mcp.json`.
+ * Trailing newline so the file is POSIX-clean and diffs don't flag a missing EOL. */
+export function mcpJson(): string {
+  return `${JSON.stringify(MCP_CONFIG, null, 2)}\n`
+}
+
+const POINTER_INTRO =
+  "This project's agent guidance - commands, the project structure, the rules, and the nifra MCP server - lives in AGENTS.md, the single source every agent reads."
+
+/** `CLAUDE.md`: Claude Code expands the `@AGENTS.md` import in place. */
+export function claudeMd(): string {
+  return `# CLAUDE.md\n\n${POINTER_INTRO}\n\n@AGENTS.md\n`
+}
+
+/** `GEMINI.md`: Gemini CLI expands `@./AGENTS.md` imports in its context files. */
+export function geminiMd(): string {
+  return `# GEMINI.md\n\n${POINTER_INTRO}\n\n@./AGENTS.md\n`
+}
+
+/** `.cursor/rules/nifra.mdc`: an always-applied Cursor rule; `@AGENTS.md` attaches the file. */
+export function cursorRule(): string {
+  return `---\ndescription: nifra project guidance\nalwaysApply: true\n---\n\n${POINTER_INTRO} Read it before changing code:\n\n@AGENTS.md\n`
+}
+
+/** `.github/copilot-instructions.md`: Copilot has no import syntax, so this names the file. */
+export function copilotInstructions(): string {
+  return `${POINTER_INTRO} Read AGENTS.md at the repository root before changing code, and follow it.\n`
+}
+
+/**
+ * The "## MCP server" section appended to a scaffolded (or retrofitted) `AGENTS.md`, so non-Claude
+ * agents (Cursor, and anything that reads `AGENTS.md`) also learn the MCP exists and what to prefer.
+ * Mirrors the CLAUDE.md preamble's guidance without the Claude-specific `@import`.
+ */
+export function agentsMcpSection(): string {
+  return `## MCP server
+
+This project ships a **nifra MCP server** - launch it with \`${MCP_SERVER_COMMAND} ${MCP_SERVER_ARGS.join(" ")}\`. It's registered for
+Claude Code in \`.mcp.json\` and for Cursor in \`.cursor/mcp.json\`; other agents can point their MCP client
+at that command. **Prefer its tools** over writing nifra from memory - they're typechecked against this
+project + the installed version, so they beat training-data recall:
+
+- \`nifra_docs\` / \`nifra_example\` - exact signatures + verified, compiling snippets.
+- \`nifra_context\` / \`nifra_routes\` - this project's route index + per-route schemas.
+- \`nifra_types\` - the EXACT TypeScript of any \`@nifrajs/*\` symbol (interface/type/function). Call it for a
+  precise type; **never read \`@nifrajs\` \`.d.ts\` files** - this is the authoritative, complete source.
+- \`nifra_check\` - the done-gate (typecheck + drift lints). Run it before calling work complete; a
+  failing check means it isn't done. (\`nifra check --json\` in a terminal does the same.)`
+}
+
+/**
+ * The "## Project structure" section of a web app's `AGENTS.md`: the zones the build enforces. Shared so
+ * a scaffolded app and one `nifra init-agents` retrofits teach the same rules.
+ */
+export function agentsStructureSection(): string {
+  return `${STRUCTURE_HEADING}
+
+Every file a build loads belongs to one side, and the build refuses an import that crosses the wrong
+way - it fails naming the import chain rather than shipping server code to the browser.
+
+| Where | Holds | Reaches the browser |
+|---|---|---|
+| \`routes/x.tsx\` (\`.svelte\`, \`.vue\`, \`.mdx\`) | a page: the component, \`meta\` | yes |
+| \`routes/x.backend.ts\` | that page's \`loader\`, \`action\`, \`loaderOutput\`, \`actionOutput\`, \`middleware\` | never |
+| \`frontend/\` | components, hooks, browser-only code | yes |
+| \`backend/\` | \`app.ts\` (the API), \`framework.ts\`, the database, auth, secrets | never |
+| \`shared/\` | schemas, types and pure helpers both sides import | yes |
+| \`public/\` | static files served as they are | yes |
+
+A file outside those folders joins a side with a \`.frontend.ts\`, \`.backend.ts\` or \`.shared.ts\` suffix.
+
+- **A route is two files.** \`routes/blog/[slug].tsx\` renders; \`routes/blog/[slug].backend.ts\` loads.
+  A server-only export (\`loader\`, \`action\`, ...) in the \`.tsx\` file is a build error.
+- **Frontend code never imports backend code** - not \`backend/\`, not a \`.backend.ts\` file, not a
+  database driver or \`node:\` built-in. Data reaches a page only as its loader's return value.
+- **Every loader and action declares what it sends**: \`export const loaderOutput = t.object({ ... })\`
+  (and \`actionOutput\`). Only what the schema declares reaches the browser, and a loader without one
+  is refused.
+- **Type a route with its generated \`./+types/<name>\`**: \`import type { Route } from "./+types/[slug]"\`
+  gives \`Route.Loader\` and \`Route.Action\` in the backend half (\`export const loader: Route.Loader =
+  async ({ api, params }) => ...\` checks what it returns against \`loaderOutput\`) and
+  \`Route.ComponentProps\` in the page. \`nifra dev\`, \`nifra build\`, \`nifra check\` and
+  \`nifra types\` write them.
+- **Secrets stay in \`backend/\`.** A value only the server may see is read there (\`process.env\`), never
+  in a frontend file; a build that finds what looks like a credential in browser output fails.`
+}
+
+/** The heading `nifra init-agents` looks for before appending {@link agentsStructureSection}. */
+export const STRUCTURE_HEADING = "## Project structure"
+
+/** Identifies a generated agent-discovery file: where it goes (relative to the project root) and how to
+ * produce its content. `merge` is for files that augment an existing one (AGENTS.md) rather than own it. */
+export interface AgentFileSpec {
+  /** Path relative to the project root (POSIX-style; the caller joins onto the cwd). */
+  readonly path: string
+  /** A human label for the "wrote/skipped" report. */
+  readonly label: string
+}
+
+/** The standalone files this module fully owns (whole-file generators). AGENTS.md is handled separately
+ * because create-nifra builds it from `agents.ts` and the retrofit command appends sections to it. */
+export const MCP_JSON_PATH = ".mcp.json"
+export const CURSOR_MCP_JSON_PATH = ".cursor/mcp.json"
+export const CLAUDE_MD_PATH = "CLAUDE.md"
+export const GEMINI_MD_PATH = "GEMINI.md"
+export const CURSOR_RULE_PATH = ".cursor/rules/nifra.mdc"
+export const COPILOT_INSTRUCTIONS_PATH = ".github/copilot-instructions.md"
+export const AGENTS_MD_PATH = "AGENTS.md"
+
+/** Every agent's pointer to `AGENTS.md`, in the order they are written and reported. */
+export const AGENT_POINTERS: readonly { readonly path: string; readonly content: () => string }[] =
+  [
+    { path: CLAUDE_MD_PATH, content: claudeMd },
+    { path: GEMINI_MD_PATH, content: geminiMd },
+    { path: CURSOR_RULE_PATH, content: cursorRule },
+    { path: COPILOT_INSTRUCTIONS_PATH, content: copilotInstructions },
+  ]

package/src/app-files.ts

@@ -6,7 +6,7 @@
  *   kept free of build tooling because it is bundled into every server build.
  * - `backend/app.ts` - exports `backend`, the app's API (a `@nifrajs/core` server). Optional.
  */
-import { existsSync } from "node:fs"
+import { existsSync, readFileSync } from "node:fs"
 import { resolve } from "node:path"
 
 export const CONFIG_FILE = "nifra.config.ts"
@@ -19,11 +19,41 @@ export const RETIRED_ROOT_FILES: Readonly<Record<string, string>> = {
   "framework.ts": FRAMEWORK_FILE,
 }
 
+/** Outside a routed app, what made each retired root file the app's: else it is just a module. */
+const RETIRED_EXPORTS: Readonly<Record<string, RegExp>> = {
+  "backend.ts":
+    /\bexport\s+(?:const|let|var|(?:async\s+)?function|class)\s+backend\b|\bexport\s*\{[^}]*\bbackend\b/,
+  "framework.ts":
+    /\bexport\s+(?:const|let|var|(?:async\s+)?function|class)\s+adapter\b|\bexport\s*\{[^}]*\badapter\b/,
+}
+
+function exportsRetiredName(path: string, pattern: RegExp | undefined): boolean {
+  if (!existsSync(path)) return false
+  try {
+    return pattern === undefined || pattern.test(readFileSync(path, "utf8"))
+  } catch {
+    // Unreadable: the commands that would load it fail too, so report it rather than skip it.
+    return true
+  }
+}
+
+/**
+ * The retired root files present in `cwd`, each with where it lives now. The old loader imported them
+ * whatever they exported, so in an app with `routes/` or a config each one counts; elsewhere only one
+ * that exports what the loader read does, and a library's `backend.ts` module does not.
+ */
+export function retiredRootFiles(cwd: string): ReadonlyArray<readonly [string, string]> {
+  const routed = ["routes", CONFIG_FILE, FRAMEWORK_FILE].some((entry) =>
+    existsSync(resolve(cwd, entry)),
+  )
+  return Object.entries(RETIRED_ROOT_FILES).filter(([file]) =>
+    exportsRetiredName(resolve(cwd, file), routed ? undefined : RETIRED_EXPORTS[file]),
+  )
+}
+
 /** Refuse an app still on the retired root files: run against it, a command would silently miss them. */
 export function assertCurrentLayout(cwd: string): void {
-  const retired = Object.entries(RETIRED_ROOT_FILES).filter(([file]) =>
-    existsSync(resolve(cwd, file)),
-  )
+  const retired = retiredRootFiles(cwd)
   if (retired.length === 0) return
   const moves = retired.map(([from, to]) => `${from} -> ${to}`).join(", ")
   throw new Error(

package/src/assure-hydration.ts

@@ -11,7 +11,16 @@ import { discoverRoutes } from "@nifrajs/web/fs"
 import type { BunPlugin } from "bun"
 import { collectDoctorResult } from "./doctor.ts"
 import { loadApp, resolvePlugins } from "./load.ts"
-import { CHILD_OUTPUT_MAX_BYTES, joinHeadTail, readBoundedStream, readHeadTail } from "./mcp-io.ts"
+import {
+  CHILD_OUTPUT_MAX_BYTES,
+  escalatingStop,
+  forwardTerminalSignals,
+  joinHeadTail,
+  OWN_PROCESS_GROUP,
+  readBoundedStream,
+  readHeadTail,
+  signalProcessGroup,
+} from "./mcp-io.ts"
 import { frameworkWebAppOptions } from "./web-app-options.ts"
 
 const HYDRATION_ASSURANCE = Symbol.for("nifra.hydration.assurance")
@@ -634,15 +643,20 @@ export async function runHydrationAssurance(
       stdin: "pipe",
       stdout: "pipe",
       stderr: "pipe",
+      // Its own group, so a stop reaches whatever the project's code started too; a process left
+      // holding the pipes would otherwise keep this run waiting past its timeout.
+      detached: OWN_PROCESS_GROUP,
     },
   )
+  const stopper = escalatingStop((name) => signalProcessGroup(proc, name))
   let stopped: string | undefined
   const stop = (reason: string): void => {
     stopped ??= reason
-    proc.kill()
+    stopper.stop()
   }
   const onAbort = (): void => stop("cancelled")
   control.signal?.addEventListener("abort", onAbort, { once: true })
+  const releaseSignals = forwardTerminalSignals(() => stop("interrupted"))
   const timeoutMs = control.timeoutMs ?? HYDRATION_RUN_TIMEOUT_MS
   const timer = setTimeout(() => stop(`timed out after ${timeoutMs} ms`), timeoutMs)
   try {
@@ -672,7 +686,9 @@ export async function runHydrationAssurance(
     return failed(joinHeadTail(stderr).trim() || "no result")
   } finally {
     clearTimeout(timer)
+    stopper.dispose()
     control.signal?.removeEventListener("abort", onAbort)
+    releaseSignals()
   }
 }
 

package/src/assure.ts

@@ -3,9 +3,10 @@
 import { existsSync } from "node:fs"
 import { join, resolve } from "node:path"
 import { pathToFileURL } from "node:url"
-import type { AssuranceConfig, AssuranceReport } from "@nifrajs/core/assurance"
+import type { AssuranceConfig, AssuranceReport, AssuredRoute } from "@nifrajs/core/assurance"
 import { CONFIG_FILE, FRAMEWORK_FILE } from "./app-files.ts"
 import type { Diagnostic } from "./diagnostics.ts"
+import type { ProjectVerification } from "./verification.ts"
 
 export interface AssureSink {
   record(bundle: AssureBundle): Promise<void>
@@ -14,6 +15,7 @@ export interface AssureSink {
 export interface GateResult {
   readonly gate:
     | "check"
+    | "assurance"
     | "doctor"
     | "render"
     | "hydration"
@@ -91,6 +93,45 @@ export async function loadAssuranceConfig(
   return loaded.default
 }
 
+/** Why declared response/error schemas go unenforced, phrased for the server that has to change. */
+export interface ResponseContractGaps {
+  readonly typedOnly: readonly string[]
+  readonly warnOnly: readonly string[]
+  readonly typedOnlyReason: string | undefined
+  readonly warnOnlyReason: string | undefined
+}
+
+const sample = (routes: readonly string[]): string =>
+  routes.length <= 3
+    ? routes.join(", ")
+    : `${routes.slice(0, 3).join(", ")} and ${routes.length - 3} more`
+
+export function responseContractGaps(routes: readonly AssuredRoute[]): ResponseContractGaps {
+  const key = (route: AssuredRoute): string => `${route.method} ${route.path}`
+  const typedOnly = routes.filter((route) => route.responseContract === "unchecked").map(key)
+  const warnOnly = routes.filter((route) => route.responseContract === "warn").map(key)
+  const covered = routes.filter(
+    (route) => route.responseContract === "enforce" || route.responseContract === "warn",
+  ).length
+  // A plugin that covers some routes is installed - just not where these were registered, which is
+  // the case "install responseContract" advice used to send people in circles over.
+  const typedOnlyReason =
+    typedOnly.length === 0
+      ? undefined
+      : covered > 0
+        ? `${typedOnly.length} declared route(s) are typed-only (${sample(typedOnly)}) although responseContract() covers ${covered} other(s): it covers routes registered after it on the same server, and routes merge()d into that server after it. Install responseContract("enforce") on the server that registers these, before them.`
+        : `${typedOnly.length} declared route(s) are typed-only (${sample(typedOnly)}); install responseContract("enforce") on the server that registers them, before them - a parent's also covers servers merge()d into it afterwards.`
+  const warnOnlyReason =
+    warnOnly.length === 0
+      ? undefined
+      : `${warnOnly.length} declared route(s) are warn-only and still send the original payload (${sample(warnOnly)}); switch responseContract("warn") to "enforce".`
+  return { typedOnly, warnOnly, typedOnlyReason, warnOnlyReason }
+}
+
+/** The policy line that turns an unenforced contract into a route-assurance failure. */
+export const RESPONSE_CONTRACT_BASELINE_HINT =
+  'to fail route assurance on these, add baseline: [{ name: "response-contract", match: { hasResponse: true }, require: ["nifra.response-contract"] }] to the policy'
+
 export function formatAssuranceReport(report: AssuranceReport): string {
   if (report.ok) {
     const contracted = report.routes.filter((route) => route.responseContract !== undefined)
@@ -247,20 +288,57 @@ export async function collectAssureBundle(
     }
   }
 
+  // One verification serves both gates that read the app, so the config is evaluated once.
+  let verification: Promise<ProjectVerification> | undefined
+  const verify = (): Promise<ProjectVerification> =>
+    (verification ??= import("./verification.ts").then(({ collectProjectVerification }) =>
+      collectProjectVerification(cwd, {
+        ...(options.config !== undefined ? { config: options.config } : {}),
+        preloaded:
+          assuranceConfig !== undefined
+            ? { config: assuranceConfig }
+            : { error: assuranceConfigError },
+      }),
+    ))
+
   await addGate("check", async () => {
-    const { collectProjectVerification } = await import("./verification.ts")
-    const verification = await collectProjectVerification(cwd, {
-      ...(options.config !== undefined ? { config: options.config } : {}),
-      preloaded:
-        assuranceConfig !== undefined
-          ? { config: assuranceConfig }
-          : { error: assuranceConfigError },
-    })
-    const result = await verification.check()
+    const result = await (await verify()).check()
     const diagnostics = (result.structuredDiagnostics ?? []).map((item) => item)
     return { diagnostics }
   })
 
+  // Route assurance is the gate the bundle exists to carry: a failing policy fails it, and a declared
+  // response the runtime does not enforce is a warning, so `--strict` refuses to call it green.
+  await addGate("assurance", async () => {
+    const report = assuranceConfig === undefined ? undefined : (await verify()).routeAssurance
+    if (report === undefined)
+      return {
+        diagnostics: [],
+        skipReason: existsSync(resolve(cwd, options.config ?? DEFAULT_ASSURANCE_CONFIG))
+          ? "route assurance could not be evaluated (reported by the check gate)"
+          : "no route assurance config",
+      }
+    const diagnostics = report.findings.map((finding) =>
+      diagnosticFromMessage("NF-A001", finding.message, "error"),
+    )
+    const gaps = responseContractGaps(report.routes)
+    for (const [reason, routes] of [
+      [gaps.typedOnlyReason, gaps.typedOnly],
+      [gaps.warnOnlyReason, gaps.warnOnly],
+    ] as const) {
+      if (reason === undefined) continue
+      diagnostics.push(
+        Object.freeze({
+          code: "NF-A001",
+          severity: "warn" as const,
+          message: `${reason} (${RESPONSE_CONTRACT_BASELINE_HINT})`,
+          evidence: Object.freeze(routes.slice(0, 20)),
+        }),
+      )
+    }
+    return { diagnostics }
+  })
+
   await addGate("doctor", async () => {
     const { collectDoctorResult } = await import("./doctor.ts")
     const result = await collectDoctorResult(cwd)

package/src/capabilities-tool.ts

@@ -18,7 +18,13 @@ import {
 } from "@nifrajs/core/capabilities"
 import { expandOptionalParams } from "@nifrajs/core/pattern"
 import { type ReflectedMount, type ReflectedRoute, reflectRoutes } from "@nifrajs/core/reflection"
-import { scanStaticRouteText, stripComments, walkSource } from "./check.ts"
+import {
+  scanSkippedRouteText,
+  scanStaticRouteText,
+  scanStaticSocketText,
+  stripComments,
+  walkSource,
+} from "./check.ts"
 
 // Import and re-export clauses are spelled out (a default binding, then `* as ns` or a `{ … }` list)
 // rather than scanned lazily, which is quadratic on a long semicolon-free module.
@@ -200,7 +206,10 @@ function resolveLocalModule(
     const fromAbsolute = join(cwd, from)
     const resolved = Bun.resolveSync(specifier, dirname(fromAbsolute))
     const rel = relative(cwd, resolved).replaceAll("\\", "/")
-    if (rel.startsWith("../") || isAbsolute(rel)) return undefined
+    // Outside the app is still the app's code: a workspace package resolves through its node_modules
+    // link to its source beside the app (`../../packages/db`), and an installed package may be hoisted
+    // above it. Both are walked, as a package in the app's own node_modules is.
+    if (isAbsolute(rel)) return undefined
     if (!sources.has(rel) && existsSync(resolved)) {
       try {
         sources.set(rel, readFileSync(resolved, "utf8"))
@@ -337,8 +346,12 @@ export async function collectCapabilityProjectReport(
   const policy = defineCapabilityPolicy(policyInput)
   const sources = await readSources(cwd)
   const automatic = new Map<string, Set<string>>()
+  const skipped = new Map<string, string>()
   for (const [file, content] of sources) {
-    for (const route of scanStaticRouteText(file, content)) {
+    for (const route of [
+      ...scanStaticRouteText(file, content, undefined, sources),
+      ...scanStaticSocketText(file, content, undefined, sources),
+    ]) {
       // A path ending in optional params is reflected as one route per form it serves.
       for (const path of staticRouteForms(route.path)) {
         const modules = automatic.get(routeKey(route.method, path)) ?? new Set<string>()
@@ -346,6 +359,12 @@ export async function collectCapabilityProjectReport(
         automatic.set(routeKey(route.method, path), modules)
       }
     }
+    for (const route of scanSkippedRouteText(file, content, sources)) {
+      for (const path of staticRouteForms(route.path)) {
+        if (!skipped.has(routeKey(route.method, path)))
+          skipped.set(routeKey(route.method, path), `${file}:${route.line}`)
+      }
+    }
   }
 
   const evidenceRoutes = []
@@ -374,12 +393,25 @@ export async function collectCapabilityProjectReport(
       policy,
       sources,
     )
-    evidenceRoutes.push({
-      method: route.method,
-      path: route.path,
-      covered: modules.size > 0 && walked.covered,
-      evidence: walked.evidence,
-    })
+    const site = modules.size === 0 ? skipped.get(routeKey(route.method, route.path)) : undefined
+    const uncoveredReason =
+      modules.size > 0
+        ? undefined
+        : site === undefined
+          ? "no source file registers it with a path the static scan can read; map it with capabilities.provenance.routeModules"
+          : `${site} appears to register it on a server the static scan cannot identify (built by a helper that is neither \`server()\` nor imported from a module that calls it); call server() there, or map the route with capabilities.provenance.routeModules`
+    const covered = modules.size > 0 && walked.covered
+    evidenceRoutes.push(
+      uncoveredReason === undefined
+        ? { method: route.method, path: route.path, covered, evidence: walked.evidence }
+        : {
+            method: route.method,
+            path: route.path,
+            covered,
+            evidence: walked.evidence,
+            uncoveredReason,
+          },
+    )
     violations.push(...walked.violations)
     truncations.push(...walked.truncations)
   }
@@ -703,6 +735,12 @@ export async function runCapabilityCheck(
     // Stated on every run, passing or not: a gap is the report's own boundary, not a failure.
     for (const gap of result.report.gaps ?? [])
       console.log(`• known gap, not analyzed: ${gap.path} - ${gap.reason}`)
+    for (const route of result.report.routes) {
+      if (route.analysis === "declared")
+        console.log(
+          `• declared by an opaque mount, not analyzed: ${route.method} ${route.path} [${route.declared.join(", ")}]`,
+        )
+    }
     for (const finding of result.report.findings) console.log(`✖ ${finding.message}`)
     for (const violation of result.violations)
       console.log(