@nifrajs/cli 1.13.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/cli",
-  "version": "1.13.0",
+  "version": "2.0.0",
   "description": "The nifra CLI — zero-config dev/build/start for a nifra app (`nifra dev`, `nifra build`, `nifra start`).",
   "keywords": [
     "bun",
@@ -41,14 +41,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/client": "1.13.0",
-    "@nifrajs/core": "1.13.0",
-    "@nifrajs/mcp": "1.13.0",
-    "@nifrajs/runner": "1.13.0",
-    "@nifrajs/schema": "1.13.0",
-    "@nifrajs/testing": "1.13.0",
-    "@nifrajs/web": "1.13.0",
-    "create-nifra": "1.13.0"
+    "@nifrajs/client": "2.0.0",
+    "@nifrajs/core": "2.0.0",
+    "@nifrajs/mcp": "2.0.0",
+    "@nifrajs/runner": "2.0.0",
+    "@nifrajs/schema": "2.0.0",
+    "@nifrajs/testing": "2.0.0",
+    "@nifrajs/web": "2.0.0",
+    "create-nifra": "2.0.0"
   },
   "repository": {
     "type": "git",

package/src/check.ts

@@ -25,9 +25,6 @@ export interface SourceFinding {
   readonly line: number
   readonly snippet: string
 }
-/** @deprecated kept for back-compat with existing tests; prefer {@link SourceFinding}. */
-export type FetchFinding = SourceFinding
-
 /** A server-only-import finding, carrying the offending module specifier on top of the base location so
  * the diagnostic can show the import chain `routeFile → specifier` (the direct edge the regex scan sees). */
 export interface ServerImportFinding extends SourceFinding {
@@ -39,7 +36,7 @@ export interface ServerImportFinding extends SourceFinding {
 // i.e. same-origin = this app's own API. `(?<![.\w])` skips `.fetch(` (a method) and `prefetch(`; the
 // `(?!\/)` skips protocol-relative `//host` (an external origin). A variable arg (`fetch(url)`) is left
 // alone on purpose — undecidable from source, and flagging it would punish legitimate external calls.
-const OWN_API_FETCH = /(?<![.\w])fetch\s*\(\s*['"`]\/(?!\/)/g
+const GLOBAL_FETCH_CALL = /(?<![.\w])fetch\s*\(/g
 const FETCH_CALL = /(?<![.\w])fetch\s*\(/g
 const HTTP_VERBS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"])
 const SIMPLE_REWRITE_METHODS = new Set(["GET", "DELETE", "HEAD", "OPTIONS"])
@@ -279,12 +276,163 @@ export function stripComments(src: string): string {
   return out.join("")
 }
 
-/** Scan one file's text for hand-rolled own-API `fetch()` calls. Pure + line-accurate. */
-export function scanFetchText(file: string, content: string): SourceFinding[] {
+/** Blank comments and every quoted/template literal while preserving offsets. Unlike
+ * {@link stripComments}, this is a code-position mask: scanners use it to find a call expression in
+ * executable code, then inspect the original source for the call's literal argument. That prevents
+ * documentation strings such as `const example = 'client("/")'` from becoming diagnostics. */
+export function codePositionMask(src: string): string {
+  const out = src.split("")
+  const n = src.length
+  let i = 0
+  const blank = (a: number, b: number): void => {
+    for (let k = a; k < b; k++) if (out[k] !== "\n") out[k] = " "
+  }
+  while (i < n) {
+    const c = src[i]
+    const d = src[i + 1]
+    if (c === "/" && d === "/") {
+      let j = i + 2
+      while (j < n && src[j] !== "\n") j++
+      blank(i, j)
+      i = j
+    } else if (c === "/" && d === "*") {
+      let j = i + 2
+      while (j < n && !(src[j] === "*" && src[j + 1] === "/")) j++
+      j = Math.min(j + 2, n)
+      blank(i, j)
+      i = j
+    } else if (c === "'" || c === '"' || c === "`") {
+      const quote = c
+      let j = i + 1
+      while (j < n && src[j] !== quote) {
+        if (src[j] === "\\") j++
+        j++
+      }
+      j = Math.min(j + 1, n)
+      blank(i, j)
+      i = j
+    } else {
+      i++
+    }
+  }
+  return out.join("")
+}
+
+const firstArgumentIndex = (content: string, callEnd: number): number => {
+  let index = callEnd
+  while (/\s/.test(content[index] ?? "")) index++
+  return index
+}
+
+// Read the literal URL path of a `fetch("/…")` call starting at `start` (the index of the leading `/`),
+// stopping at the first quote / query / hash / template-expression boundary, and test it against the
+// allowlist. A template like `/auth/${id}` matches on its literal head (`/auth`), so a dynamic sign-in URL
+// is covered too. Match is segment-anchored - `/auth` blesses `/auth` and `/auth/**`, never `/authors`.
+function matchesExternalMount(content: string, start: number, mounts: readonly string[]): boolean {
+  let end = start
+  while (end < content.length) {
+    const ch = content[end]
+    if (ch === "'" || ch === '"' || ch === "`" || ch === "?" || ch === "#") break
+    if (ch === "$" && content[end + 1] === "{") break
+    end++
+  }
+  const path = content.slice(start, end)
+  // A `..` segment means the runtime path escapes the literal prefix (`/auth/../api/admin` resolves to
+  // `/api/admin`), so it must NOT be blessed by an `/auth` mount - never let traversal hide a real own-API
+  // fetch. Match is otherwise segment-anchored (`/auth` blesses `/auth` and `/auth/**`, never `/authors`).
+  try {
+    if (path.split("/").some((segment) => decodeURIComponent(segment) === "..")) return false
+  } catch {
+    // A malformed escape is not a prefix we can prove stays inside the external mount.
+    return false
+  }
+  return mounts.some((prefix) => path === prefix || path.startsWith(`${prefix}/`))
+}
+
+function findTopLevelPropertyColon(src: string): number | undefined {
+  let depth = 0
+  let quote: '"' | "'" | "`" | undefined
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i]
+    if (quote !== undefined) {
+      if (c === "\\") {
+        i++
+        continue
+      }
+      if (c === quote) quote = undefined
+      continue
+    }
+    if (c === '"' || c === "'" || c === "`") {
+      quote = c
+      continue
+    }
+    if (c === "(" || c === "{" || c === "[") depth++
+    else if (c === ")" || c === "}" || c === "]") depth--
+    else if (c === ":" && depth === 0) return i
+  }
+  return undefined
+}
+
+function parseStaticPropertyName(raw: string): string | undefined {
+  const name = raw.trim()
+  if (IDENT.test(name)) return name
+  const quoted = parseQuotedLiteral(name)
+  if (quoted !== undefined) return quoted
+  if (name.startsWith("[") && name.endsWith("]")) {
+    return parseQuotedLiteral(name.slice(1, -1).trim())
+  }
+  return undefined
+}
+
+/** Return a statically named property from a plain object literal. Deliberately does not follow
+ * spreads, identifiers, or helper calls: only an inline literal proves this fetch is Nifra's page-data
+ * transport rather than an arbitrary same-origin API request. */
+function staticObjectProperty(raw: string | undefined, name: string): string | undefined {
+  if (raw === undefined) return undefined
+  const object = raw.trim()
+  if (!object.startsWith("{") || !object.endsWith("}")) return undefined
+  const properties = splitTopLevelArgs(object.slice(1, -1))
+  if (properties === undefined) return undefined
+  for (const property of properties) {
+    const colon = findTopLevelPropertyColon(property)
+    if (colon === undefined || parseStaticPropertyName(property.slice(0, colon)) !== name) continue
+    return property.slice(colon + 1).trim()
+  }
+  return undefined
+}
+
+function hasLiteralNifraDataHeader(content: string, openParen: number): boolean {
+  const closeParen = findMatchingParen(content, openParen)
+  if (closeParen === undefined) return false
+  const args = splitTopLevelArgs(content.slice(openParen + 1, closeParen))
+  if (args === undefined || args.length !== 2) return false
+  const headers = staticObjectProperty(args[1], "headers")
+  return staticObjectProperty(headers, "x-nifra-data") !== undefined
+}
+
+/** Scan one file's text for hand-rolled own-API `fetch()` calls. Pure + line-accurate. `externalMounts`
+ * are intentional non-typed mount prefixes (from `nifra.check.json`, e.g. a mounted better-auth owning
+ * `/auth/**`) - a relative fetch into one is deliberate, not drift, so it's skipped. A fetch with an
+ * inline literal `x-nifra-data` header is Nifra's page-loader transport, not a backend API call, and is
+ * skipped too. */
+export function scanFetchText(
+  file: string,
+  content: string,
+  externalMounts: readonly string[] = [],
+): SourceFinding[] {
   const out: SourceFinding[] = []
   const lines = content.split("\n")
-  OWN_API_FETCH.lastIndex = 0
-  for (let m = OWN_API_FETCH.exec(content); m !== null; m = OWN_API_FETCH.exec(content)) {
+  const code = codePositionMask(content)
+  GLOBAL_FETCH_CALL.lastIndex = 0
+  for (let m = GLOBAL_FETCH_CALL.exec(code); m !== null; m = GLOBAL_FETCH_CALL.exec(code)) {
+    const argument = firstArgumentIndex(content, m.index + m[0].length)
+    const quote = content[argument]
+    if (quote !== "'" && quote !== '"' && quote !== "`") continue
+    if (content[argument + 1] !== "/" || content[argument + 2] === "/") continue
+    const openParen = m.index + m[0].lastIndexOf("(")
+    if (hasLiteralNifraDataHeader(content, openParen)) continue
+    if (externalMounts.length > 0 && matchesExternalMount(content, argument + 1, externalMounts))
+      continue
     const line = lineAt(content, m.index)
     out.push({ file, line, snippet: (lines[line - 1] ?? "").trim() })
   }
@@ -305,14 +453,18 @@ export function scanStaticRouteText(file: string, content: string): StaticRouteF
 // the compiler has nothing to derive types from, so the anti-drift guarantee silently vanishes.
 // `client<typeof app>("…")` has `<…>` between the name and `(` so it never matches; the published-
 // contract form `client(contract, url)` starts with an identifier, not a quote — also unmatched.
-const UNTYPED_CLIENT = /(?<![.\w])client\s*\(\s*['"`]/g
+const CLIENT_CALL = /(?<![.\w])client\s*\(/g
 
 /** Scan one file's text for untyped `client("…")` calls. Pure + line-accurate. */
 export function scanUntypedClient(file: string, content: string): SourceFinding[] {
   const out: SourceFinding[] = []
   const lines = content.split("\n")
-  UNTYPED_CLIENT.lastIndex = 0
-  for (let m = UNTYPED_CLIENT.exec(content); m !== null; m = UNTYPED_CLIENT.exec(content)) {
+  const code = codePositionMask(content)
+  CLIENT_CALL.lastIndex = 0
+  for (let m = CLIENT_CALL.exec(code); m !== null; m = CLIENT_CALL.exec(code)) {
+    const argument = firstArgumentIndex(content, m.index + m[0].length)
+    const quote = content[argument]
+    if (quote !== "'" && quote !== '"' && quote !== "`") continue
     const line = lineAt(content, m.index)
     out.push({ file, line, snippet: (lines[line - 1] ?? "").trim() })
   }
@@ -326,8 +478,11 @@ export function scanServerOnlyImports(file: string, content: string): ServerImpo
   if (!ROUTE_FILE.test(file)) return []
   const out: ServerImportFinding[] = []
   const lines = content.split("\n")
+  const code = stripComments(content)
+  const positions = codePositionMask(content)
   STATIC_IMPORT.lastIndex = 0
-  for (let m = STATIC_IMPORT.exec(content); m !== null; m = STATIC_IMPORT.exec(content)) {
+  for (let m = STATIC_IMPORT.exec(code); m !== null; m = STATIC_IMPORT.exec(code)) {
+    if (positions[m.index] === " ") continue
     const specifier = m[1] ?? ""
     if (!SERVER_ONLY.test(specifier)) continue
     const line = lineAt(content, m.index)
@@ -379,7 +534,10 @@ const staticImportRegex = (): RegExp => new RegExp(STATIC_IMPORT.source, STATIC_
 function staticImportEdges(content: string): Array<{ specifier: string; index: number }> {
   const edges: Array<{ specifier: string; index: number }> = []
   const re = staticImportRegex()
-  for (let m = re.exec(content); m !== null; m = re.exec(content)) {
+  const code = stripComments(content)
+  const positions = codePositionMask(content)
+  for (let m = re.exec(code); m !== null; m = re.exec(code)) {
+    if (positions[m.index] === " ") continue
     if (m[1] !== undefined) edges.push({ specifier: m[1], index: m.index })
   }
   return edges
@@ -574,11 +732,24 @@ export function scanResponseRoutes(file: string, content: string): SourceFinding
   RESPONSE_RETURN.lastIndex = 0
   for (let m = RESPONSE_RETURN.exec(code); m !== null; m = RESPONSE_RETURN.exec(code)) {
     const line = lineAt(content, m.index)
-    out.push({ file, line, snippet: (lines[line - 1] ?? "").trim() })
+    // A `// nifra-expect raw-response` pragma marks an intentional raw Response (a file/redirect that can't
+    // be a typed route), silencing this advisory. Honor it on the return line itself, OR on the line above
+    // ONLY when that line is a standalone comment - so a TRAILING pragma on one route's return line can't
+    // leak down and suppress the very next route's genuine advisory. `stripComments` blanks the pragma in
+    // `code` (so it never affects the match); the raw `lines` still carry it.
+    const thisLine = lines[line - 1] ?? ""
+    const aboveLine = lines[line - 2] ?? ""
+    const aboveSuppresses =
+      aboveLine.trimStart().startsWith("//") && aboveLine.includes(RAW_RESPONSE_PRAGMA)
+    if (thisLine.includes(RAW_RESPONSE_PRAGMA) || aboveSuppresses) continue
+    out.push({ file, line, snippet: thisLine.trim() })
   }
   return out
 }
 
+/** The opt-out pragma that suppresses the {@link scanResponseRoutes} advisory for an intentional raw Response. */
+const RAW_RESPONSE_PRAGMA = "nifra-expect raw-response"
+
 /** Walk the project's `.ts`/`.tsx` source (skipping deps/build/tests), calling `visit` per file.
  * Exported so `nifra doctor` ({@link ./doctor.ts}) scans the same source surface as `nifra check`. */
 /**
@@ -634,7 +805,7 @@ export async function walkSource(
 const bySite = (a: SourceFinding, b: SourceFinding): number =>
   a.file.localeCompare(b.file) || a.line - b.line
 
-/** Collect own-API `fetch()` findings across the project (kept for back-compat + reuse). */
+/** Collect own-API `fetch()` findings across the project. */
 export async function scanProject(cwd: string): Promise<SourceFinding[]> {
   const out: SourceFinding[] = []
   await walkSource(cwd, (rel, content) => out.push(...scanFetchText(rel, content)))
@@ -775,6 +946,7 @@ export interface CheckDiagnostic {
     | "manifest-drift"
     | "capability-assurance"
     | "capability-config"
+    | "check-config"
   /** `error` fails the gate (a real contract break); `warning` is advisory — surfaced to the agent but
    * does NOT fail `nifra check`, for patterns that are sometimes intentional (a route returning a raw
    * `Response`, which silently drops the typed client to `data: never` but is valid for files/redirects). */
@@ -817,12 +989,43 @@ export interface CheckResult {
   readonly ok: boolean
   readonly typecheck: "pass" | "fail" | "skipped"
   readonly diagnostics: readonly CheckDiagnostic[]
+  /** Intentional non-typed mount prefixes declared in `nifra.check.json` (e.g. `/auth` for a mounted
+   * better-auth). Echoed here so `--json` / the MCP tool / the report can show what the typed-client scan
+   * deliberately skipped - a suppressed prefix stays auditable instead of silently hiding real drift. */
+  readonly externalMounts?: readonly string[]
   /** Set only when the caller passed `maxDiagnostics` and there were more — `diagnostics` then holds the
    * first `shown` of `total`. It caps the serialized size so the `nifra_check` MCP tool can't emit a
    * message large enough to break the stdio transport; fix the shown diagnostics and re-run for the rest. */
   readonly truncated?: { readonly shown: number; readonly total: number }
 }
 
+/** Optional per-project `nifra.check.json` - pure data (no code execution), so it's safe to read before
+ * the app is built or even importable, preserving check's pre-`loadApp` invariant. */
+interface CheckConfig {
+  readonly externalMounts: readonly string[]
+}
+
+/** Load `nifra.check.json` if present. Fail-open + total: absent → empty; malformed → empty plus a parse
+ * `error` the caller surfaces as a `warning` diagnostic (never throws, never blocks the gate). Mount
+ * entries are normalized to bare path prefixes (`/auth/**` and `/auth/` both become `/auth`). */
+async function loadCheckConfig(cwd: string): Promise<{ config: CheckConfig; error?: string }> {
+  const path = join(cwd, "nifra.check.json")
+  if (!existsSync(path)) return { config: { externalMounts: [] } }
+  try {
+    const parsed = JSON.parse(await Bun.file(path).text()) as { externalMounts?: unknown }
+    const raw = Array.isArray(parsed.externalMounts) ? parsed.externalMounts : []
+    const externalMounts = raw
+      .filter((m): m is string => typeof m === "string" && m.startsWith("/"))
+      .map((m) => m.replace(/\/\*+$/, "").replace(/\/+$/, "") || "/")
+    return { config: { externalMounts } }
+  } catch (error) {
+    return {
+      config: { externalMounts: [] },
+      error: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
 const UNTYPED_CLIENT_HINT =
   'client("…") without a type argument — write client<typeof app>("…") (or client(contract, url)) so the compiler can catch drift'
 const FETCH_HINT =
@@ -830,7 +1033,7 @@ const FETCH_HINT =
 const SERVER_IMPORT_HINT =
   "server-only import in a route module (bundled for the browser) — reach it via c.db / ctx.api inside a loader, never a top-level import"
 const RESPONSE_ROUTE_HINT =
-  "route handler returns a raw Response — the typed client infers `data: never`, so drift detection is lost for this route. Return a plain object (it's serialized for you), or add `{ response: t.… }` to the route if a raw Response is intended (file/redirect/stream)"
+  "route handler returns a raw Response - the typed client infers `data: never`, so drift detection is lost for this route. Return a plain object (it's serialized for you); for a stream use a typed SSE route (`app.sse(...)`), which keeps typed events; or, if a raw Response is intended (file/redirect), add `{ response: t.… }` or a `// nifra-expect raw-response` comment to mark it and silence this"
 const UNDECLARED_DEP_HINT =
   "imported package is not declared in package.json dependencies — run bun add to declare it"
 const MANIFEST_DRIFT_HINT =
@@ -965,7 +1168,8 @@ function responseRouteSuggestion(): CheckSuggestion {
     title: "Preserve typed-client response inference",
     steps: [
       "Prefer returning a plain object from JSON routes; nifra serializes it for you.",
-      "If this route must return a raw Response (redirect, file, stream), declare an explicit response schema or accept the warning.",
+      "For a stream, use a typed SSE route - `app.sse(...)` (or `sse(c, run)` from `@nifrajs/core/server`) - which keeps typed events instead of collapsing the client to `data: never`.",
+      "If this route must return a raw Response (redirect, file), declare an explicit response schema, or add a `// nifra-expect raw-response` comment above the return to mark it intentional and silence this advisory.",
     ],
   }
 }
@@ -990,6 +1194,9 @@ export async function collectCheckResult(
   // Route modules (rel + content) collected during the walk, so the TRANSITIVE server-only resolution
   // (#4.4) — which needs fs-backed import resolution, not just per-file text — runs after the walk.
   const routeModules: Array<{ rel: string; content: string }> = []
+  // Load the optional check config first - the typed-client scan needs the external-mount allowlist as it
+  // walks. It's a tiny pure-JSON read; a malformed file surfaces as a warning below, never blocking.
+  const { config: checkConfig, error: checkConfigError } = await loadCheckConfig(cwd)
   // lintsOnly: skip the tsc pass (seconds on a big project) and run just the near-instant source
   // lints — the agent inner-loop mode; the full gate stays the definition of done.
   const [tc, _, dr, manifestDrift] = await Promise.all([
@@ -997,7 +1204,7 @@ export async function collectCheckResult(
       ? Promise.resolve<TypecheckResult>({ ran: false, ok: true, note: "skipped (lintsOnly)" })
       : typecheck(cwd, opts.signal),
     walkSource(cwd, (rel, content) => {
-      fetches.push(...scanFetchText(rel, content))
+      fetches.push(...scanFetchText(rel, content, checkConfig.externalMounts))
       staticRoutes.push(...scanStaticRouteText(rel, content))
       untypedClients.push(...scanUntypedClient(rel, content))
       if (ROUTE_FILE.test(rel)) routeModules.push({ rel, content })
@@ -1034,6 +1241,15 @@ export async function collectCheckResult(
   }
 
   const diagnostics: CheckDiagnostic[] = []
+  if (checkConfigError !== undefined) {
+    diagnostics.push({
+      rule: "check-config",
+      severity: "warning",
+      file: "nifra.check.json",
+      message: `nifra.check.json could not be parsed (${checkConfigError}) - its external-mount allowlist was ignored`,
+      fix: "Fix the JSON syntax in nifra.check.json",
+    })
+  }
   if (tc.ran && !tc.ok) {
     const lines = (tc.output ?? "").split("\n")
     let matched = false
@@ -1304,6 +1520,9 @@ export async function collectCheckResult(
     ok: !diagnostics.some((diagnostic) => diagnostic.severity === "error"),
     typecheck: tc.ran ? (tc.ok ? "pass" : "fail") : "skipped",
     diagnostics: shown,
+    ...(checkConfig.externalMounts.length > 0
+      ? { externalMounts: checkConfig.externalMounts }
+      : {}),
     ...(shown.length < total ? { truncated: { shown: shown.length, total } } : {}),
   }
 }
@@ -1327,6 +1546,11 @@ export async function runCheck(
         ? "✗ typecheck failed — the frontend/backend contract is broken"
         : "• typecheck skipped (no tsconfig / typescript not installed)",
   )
+  if (result.externalMounts !== undefined && result.externalMounts.length > 0) {
+    console.log(
+      `• intentional external mounts (not typed-client checked): ${result.externalMounts.join(", ")}`,
+    )
+  }
   const counts = (rule: CheckDiagnostic["rule"]): CheckDiagnostic[] =>
     result.diagnostics.filter((d) => d.rule === rule)
   for (const [rule, label] of [
@@ -1341,6 +1565,7 @@ export async function runCheck(
     ["manifest-drift", "versioned trust manifest drift"],
     ["capability-assurance", "effect/capability assurance"],
     ["capability-config", "capability assurance config"],
+    ["check-config", "nifra.check.json"],
   ] as const) {
     const ds = counts(rule)
     if (rule === "response-route") {
@@ -1369,5 +1594,13 @@ export async function runCheck(
     }
   }
   console.log(result.ok ? "\n✓ check passed" : "\n✗ check failed")
+  // Discoverability nudge: a project with no `.mcp.json` hasn't wired its nifra MCP for coding agents.
+  // `nifra init-agents` writes it (+ .cursor/mcp.json + a CLAUDE.md preamble), no-clobber. A non-fatal
+  // one-line tip in the human report only (the `--json` path returns above, unaffected).
+  if (!existsSync(join(cwd, ".mcp.json"))) {
+    console.log(
+      "\ntip: no .mcp.json here - run `nifra init-agents` to wire this project's MCP + agent files (no-clobber).",
+    )
+  }
   return result.ok
 }