@nifrajs/cli 1.3.1 → 1.5.0

package/package.json

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

package/src/cli.ts

@@ -65,6 +65,13 @@ Usage:
   nifra check   [--json] [--lints-only]  Gate: typecheck + lints (hand-rolled fetch(), untyped client("…"),
                                          server-only imports in routes/). Run as "done"; --json for agents;
                                          --lints-only skips tsc for a near-instant inner-loop pass.
+  nifra snapshot [--out <file>]          Write the backend's API contract (routes + schemas) as plain
+                                         JSON — the baseline for \`nifra diff\`. Default api-snapshot.json.
+  nifra diff    [<baseline>] [--json]    Breaking-change gate: re-snapshot the contract and compare
+                                         against the committed baseline. Direction-aware (a new required
+                                         request field or a removed response field breaks; widening a
+                                         request enum or adding a response field doesn't) and fails
+                                         closed. Exits non-zero on any breaking change — run it in CI.
   nifra doctor  [--json] [--auto-fix]    Flag packages imported in source but missing from package.json
                                          (resolve at Bun runtime, break tsc + standalone install);
                                          --auto-fix writes safe local-version dependency fixes.
@@ -82,7 +89,7 @@ Port: \`dev\` and \`start\` share the default ${DEFAULT_DEV_PORT}. Override with
 \`PORT\` env var (\`--port\` wins over \`PORT\`, which wins over the default).`
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const CLI_VERSION = "1.3.1"
+const CLI_VERSION = "1.5.0"
 
 // A render adapter + nifra server are opaque to the CLI (it just forwards them); cast at the seam.
 const asAdapter = (v: unknown): RenderAdapter => v as RenderAdapter
@@ -332,6 +339,38 @@ async function main(): Promise<void> {
       process.exitCode = 1
     return
   }
