@nifrajs/cli 2.9.0 → 2.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/cli",
-  "version": "2.9.0",
+  "version": "2.10.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": "2.9.0",
-    "@nifrajs/core": "2.9.0",
-    "@nifrajs/mcp": "2.9.0",
-    "@nifrajs/runner": "2.9.0",
-    "@nifrajs/schema": "2.9.0",
-    "@nifrajs/testing": "2.9.0",
-    "@nifrajs/web": "2.9.0",
-    "create-nifra": "2.9.0"
+    "@nifrajs/client": "2.10.0",
+    "@nifrajs/core": "2.10.0",
+    "@nifrajs/mcp": "2.10.0",
+    "@nifrajs/runner": "2.10.0",
+    "@nifrajs/schema": "2.10.0",
+    "@nifrajs/testing": "2.10.0",
+    "@nifrajs/web": "2.10.0",
+    "create-nifra": "2.10.0"
   },
   "repository": {
     "type": "git",

package/src/cli.ts

@@ -15,7 +15,7 @@ import { inProcessClient } from "@nifrajs/client"
 import { createWebApp, DEFAULT_DEV_PORT, type RenderAdapter } from "@nifrajs/web"
 import { discoverRoutes } from "@nifrajs/web/fs"
 import type { BunPlugin } from "bun"
-import { describeProject, describeRoutes } from "./introspect.ts"
+import { describeProject, describeRouteGraph, describeRoutes } from "./introspect.ts"
 import { type LoadedApp, loadApp } from "./load.ts"
 import { chooseBuildPipeline } from "./pipeline-guard.ts"
 
@@ -67,6 +67,8 @@ Usage:
                                          routes (routes/) + the in-process backend's API routes,
                                          marking which API routes are auto-mounted under apiPrefix.
                                          --json for agents (see POST /api/x is/isn't served, not via 405).
+  nifra routes  --graph [--json]         Render the public route surface as a Mermaid graph, or as
+                                         stable JSON for contract explorers.
   nifra routes --modes [--target <t>]    Show each page route's RENDER MODE (static | isr | ssr),
                                          hydration, and cache policy in one table. With --target, gate
                                          against it: a route the target can't honour (an ssr route on a
@@ -105,6 +107,8 @@ Usage:
                                          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 sdk     --lang <python|go> [--out <file>]
+                                         Generate a deterministic non-TypeScript SDK from backend.ts.
   nifra assure  [--config <file>] [--json]  Route-assurance gate: load nifra.assurance.ts, classify every
                                          reflected backend route, and fail when required enforcement
                                          evidence is missing/forbidden or a route is unclassified.
@@ -148,7 +152,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 = "2.9.0"
+const CLI_VERSION = "2.10.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
@@ -619,6 +623,30 @@ async function main(): Promise<void> {
     }
     return
   }
+  if (command === "sdk") {
+    const languageIndex = argv.indexOf("--lang")
+    const language = languageIndex === -1 ? undefined : argv[languageIndex + 1]
+    const outIndex = argv.indexOf("--out")
+    const out = outIndex === -1 ? undefined : argv[outIndex + 1]
+    if (language !== "python" && language !== "go") {
+      console.error("[nifra] sdk needs --lang python or --lang go")
+      process.exitCode = 1
+      return
+    }
+    if (outIndex !== -1 && (out === undefined || out.startsWith("-"))) {
+      console.error("[nifra] --out needs a file path")
+      process.exitCode = 1
+      return
+    }
+    try {
+      const { runSdk } = await import("./sdk.ts")
+      await runSdk(process.cwd(), { language, ...(out !== undefined ? { out } : {}) })
+    } catch (err) {
+      console.error(formatCliError(err))
+      process.exitCode = 1
+    }
+    return
+  }
   // Route assurance intentionally loads only its explicit config (which imports the backend it audits),
   // not the full SSR app. Like snapshot/diff, this works for API-only projects.
   if (command === "assure") {
@@ -823,7 +851,9 @@ async function main(): Promise<void> {
   else if (command === "build") await buildForTarget(app, flags.target, flags)
   else if (command === "context") console.log(describeProject(app))
   else if (command === "routes") {
-    if (argv.includes("--modes")) {
+    if (argv.includes("--graph")) {
+      console.log(await describeRouteGraph(app, { json: argv.includes("--json") }))
+    } else if (argv.includes("--modes")) {
       // `--modes` answers a different question than the default table: not "what URLs exist" but "how
       // does each render, and can the target I'm about to deploy to actually honour that". Resolves
       // against `--target` when given, so a `static` build's server-needing route fails here, in one

package/src/introspect.ts

@@ -430,6 +430,106 @@ export function routeTableToJson(rows: readonly RouteTableEntry[]): {
   }
 }
 
+export interface RouteGraphNode {
+  readonly id: string
+  readonly kind: "root" | RouteKind
+  readonly path: string
+  readonly methods?: readonly string[]
+  readonly file?: string
+  readonly autoMounted?: boolean
+}
+
+export interface RouteGraphEdge {
+  readonly from: string
+  readonly to: string
+}
+
+export interface RouteGraph {
+  readonly nodes: readonly RouteGraphNode[]
+  readonly edges: readonly RouteGraphEdge[]
+}
+
+function parentPath(path: string): string | undefined {
+  if (path === "/") return undefined
+  const trimmed = path.replace(/\/$/, "")
+  const slash = trimmed.lastIndexOf("/")
+  return slash <= 0 ? "/" : trimmed.slice(0, slash)
+}
+
+/** Build a stable parent/child graph from the public route table. Pure and topology-neutral. */
+export function buildRouteGraph(rows: readonly RouteTableEntry[]): RouteGraph {
+  const sorted = [...rows].sort(
+    (a, b) => a.path.localeCompare(b.path) || a.kind.localeCompare(b.kind),
+  )
+  const nodes: RouteGraphNode[] = [
+    { id: "root", kind: "root", path: "/" },
+    ...sorted.map((row) => ({
+      id: `${row.kind}:${row.path}`,
+      kind: row.kind,
+      path: row.path,
+      methods: row.methods,
+      ...(row.file === undefined ? {} : { file: row.file }),
+      ...(row.kind === "api" ? { autoMounted: row.autoMounted === true } : {}),
+    })),
+  ]
+  const nodeIds = new Set(nodes.map((node) => node.id))
+  const edges: RouteGraphEdge[] = []
+  for (const row of sorted) {
+    let parent = parentPath(row.path)
+    let from = "root"
+    while (parent !== undefined) {
+      const candidate = `${row.kind}:${parent}`
+      if (nodeIds.has(candidate)) {
+        from = candidate
+        break
+      }
+      parent = parentPath(parent)
+    }
+    edges.push({ from, to: `${row.kind}:${row.path}` })
+  }
+  return { nodes, edges }
+}
+
+/** Stable JSON shape for agents and contract explorers. */
+export function routeGraphToJson(graph: RouteGraph): RouteGraph {
+  return {
+    nodes: graph.nodes.map((node) => ({
+      ...node,
+      ...(node.methods === undefined ? {} : { methods: [...node.methods] }),
+    })),
+    edges: graph.edges.map((edge) => ({ ...edge })),
+  }
+}
+
+function mermaidText(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll(/[\r\n]/g, " ")
+}
+
+function mermaidLabel(node: RouteGraphNode): string {
+  if (node.kind === "root") return "routes"
+  const methods = node.methods?.join(", ") ?? ""
+  const mounted = node.autoMounted === true ? " (auto-mounted)" : ""
+  return mermaidText(`${node.kind}: ${methods} ${node.path}${mounted}`)
+}
+
+/** Render a route graph as Mermaid for terminals, docs, and agent-facing previews. */
+export function renderRouteGraph(graph: RouteGraph): string {
+  const ids = new Map(graph.nodes.map((node, index) => [node.id, `n${index}`]))
+  const lines = ["flowchart TD"]
+  for (const node of graph.nodes) {
+    lines.push(`  ${ids.get(node.id)}["${mermaidLabel(node)}"]`)
+  }
+  for (const edge of graph.edges) {
+    lines.push(`  ${ids.get(edge.from)} --> ${ids.get(edge.to)}`)
+  }
+  return lines.join("\n")
+}
+
 /** A route module that may export an `action` (→ the page serves POST). */
 interface MaybeActionModule {
   readonly action?: unknown
@@ -441,10 +541,7 @@ interface MaybeActionModule {
  * text (default) or JSON (`--json`). The page-route load mirrors what SSR would do; a load failure
  * degrades to GET-only for that route (never throws the whole command).
  */
-export async function describeRoutes(
-  app: LoadedApp,
-  opts: { readonly json?: boolean } = {},
-): Promise<string> {
+async function collectRouteTable(app: LoadedApp): Promise<RouteTableEntry[]> {
   let manifest: Manifest | undefined
   try {
     manifest = discoverRoutes(app.routesDir)
@@ -463,5 +560,22 @@ export async function describeRoutes(
     pages.push({ pattern: route.pattern, file: route.file, hasAction })
   }
   const rows = buildRouteTable({ pages, api: backendRoutes(app.backend) })
+  return rows
+}
+
+export async function describeRoutes(
+  app: LoadedApp,
+  opts: { readonly json?: boolean } = {},
+): Promise<string> {
+  const rows = await collectRouteTable(app)
   return opts.json ? JSON.stringify(routeTableToJson(rows), null, 2) : renderRouteTable(rows)
 }
+
+/** Gather and render the public route graph for `nifra routes --graph`. */
+export async function describeRouteGraph(
+  app: LoadedApp,
+  opts: { readonly json?: boolean } = {},
+): Promise<string> {
+  const graph = buildRouteGraph(await collectRouteTable(app))
+  return opts.json ? JSON.stringify(routeGraphToJson(graph), null, 2) : renderRouteGraph(graph)
+}

package/src/mcp-http.ts

@@ -29,7 +29,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 = "2.9.0"
+const VERSION = "2.10.0"
 const SERVER_INFO = { name: "nifra-docs", version: VERSION }
 // Derive the GET/health tool list from the tools actually served, so the line can never drift from them.
 const docsHealth = (tools: McpTool[]): string =>

package/src/sdk.ts

@@ -0,0 +1,260 @@
+/** Deterministic, dependency-free SDK generation from the backend's OpenAPI contract. */
+import { existsSync } from "node:fs"
+import { basename, resolve } from "node:path"
+import { type OpenAPIDocument, toOpenAPI } from "@nifrajs/schema/openapi"
+
+export type SdkLanguage = "python" | "go"
+
+interface OperationLike {
+  readonly operationId?: string
+  readonly parameters?: readonly {
+    readonly name: string
+    readonly in: "path" | "query"
+    readonly required: boolean
+  }[]
+  readonly requestBody?: unknown
+}
+
+const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "head", "options"] as const
+
+function operations(
+  document: OpenAPIDocument,
+): readonly { method: string; path: string; operation: OperationLike }[] {
+  const result: { method: string; path: string; operation: OperationLike }[] = []
+  for (const [path, item] of Object.entries(document.paths).sort(([a], [b]) =>
+    a.localeCompare(b),
+  )) {
+    for (const method of HTTP_METHODS) {
+      const operation = (item as Record<string, unknown>)[method]
+      if (operation !== null && typeof operation === "object") {
+        result.push({ method, path, operation: operation as OperationLike })
+      }
+    }
+  }
+  return result
+}
+
+function identifier(value: string, fallback: string): string {
+  const startsWithDigit = /^\d/.test(value)
+  const normalized = value
+    .replace(/[^A-Za-z0-9_]+/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_+|_+$/g, "")
+  const safe = startsWithDigit ? `_${normalized}` : normalized
+  return safe === "" || safe === "_" ? fallback : safe
+}
+
+function operationName(operation: OperationLike, method: string, path: string): string {
+  return identifier(operation.operationId ?? `${method}_${path}`, `${method}_request`)
+}
+
+function uniqueNames(items: readonly string[]): readonly string[] {
+  const counts = new Map<string, number>()
+  return items.map((item) => {
+    const count = (counts.get(item) ?? 0) + 1
+    counts.set(item, count)
+    return count === 1 ? item : `${item}_${count}`
+  })
+}
+
+function pathParameters(path: string): readonly string[] {
+  return [...path.matchAll(/\{([^}]+)\}/g)].map((match) => match[1]!).filter(Boolean)
+}
+
+function pythonSdk(document: OpenAPIDocument): string {
+  const entries = operations(document)
+  const names = uniqueNames(
+    entries.map(({ method, path, operation }) => operationName(operation, method, path)),
+  )
+  const methods: string[] = []
+  entries.forEach(({ method, path, operation }, index) => {
+    const name = names[index]!
+    const pathParams = pathParameters(path)
+    const queryParams = (operation.parameters ?? []).filter((parameter) => parameter.in === "query")
+    const used = new Set(["self", "body", ...pathParams])
+    const queryNames = queryParams.map((parameter) => {
+      let value = identifier(parameter.name, "query")
+      while (used.has(value)) value += "_"
+      used.add(value)
+      return value
+    })
+    const args = pathParams.map((parameter) => `${identifier(parameter, "param")}: Any`)
+    const keywordArgs = queryParams.map((parameter, queryIndex) => {
+      const required = parameter.required ? "" : " = None"
+      return `${queryNames[queryIndex]!}: Any${required}`
+    })
+    if (operation.requestBody !== undefined) keywordArgs.push("body: Any = None")
+    const signature = [...args, ...(keywordArgs.length > 0 ? ["*", ...keywordArgs] : [])].join(", ")
+    const query =
+      queryNames.length === 0
+        ? "None"
+        : `{${queryNames.map((value) => `${JSON.stringify(value)}: ${value}`).join(", ")}}`
+    const paths =
+      pathParams.length === 0
+        ? "None"
+        : `{${pathParams.map((value) => `${JSON.stringify(value)}: ${identifier(value, "param")}`).join(", ")}}`
+    const body = operation.requestBody === undefined ? "None" : "body"
+    methods.push(
+      `    def ${name}(self${signature ? `, ${signature}` : ""}) -> Any:\n` +
+        `        return self._request(${JSON.stringify(method.toUpperCase())}, ${JSON.stringify(path)}, path_params=${paths}, query=${query}, body=${body})`,
+    )
+  })
+  return `# Generated by nifra. Regenerate with: nifra sdk --lang python
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Mapping
+
+
+class NifraApiError(RuntimeError):
+    def __init__(self, status: int, body: Any):
+        super().__init__(f"Nifra API request failed with HTTP {status}")
+        self.status = status
+        self.body = body
+
+
+class Client:
+    def __init__(self, base_url: str, headers: Mapping[str, str] | None = None, timeout: float = 30.0):
+        self.base_url = base_url.rstrip("/")
+        self.headers = dict(headers or {})
+        self.timeout = timeout
+
+    def _request(self, method: str, path: str, *, path_params: Mapping[str, Any] | None, query: Mapping[str, Any] | None, body: Any) -> Any:
+        route = path
+        for key, value in (path_params or {}).items():
+            route = route.replace("{" + key + "}", urllib.parse.quote(str(value), safe=""))
+        params = [(key, value) for key, value in (query or {}).items() if value is not None]
+        url = self.base_url + route
+        if params:
+            url += ("&" if "?" in url else "?") + urllib.parse.urlencode(params, doseq=True)
+        payload = None if body is None else json.dumps(body).encode("utf-8")
+        request = urllib.request.Request(url, data=payload, method=method, headers=self.headers)
+        if payload is not None:
+            request.add_header("Content-Type", "application/json")
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                raw = response.read()
+                return json.loads(raw) if raw else None
+        except urllib.error.HTTPError as error:
+            raw = error.read()
+            try:
+                value = json.loads(raw) if raw else None
+            except json.JSONDecodeError:
+                value = raw.decode("utf-8", errors="replace")
+            raise NifraApiError(error.code, value) from error
+
+${methods.length === 0 ? "    pass" : methods.join("\n\n")}
+`
+}
+
+function goExportName(value: string): string {
+  const name = identifier(value, "Request")
+  return name[0]!.toUpperCase() + name.slice(1)
+}
+
+function goSdk(document: OpenAPIDocument): string {
+  const entries = operations(document)
+  const names = uniqueNames(
+    entries.map(({ method, path, operation }) => operationName(operation, method, path)),
+  )
+  const methods: string[] = []
+  entries.forEach(({ method, path }, index) => {
+    const pathParams = pathParameters(path)
+    const args = pathParams.map((parameter) => `${identifier(parameter, "param")} string`)
+    args.push("query url.Values", "body any")
+    const pathMap =
+      pathParams.length === 0
+        ? "nil"
+        : `map[string]string{${pathParams.map((value) => `${JSON.stringify(value)}: ${identifier(value, "param")}`).join(", ")}}`
+    methods.push(
+      `func (c *Client) ${goExportName(names[index]!)}(${args.join(", ")}) (any, error) {\n` +
+        `    return c.request(http.Method${method[0]!.toUpperCase()}${method.slice(1)}, ${JSON.stringify(path)}, ${pathMap}, query, body)\n` +
+        `}`,
+    )
+  })
+  return `// Code generated by nifra. Regenerate with: nifra sdk --lang go
+package nifrasdk
+
+import (
+    "bytes"
+    "encoding/json"
+    "fmt"
+    "io"
+    "net/http"
+    "net/url"
+    "strings"
+)
+
+type Client struct {
+    BaseURL string
+    HTTP *http.Client
+    Headers http.Header
+}
+
+func NewClient(baseURL string) *Client {
+    return &Client{BaseURL: strings.TrimRight(baseURL, "/"), HTTP: http.DefaultClient, Headers: make(http.Header)}
+}
+
+func (c *Client) request(method, path string, pathParams map[string]string, query url.Values, body any) (any, error) {
+    route := path
+    for key, value := range pathParams {
+        route = strings.ReplaceAll(route, "{"+key+"}", url.PathEscape(value))
+    }
+    target := c.BaseURL + route
+    parsed, err := url.Parse(target)
+    if err != nil { return nil, err }
+    parsed.RawQuery = query.Encode()
+    var reader io.Reader
+    if body != nil {
+        payload, err := json.Marshal(body)
+        if err != nil { return nil, err }
+        reader = bytes.NewReader(payload)
+    }
+    request, err := http.NewRequest(method, parsed.String(), reader)
+    if err != nil { return nil, err }
+    for key, values := range c.Headers { for _, value := range values { request.Header.Add(key, value) } }
+    if body != nil { request.Header.Set("Content-Type", "application/json") }
+    response, err := c.HTTP.Do(request)
+    if err != nil { return nil, err }
+    defer response.Body.Close()
+    raw, err := io.ReadAll(response.Body)
+    if err != nil { return nil, err }
+    var value any
+    if len(raw) > 0 { if err := json.Unmarshal(raw, &value); err != nil { value = string(raw) } }
+    if response.StatusCode < 200 || response.StatusCode >= 300 { return nil, fmt.Errorf("nifra API request failed with HTTP %d: %v", response.StatusCode, value) }
+    return value, nil
+}
+
+${methods.length === 0 ? "// No operations were found.\n" : `${methods.join("\n\n")}\n`}`
+}
+
+/** Render a generated SDK. Python uses the standard library; Go uses net/http. */
+export function renderSdk(document: OpenAPIDocument, language: SdkLanguage): string {
+  return language === "python" ? pythonSdk(document) : goSdk(document)
+}
+
+/** Load `backend.ts`, generate an SDK, and write it to the project. */
+export async function runSdk(
+  cwd: string,
+  options: { readonly language: SdkLanguage; readonly out?: string },
+): Promise<void> {
+  const backendPath = resolve(cwd, "backend.ts")
+  if (!existsSync(backendPath)) {
+    throw new Error(`[nifra] no backend.ts in ${cwd} - SDK generation needs the API contract.`)
+  }
+  const backend = ((await import(backendPath)) as { backend?: unknown }).backend
+  if (backend === undefined) throw new Error(`[nifra] ${backendPath} does not export \`backend\`.`)
+  const document = toOpenAPI(backend as Parameters<typeof toOpenAPI>[0], {
+    title: `${basename(cwd)} API`,
+    version: "1.0.0",
+  })
+  const extension = options.language === "python" ? "py" : "go"
+  const out = resolve(cwd, options.out ?? `nifra_sdk.${extension}`)
+  await Bun.write(out, renderSdk(document, options.language))
+  console.log(
+    `[nifra] wrote ${options.language} SDK with ${Object.keys(document.paths).length} path${Object.keys(document.paths).length === 1 ? "" : "s"} to ${out}`,
+  )
+}