+  // `snapshot` / `diff` load ONLY backend.ts (the API contract) — like `check`, they must run on an
+  // API-only project, so they dispatch before the eager `loadApp`.
+  if (command === "snapshot") {
+    const { runSnapshot } = await import("./diff-tool.ts")
+    const outIdx = argv.indexOf("--out")
+    const out = outIdx !== -1 ? argv[outIdx + 1] : undefined
+    if (outIdx !== -1 && (out === undefined || out.startsWith("-"))) {
+      console.error("[nifra] --out needs a file path")
+      process.exitCode = 1
+      return
+    }
+    try {
+      await runSnapshot(process.cwd(), out !== undefined ? { out } : {})
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err))
+      process.exitCode = 1
+    }
+    return
+  }
+  if (command === "diff") {
+    const { runDiff, DEFAULT_SNAPSHOT_FILE } = await import("./diff-tool.ts")
+    const baseline = argv.slice(1).find((arg) => !arg.startsWith("-")) ?? DEFAULT_SNAPSHOT_FILE
+    try {
+      if (!(await runDiff(process.cwd(), baseline, { json: argv.includes("--json") }))) {
+        process.exitCode = 1
+      }
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err))
+      process.exitCode = 1
+    }
+    return
+  }
   // `port` is a pure cwd-based portability linter (scans source, doesn't run the app) — like `check`/
   // `doctor`, dispatch before the eager `loadApp` so it runs on an API-only / not-yet-built project.
   if (command === "port") {

package/src/diff-tool.ts

@@ -0,0 +1,130 @@
+/**
+ * `nifra snapshot` / `nifra diff` — the API breaking-change gate.
+ *
+ *   nifra snapshot [--out api-snapshot.json]   Write the backend's route contract as plain JSON.
+ *   nifra diff <baseline.json> [--json]        Re-snapshot and compare against the committed
+ *                                              baseline; exit non-zero on any breaking change.
+ *
+ * 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.
+ *
+ * Loads ONLY `backend.ts` — the API contract — so it works on an API-only project with no
+ * framework config or routes/ directory (unlike the eager `loadApp`).
+ */
+
+import { existsSync } from "node:fs"
+import { resolve } from "node:path"
+import {
+  diffRouteSnapshots,
+  type RouteChange,
+  type RouteSnapshot,
+  type RoutesDiff,
+  snapshotRoutes,
+} from "@nifrajs/core/diff"
+
+/** Snapshot file envelope — versioned so a future format change can migrate instead of misparse. */
+export interface SnapshotFile {
+  readonly nifraSnapshot: 1
+  readonly routes: readonly RouteSnapshot[]
+}
+
+export const DEFAULT_SNAPSHOT_FILE = "api-snapshot.json"
+
+/** Parse + validate a snapshot file's content. Throws with an actionable message on any mismatch. */
+export function parseSnapshotFile(content: string, sourcePath: string): SnapshotFile {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(content)
+  } catch {
+    throw new Error(
+      `[nifra] ${sourcePath} is not valid JSON — regenerate it with \`nifra snapshot\`.`,
+    )
+  }
+  const record = parsed as Partial<SnapshotFile> | null
+  if (
+    record === null ||
+    typeof record !== "object" ||
+    record.nifraSnapshot !== 1 ||
+    !Array.isArray(record.routes)
+  ) {
+    throw new Error(
+      `[nifra] ${sourcePath} is not a nifra API snapshot — expected { "nifraSnapshot": 1, "routes": [...] }.`,
+    )
+  }
+  return record as SnapshotFile
+}
+
+const SEVERITY_MARK = {
+  breaking: "✖ breaking",
+  compatible: "✓ compatible",
+  info: "ℹ info",
+} as const
+
+const describeChange = (change: RouteChange): string => {
+  const where = change.section === "route" ? "" : ` ${change.section}`
+  return `${SEVERITY_MARK[change.severity]}  ${change.method} ${change.path}${where}: ${change.message}`
+}
+
+/** Render a diff for terminals: breaking first, then info, then compatible. */
+export function formatDiff(diff: RoutesDiff): string {
+  if (diff.changes.length === 0) return "No API contract changes."
+  const order: Record<RouteChange["severity"], number> = { breaking: 0, info: 1, compatible: 2 }
+  const lines = [...diff.changes]
+    .sort((a, b) => order[a.severity] - order[b.severity])
+    .map(describeChange)
+  const breaking = diff.changes.filter((change) => change.severity === "breaking").length
+  const summary = diff.hasBreaking
+    ? `${breaking} breaking change${breaking === 1 ? "" : "s"} — existing clients will fail.`
+    : "No breaking changes."
+  return `${lines.join("\n")}\n\n${summary}`
+}
+
+/** Import `backend.ts` from `cwd` and snapshot its routes. */
+async function snapshotBackend(cwd: string): Promise<readonly RouteSnapshot[]> {
+  const backendPath = resolve(cwd, "backend.ts")
+  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.`,
+    )
+  }
+  const backend = ((await import(backendPath)) as { backend?: unknown }).backend
+  if (backend === undefined) {
+    throw new Error(`[nifra] ${backendPath} does not export \`backend\`.`)
+  }
+  return snapshotRoutes(backend)
+}
+
+/** `nifra snapshot`: write the current contract as the CI baseline. */
+export async function runSnapshot(cwd: string, options: { out?: string }): Promise<void> {
+  const routes = await snapshotBackend(cwd)
+  const file: SnapshotFile = { nifraSnapshot: 1, routes }
+  const outPath = resolve(cwd, options.out ?? DEFAULT_SNAPSHOT_FILE)
+  await Bun.write(outPath, `${JSON.stringify(file, null, 2)}\n`)
+  console.log(`[nifra] wrote ${routes.length} route${routes.length === 1 ? "" : "s"} to ${outPath}`)
+}
+
+/** `nifra diff`: compare the current contract against a baseline. Returns false on breaking changes. */
+export async function runDiff(
+  cwd: string,
+  baselinePath: string,
+  options: { json?: boolean },
+): Promise<boolean> {
+  const resolved = resolve(cwd, baselinePath)
+  const baselineFile = Bun.file(resolved)
+  if (!(await baselineFile.exists())) {
+    throw new Error(
+      `[nifra] baseline not found: ${resolved} — create it on your main branch with \`nifra snapshot\`.`,
+    )
+  }
+  const baseline = parseSnapshotFile(await baselineFile.text(), baselinePath)
+  const current = await snapshotBackend(cwd)
+  const diff = diffRouteSnapshots(baseline.routes, current)
+  if (options.json === true) {
+    console.log(JSON.stringify({ hasBreaking: diff.hasBreaking, changes: diff.changes }, null, 2))
+  } else {
+    console.log(formatDiff(diff))
+  }
+  return !diff.hasBreaking
+}

package/src/introspect.ts

@@ -5,38 +5,14 @@
  * *this* project's actual surface, not just generic docs.
  */
 
+import { type ReflectedRoute, reflectRoutes, type SchemaReflection } from "@nifrajs/core/reflection"
 import type { Manifest } from "@nifrajs/web"
 import { discoverRoutes } from "@nifrajs/web/fs"
 import type { LoadedApp } from "./load.ts"
 
-/** Structural view of a `@nifrajs/core` route descriptor — declared locally so the CLI needs no type
- * dependency on core. `app.routes()` returns these. */
-interface RouteDesc {
-  readonly method: string
-  readonly path: string
-  readonly schema?: unknown
-}
-
 /** Read the backend's registered routes, if it's a `server()` with a `.routes()` method. */
-export function backendRoutes(backend: unknown): RouteDesc[] {
-  if (backend && typeof (backend as { routes?: unknown }).routes === "function") {
-    try {
-      return (backend as { routes(): RouteDesc[] }).routes()
-    } catch {
-      return []
-    }
-  }
-  return []
-}
-
-/** The JSON Schema a `t`/Standard Schema carries (nifra's `t` is TypeBox-backed and exposes `.jsonSchema`),
- * or `undefined` for a validator that doesn't expose one. This is the exact field-level contract. */
-function jsonSchemaOf(schema: unknown): unknown {
-  if (schema && typeof schema === "object" && "jsonSchema" in schema) {
-    const js = (schema as { jsonSchema?: unknown }).jsonSchema
-    if (js !== undefined && js !== null) return js
-  }
-  return undefined
+export function backendRoutes(backend: unknown): ReflectedRoute[] {
+  return [...reflectRoutes(backend)]
 }
 
 interface JsonSchemaNode {
@@ -99,16 +75,16 @@ export function tsTypeOf(schema: unknown, depth = 0): string {
 
 /** One route's request/response field shapes, indented under its line. Reads the declared schemas off the
  * descriptor so an agent gets the exact input + output contract — not just "this route is validated". */
-function schemaLines(schema: unknown): string[] {
-  const s = schema as { body?: unknown; query?: unknown; response?: unknown } | undefined
+function schemaLines(schema: ReflectedRoute["schema"]): string[] {
+  const s = schema
   if (!s) return []
   const out: string[] = []
   for (const key of ["query", "body", "response"] as const) {
     const declared = s[key]
     if (!declared) continue
-    const js = jsonSchemaOf(declared)
+    const js = declared.jsonSchema
     out.push(
-      js
+      js !== undefined
         ? `    - ${key}: \`${tsTypeOf(js)}\``
         : `    - ${key}: _(validated; shape not introspectable from this validator)_`,
     )
@@ -153,7 +129,7 @@ export function clientCall(method: string, path: string, schema: unknown): strin
 }
 
 /** Markdown section listing the backend's API routes with their request + response field shapes. */
-export function apiRoutesSection(routes: readonly RouteDesc[]): string {
+export function apiRoutesSection(routes: readonly ReflectedRoute[]): string {
   if (routes.length === 0) {
     return "## API routes\n\nNo `backend.ts` server routes found (this app may be frontend-only)."
   }
@@ -171,7 +147,7 @@ export function apiRoutesSection(routes: readonly RouteDesc[]): string {
  * body/query/response shapes or the per-route `call` line. Bounds the first-call payload on a big backend:
  * an agent gets the full route list (so it knows what's mounted) plus a pointer to fetch any route's full
  * contract via the `path`/`kind` slice, instead of every schema up front. */
-export function apiRoutesIndexSection(routes: readonly RouteDesc[]): string {
+export function apiRoutesIndexSection(routes: readonly ReflectedRoute[]): string {
   if (routes.length === 0) {
     return "## API routes (backend.ts)\n\nNo `backend.ts` server routes found (this app may be frontend-only)."
   }
@@ -287,8 +263,10 @@ export interface RouteJson {
 export function routesToJson(app: LoadedApp, pathPrefix?: string): RouteJson[] {
   const shape = (v: unknown): string | undefined => {
     if (!v) return undefined
-    const js = jsonSchemaOf(v)
-    return js ? tsTypeOf(js) : "(validated; shape not introspectable from this validator)"
+    const js = (v as SchemaReflection).jsonSchema
+    return js !== undefined
+      ? tsTypeOf(js)
+      : "(validated; shape not introspectable from this validator)"
   }
   let routes = backendRoutes(app.backend)
   if (pathPrefix !== undefined && pathPrefix !== "") {
@@ -297,7 +275,7 @@ export function routesToJson(app: LoadedApp, pathPrefix?: string): RouteJson[] {
   return [...routes]
     .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method))
     .map((r) => {
-      const s = r.schema as { body?: unknown; query?: unknown; response?: unknown } | undefined
+      const s = r.schema
       const body = shape(s?.body)
       const query = shape(s?.query)
       const response = shape(s?.response)
@@ -353,7 +331,7 @@ export interface PageRouteInput {
 
 export interface RouteTableInput {
   readonly pages: readonly PageRouteInput[]
-  readonly api: readonly RouteDesc[]
+  readonly api: ReadonlyArray<Pick<ReflectedRoute, "method" | "path">>
   /** The page router's `apiPrefix` (default `/api`); an API route at/under it is auto-mounted. `""`
    * disables the auto-mount, so no API route is marked auto-mounted. */
   readonly apiPrefix?: string

package/src/mcp-http.ts

@@ -26,7 +26,7 @@ export { docsTools } from "./mcp-docs-tools.ts"
 export type { TypeEntry } from "./types-search.ts"
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const VERSION = "1.3.1"
+const VERSION = "1.5.0"
 const SERVER_INFO = { name: "nifra-docs", version: VERSION }
 const DOCS_HEALTH =
   "nifra docs MCP — POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call). Tools: nifra_docs, nifra_example."

package/src/mcp.ts

@@ -26,6 +26,7 @@
 import { readFile, stat } from "node:fs/promises"
 import { basename, resolve, sep } from "node:path"
 import { fileURLToPath } from "node:url"
+import { type ReflectedRoute, reflectRoutes } from "@nifrajs/core/reflection"
 import { Glob } from "bun"
 import { loadDocsCorpus } from "./docs-search.ts"
 import { loadExamplesCorpus } from "./examples.ts"
@@ -978,17 +979,8 @@ export function projectTools(
   ]
 }
 
-/** A `.tool()`-registered route as seen through the backend's `routes()` introspection. */
-type ToolRoute = {
-  readonly schema?: { readonly body?: unknown; readonly response?: unknown }
-  readonly tool?: {
-    readonly name: string
-    readonly description: string
-    readonly annotations?: McpTool["annotations"]
-  }
-}
 type ToolBackend = {
-  readonly routes?: () => ToolRoute[]
+  readonly routes?: () => readonly unknown[]
   readonly fetch: (req: Request) => Promise<Response>
 }
 
@@ -997,28 +989,15 @@ type ToolBackend = {
 export function extractBackendTools(backend: unknown): McpTool[] {
   const b = backend as ToolBackend | null
   if (!b || typeof b.routes !== "function") return []
-  let routes: ToolRoute[] = []
-  try {
-    routes = b.routes()
-  } catch {
-    return []
-  }
-
-  const jsonSchemaOf = (schema: unknown): unknown => {
-    if (schema && typeof schema === "object" && "jsonSchema" in schema) {
-      const js = (schema as { jsonSchema?: unknown }).jsonSchema
-      if (js !== undefined && js !== null) return js
-    }
-    return undefined
-  }
+  const routes = reflectRoutes(b)
 
   return routes
     .filter(
       (
         r,
-      ): r is ToolRoute & {
-        schema: NonNullable<ToolRoute["schema"]>
-        tool: NonNullable<ToolRoute["tool"]>
+      ): r is ReflectedRoute & {
+        schema: NonNullable<ReflectedRoute["schema"]>
+        tool: NonNullable<ReflectedRoute["tool"]>
       } => r.schema !== undefined && r.tool !== undefined,
     )
     .map((r) => {
@@ -1027,7 +1006,7 @@ export function extractBackendTools(backend: unknown): McpTool[] {
       return {
         name: toolInfo.name,
         description: toolInfo.description,
-        inputSchema: (jsonSchemaOf(s.body) ?? {
+        inputSchema: (s.body?.jsonSchema ?? {
           type: "object",
           properties: {},
         }) as McpTool["inputSchema"],