@nifrajs/cli 2.3.0 → 2.4.0

package/docs/types.json

@@ -128,13 +128,13 @@
     "name": "AdversarialContractOptions",
     "kind": "interface",
     "package": "@nifrajs/testing",
-    "signature": "export interface AdversarialContractOptions {\n    /** Base origin for generated requests. Default `http://nifra.contract`. */\n    readonly origin?: string;\n    /** Replayable seed used for deterministic witness generation. */\n    readonly seed?: number;\n    /** Known-good request values keyed by `\"METHOD /path\"`. Required for opaque Standard Schemas. */\n    readonly witnesses?: Readonly<Record<string, ContractWitness>>;\n    /** Select a subset of reflected routes. */\n    readonly include?: (route: ReflectedRoute) => boolean;\n    /** Execute every case against these targets. Default: the supplied app, named `in-process`. */\n    readonly runtimes?: readonly ContractRuntime[];\n    /** Maximum validator-proven mutations per body/query schema. Default 32. */\n    readonly maxMutationsPerInput?: number;\n    /** Maximum serialized witness size. Default 256 KiB. */\n    readonly maxWitnessBytes?: number;\n    /** Statuses that prove an invalid input was rejected. Default `[422]`. */\n    readonly expectedValidationStatuses?: readonly number[];\n    /**\n     * Attach auth, tenant, or runtime-specific state. Return a new Request; the input Request is already\n     * fresh for this case and runtime.\n     */\n    readonly prepareRequest?: (request: Request, context: ContractCaseContext) => Request | Promise<Request>;\n    /** Override rejection semantics (for apps with a custom validation response). */\n    readonly isRejected?: (response: Response, context: ContractCaseContext) => boolean | Promise<boolean>;\n    /** Validate a real successful response for every declared response schema. Default true. */\n    readonly validateResponses?: boolean;\n    /** Fail the report when a contracted target cannot be exercised. Default true. */\n    readonly requireCoverage?: boolean;\n    /** Greedily minimize an invalid input that unexpectedly reaches the app. Default true. */\n    readonly shrinkFailures?: boolean;\n    /** Cap shrink probes for one failure. Default 12. */\n    readonly maxShrinkAttempts?: number;\n    /** Replay only these stable case IDs. Coverage gaps are advisory when this is set. */\n    readonly only?: string | readonly string[];\n}"
+    "signature": "export interface AdversarialContractOptions {\n    /** Base origin for generated requests. Default `http://nifra.contract`. */\n    readonly origin?: string;\n    /** Replayable seed used for deterministic witness generation. */\n    readonly seed?: number;\n    /** Known-good request values keyed by `\"METHOD /path\"`. Required for opaque Standard Schemas. */\n    readonly witnesses?: Readonly<Record<string, ContractWitness>>;\n    /** Select a subset of reflected routes. */\n    readonly include?: (route: ReflectedRoute) => boolean;\n    /** Execute every case against these targets. Default: the supplied app, named `in-process`. */\n    readonly runtimes?: readonly ContractRuntime[];\n    /** Maximum validator-proven mutations per body/query schema. Default 32. */\n    readonly maxMutationsPerInput?: number;\n    /** Maximum serialized witness size. Default 256 KiB. */\n    readonly maxWitnessBytes?: number;\n    /** Statuses that prove an invalid input was rejected. Default `[422]`. */\n    readonly expectedValidationStatuses?: readonly number[];\n    /**\n     * Attach auth, tenant, or runtime-specific state. Return a new Request; the input Request is already\n     * fresh for this case and runtime.\n     */\n    readonly prepareRequest?: (request: Request, context: ContractCaseContext) => Request | Promise<Request>;\n    /** Override rejection semantics (for apps with a custom validation response). */\n    readonly isRejected?: (response: Response, context: ContractCaseContext) => boolean | Promise<boolean>;\n    /** Validate a real successful response for every declared response schema. Default true. */\n    readonly validateResponses?: boolean;\n    /** Fail the report when a contracted target cannot be exercised. Default true. */\n    readonly requireCoverage?: boolean;\n    /** Greedily minimize an invalid input that unexpectedly reaches the app. Default true. */\n    readonly shrinkFailures?: boolean;\n    /** Cap shrink probes for one failure. Default 12. */\n    readonly maxShrinkAttempts?: number;\n    /** Replay only these stable case IDs. Coverage gaps are advisory when this is set. */\n    readonly only?: string | readonly string[];\n    /**\n     * Derive an inspectable JSON Schema from a validator that carries none (zod/valibot/arktype expose a\n     * Standard Schema validator but no `.jsonSchema`). Called for any body/query schema whose `jsonSchema`\n     * is undefined; a non-undefined return turns on witness synthesis AND constraint-driven mutation\n     * generation for that route. Fail-safe: throwing or returning undefined leaves the schema opaque\n     * (NO_WITNESS, as today). Ready-made for zod: `import { zodJsonSchema } from \"@nifrajs/testing/zod\"`.\n     */\n    readonly reflectJsonSchema?: (schema: unknown) => JsonSchema | undefined;\n}"
   },
   {
     "name": "AdversarialContractReport",
     "kind": "interface",
     "package": "@nifrajs/testing",
-    "signature": "export interface AdversarialContractReport {\n    readonly ok: boolean;\n    readonly seed: number;\n    readonly routeCount: number;\n    readonly targetCount: number;\n    readonly runtimeCount: number;\n    readonly results: readonly AdversarialContractResult[];\n    readonly failures: readonly AdversarialContractResult[];\n    readonly gaps: readonly ContractCoverageGap[];\n    readonly counts: {\n        readonly passed: number;\n        readonly failed: number;\n        readonly gaps: number;\n    };\n}"
+    "signature": "export interface AdversarialContractReport {\n    readonly ok: boolean;\n    readonly seed: number;\n    readonly routeCount: number;\n    readonly targetCount: number;\n    readonly runtimeCount: number;\n    readonly results: readonly AdversarialContractResult[];\n    readonly failures: readonly AdversarialContractResult[];\n    readonly gaps: readonly ContractCoverageGap[];\n    /** Non-fatal notes about coverage that is legitimately absent (does not affect `ok`). */\n    readonly advisories: readonly string[];\n    readonly counts: {\n        readonly passed: number;\n        readonly failed: number;\n        readonly gaps: number;\n    };\n}"
   },
   {
     "name": "AdversarialContractResult",
@@ -931,6 +931,26 @@
     "signature": "export interface BuildClientViteOptions extends Omit<BuildClientOptions, \"plugins\"> {\n    /** Vite plugins for the app's client transforms (e.g. `react()`, `vue()`). */\n    readonly vitePlugins?: readonly unknown[];\n    /** Vite project root (default: the parent of `routesDir`). Manifest keys are relative to it. */\n    readonly root?: string;\n}",
     "doc": "/** Options for {@link buildClientVite} - the Bun {@link BuildClientOptions} minus Bun-plugin specifics,\n * plus the Vite plugin list the app injects for its transforms. */"
   },
+  {
+    "name": "buildCodeframe",
+    "kind": "function",
+    "package": "@nifrajs/web",
+    "signature": "export declare function buildCodeframe(file: string, line: number, column: number | undefined, read?: SourceReader, radius?: number): Codeframe | undefined;",
+    "doc": "/**\n * Build a source codeframe: `radius` lines either side of `line`, each tagged with its 1-based number\n * and whether it is the offending line. Returns undefined if the source can't be read or the line is\n * out of range - a diagnostic without a codeframe is still useful, so this never throws.\n */"
+  },
+  {
+    "name": "buildDiagnostic",
+    "kind": "function",
+    "package": "@nifrajs/web",
+    "signature": "export declare function buildDiagnostic(err: unknown, options?: BuildDiagnosticOptions): Diagnostic;",
+    "doc": "/**\n * Resolve any thrown value into a `Diagnostic`: parse the (already source-mapped) stack, locate the top\n * user frame, attach a codeframe, and classify the failure for a cause/fix. The caller is responsible\n * for running Vite's `ssrFixStacktrace` first so the frames point at real source.\n */"
+  },
+  {
+    "name": "BuildDiagnosticOptions",
+    "kind": "interface",
+    "package": "@nifrajs/web",
+    "signature": "export interface BuildDiagnosticOptions {\n    readonly request?: {\n        readonly method: string;\n        readonly url: string;\n    };\n    /** Project root; frames outside it are treated as non-user. Defaults to `process.cwd()`. */\n    readonly root?: string;\n    /** Injectable source reader (tests pass a fake; production reads the filesystem). */\n    readonly read?: SourceReader;\n}"
+  },
   {
     "name": "buildManifest",
     "kind": "function",
@@ -1718,6 +1738,13 @@
     "package": "@nifrajs/core",
     "signature": "export type ClassifiedSchema<S extends object> = S & {\n    readonly [CLASSIFICATION]: DataClassification;\n};"
   },
+  {
+    "name": "classify",
+    "kind": "function",
+    "package": "@nifrajs/web",
+    "signature": "export declare function classify(name: string, message: string): {\n    code: string;\n    cause?: string;\n    fix?: string;\n    docsAnchor?: string;\n};",
+    "doc": "/** Classify an error name+message against the catalog; falls back to the generic unhandled code. */"
+  },
   {
     "name": "CLAUDE_MD_PATH",
     "kind": "const",
@@ -1823,6 +1850,13 @@
     "package": "@nifrajs/web",
     "signature": "export interface CloudflareRouteRules {\n    readonly include: readonly string[];\n    readonly exclude: readonly string[];\n    /** Public files the budget could not name, so the build can say so instead of capping silently. */\n    readonly omitted: readonly string[];\n}"
   },
+  {
+    "name": "Codeframe",
+    "kind": "interface",
+    "package": "@nifrajs/web",
+    "signature": "export interface Codeframe {\n    readonly file: string;\n    readonly line: number;\n    readonly column?: number | undefined;\n    readonly lines: ReadonlyArray<{\n        readonly number: number;\n        readonly text: string;\n        readonly caret: boolean;\n    }>;\n}",
+    "doc": "/** A source window around the offending line. `caret` marks the exact line the top frame points at. */"
+  },
   {
     "name": "Collection",
     "kind": "interface",
@@ -2931,8 +2965,7 @@
     "name": "devtools",
     "kind": "function",
     "package": "@nifrajs/devtools",
-    "signature": "export declare function devtools(options?: DevToolsOptions | undefined): import(\"@nifrajs/core/server\").NifraPlugin<import(\"@nifrajs/core/server\").AnyServer, import(\"@nifrajs/core/server\").AnyServer>;",
-    "doc": "/**\n * DevTools plugin. Its observation adapter projects the single request span into a\n * `DevToolsEvent`; its middleware only owns the secured SSE transport.\n * When configuring `tracing()` yourself, register it before this plugin so DevTools attaches to\n * that request owner.\n */"
+    "signature": "export declare function devtools(options?: DevToolsOptions | undefined): import(\"@nifrajs/core/server\").NifraPlugin<import(\"@nifrajs/core/server\").AnyServer, import(\"@nifrajs/core/server\").AnyServer>;"
   },
   {
     "name": "DevToolsClientOptions",
@@ -2960,6 +2993,34 @@
     "package": "@nifrajs/devtools",
     "signature": "export interface DevToolsOptions {\n    /** Maximum events to retain in the ring buffer (default 200). */\n    readonly maxEvents?: number | undefined;\n    /** Maximum simultaneous SSE connections (default 5). */\n    readonly maxConnections?: number | undefined;\n    /** SSE path (default `/_nifra/devtools`). */\n    readonly path?: string | undefined;\n    /** Explicit enable switch. Defaults to true only when `NODE_ENV === \"development\"`. */\n    readonly enabled?: boolean | undefined;\n    /** Permit non-loopback URL hosts. Default false. */\n    readonly allowRemote?: boolean | undefined;\n    /** Additional origins permitted to open the stream. Same-origin requests are always allowed. */\n    readonly allowedOrigins?: readonly string[] | undefined;\n    /** Optional request authorization for the stream. */\n    readonly authorize?: ((request: Request) => boolean | Promise<boolean>) | undefined;\n    /**\n     * Interval for SSE keep-alive comment frames, in milliseconds (default 15000). Pings stop\n     * idle proxies/dev tunnels from dropping the stream and evict dead connections so they no\n     * longer count against `maxConnections`.\n     */\n    readonly pingIntervalMs?: number | undefined;\n}"
   },
+  {
+    "name": "DevToolsQuery",
+    "kind": "interface",
+    "package": "@nifrajs/devtools",
+    "signature": "export interface DevToolsQuery {\n    readonly path?: string | undefined;\n    readonly limit?: number | undefined;\n}",
+    "doc": "/** Query for a DevTools state snapshot: an optional `path` prefix and a most-recent-`limit`. */"
+  },
+  {
+    "name": "Diagnostic",
+    "kind": "interface",
+    "package": "@nifrajs/web",
+    "signature": "export interface Diagnostic {\n    /** Stable, greppable identifier, e.g. `NIFRA_SERVER_ONLY_IN_CLIENT`. `NIFRA_UNHANDLED` when unrecognised. */\n    readonly code: string;\n    readonly name: string;\n    readonly message: string;\n    readonly request?: {\n        readonly method: string;\n        readonly url: string;\n    } | undefined;\n    readonly frames: readonly DiagnosticFrame[];\n    readonly codeframe?: Codeframe | undefined;\n    /** Plain-language \"why this happened\", when the failure is recognised. */\n    readonly cause?: string | undefined;\n    /** Plain-language \"do this\", when the failure is recognised. */\n    readonly fix?: string | undefined;\n    /** Docs section anchor for the code, e.g. `errors#server-only-in-client`. */\n    readonly docsAnchor?: string | undefined;\n}",
+    "doc": "/** The structured failure. Serialisable as-is to JSON for the agent surfaces. */"
+  },
+  {
+    "name": "DIAGNOSTIC_CATALOG",
+    "kind": "const",
+    "package": "@nifrajs/web",
+    "signature": "export declare const DIAGNOSTIC_CATALOG: readonly CatalogEntry[];",
+    "doc": "/**\n * The recognised-failure catalog. Seeded with the highest-signal nifra failures; extend it as new\n * classes of error earn a stable code. Order matters only in that the first match wins.\n */"
+  },
+  {
+    "name": "DiagnosticFrame",
+    "kind": "interface",
+    "package": "@nifrajs/web",
+    "signature": "export interface DiagnosticFrame {\n    readonly raw: string;\n    readonly file?: string;\n    readonly line?: number;\n    readonly column?: number;\n}",
+    "doc": "/** One parsed stack frame. `file`/`line`/`column` are present only when the frame could be located. */"
+  },
   {
     "name": "diffManifestRoutes",
     "kind": "function",
@@ -3526,6 +3587,20 @@
     "signature": "export interface Example {\n    readonly name: string;\n    /** The doc page's title, e.g. \"Nifra - Auth & sessions\". */\n    readonly topic: string;\n    /** The doc page slug, e.g. \"auth\" - a short, matchable tag. */\n    readonly slug: string;\n    readonly code: string;\n}",
     "doc": "/**\n * `nifra_example` - verified, copy-pasteable code examples for agents. The corpus is `examples.json`\n * (written into this package by `bun run gen:llms`): the same doc snippets `check:docs` typechecks\n * against the live `@nifrajs/*` API. So every example this returns is GUARANTEED to compile against the\n * installed version - the antidote to an agent hallucinating a framework API from stale training.\n *\n * Keyword-scored over each example's name/topic/slug (curated identifiers, heavily weighted) and its\n * code body. No query → a grouped index of what's available (the cheap discovery call).\n */"
   },
+  {
+    "name": "examplesAppTool",
+    "kind": "function",
+    "package": "@nifrajs/cli",
+    "signature": "export declare function examplesAppTool(loadExamples: () => Promise<Example[] | undefined>): McpTool;",
+    "doc": "/** The widget-backed tool. `loadExamples` is injected (disk on the CLI, cached fetch on the edge). */"
+  },
+  {
+    "name": "examplesWidget",
+    "kind": "const",
+    "package": "@nifrajs/cli",
+    "signature": "export declare const examplesWidget: import(\"@nifrajs/mcp\").McpWidget;",
+    "doc": "/** The widget: renders `structuredContent.examples` as a filterable list of example cards. */"
+  },
   {
     "name": "executeCapability",
     "kind": "function",
@@ -3732,6 +3807,27 @@
     "signature": "export interface FileType {\n    /** Detected MIME type, e.g. `\"image/png\"`. */\n    readonly mime: string;\n    /** Canonical extension (no dot), e.g. `\"png\"`. */\n    readonly ext: string;\n}",
     "doc": "/**\n * Magic-byte file-type detection - trust the bytes, not the `Content-Type` header (which a client\n * sets freely). Reads only the leading bytes; dependency-free + edge-safe. Covers the common upload\n * types; returns `null` for anything unrecognized (incl. text formats like SVG/CSV that have no magic\n * number - handle those explicitly if you accept them).\n */"
   },
+  {
+    "name": "filterDevToolsEvents",
+    "kind": "function",
+    "package": "@nifrajs/devtools",
+    "signature": "export declare function filterDevToolsEvents(events: readonly DevToolsEvent[], query?: DevToolsQuery): DevToolsEvent[];",
+    "doc": "/**\n * Filter a DevTools event buffer for a snapshot query - by `path` prefix and/or the most recent\n * `limit`. Pure, so the `/state` endpoint and its tests (and the `nifra_inspect` MCP tool that reads\n * that endpoint) share ONE definition of what a query returns.\n */"
+  },
+  {
+    "name": "findRoutePathLiteral",
+    "kind": "function",
+    "package": "@nifrajs/ts-plugin",
+    "signature": "export declare function findRoutePathLiteral(tsm: typeof ts, source: ts.SourceFile, position: number): {\n    text: string;\n    span: ts.TextSpan;\n} | undefined;",
+    "doc": "/**\n * If `position` sits on a string-literal route path (`\"/...\"`), return its text and the span INSIDE the\n * quotes (so the editor highlights the path, not the quotes). Exported for unit testing against a\n * `SourceFile` built with `ts.createSourceFile`.\n */"
+  },
+  {
+    "name": "findRoutesDir",
+    "kind": "function",
+    "package": "@nifrajs/ts-plugin",
+    "signature": "export declare function findRoutesDir(fromFile: string, exists?: (p: string) => boolean): string | undefined;",
+    "doc": "/** Walk up from a source file to the nearest directory that has a `routes/` folder - the app root. */"
+  },
   {
     "name": "fixedBackoff",
     "kind": "const",
@@ -4054,7 +4150,7 @@
     "kind": "function",
     "package": "@nifrajs/cli",
     "signature": "export declare function handleMcpHttp(request: Request): Promise<Response>;",
-    "doc": "/** The CLI HTTP handler: serves the disk-backed corpus tools. (`nifra docs-mcp` / `bun run` this file.) */"
+    "doc": "/** The CLI HTTP handler: serves the disk-backed corpus tools + registers the examples widget's `ui://`\n * resource so MCP Apps hosts can render `nifra_examples_app`. (`nifra docs-mcp` / `bun run` this file.) */"
   },
   {
     "name": "Handler",
@@ -5071,6 +5167,13 @@
     "package": "@nifrajs/middleware",
     "signature": "export interface LanguageOptions<L extends readonly string[]> {\n    readonly supported: L;\n    readonly defaultLanguage: L[number];\n    /** Emit `Content-Language`. Default `true`. */\n    readonly header?: boolean;\n}"
   },
+  {
+    "name": "LAST_ERROR_PATH",
+    "kind": "const",
+    "package": "@nifrajs/web",
+    "signature": "export declare const LAST_ERROR_PATH = \"/__nifra/last-error\";",
+    "doc": "/** Shared endpoint name used by both dev pipelines and the agent-facing MCP tools. */"
+  },
   {
     "name": "LAYOUT_DATA_GLOBAL",
     "kind": "const",
@@ -5831,7 +5934,7 @@
     "name": "MockServerOptions",
     "kind": "interface",
     "package": "@nifrajs/mock",
-    "signature": "export interface MockServerOptions {\n    /** Seed for deterministic mock generation. */\n    readonly seed?: number | undefined;\n    /** Log mock requests to console. */\n    readonly verbose?: boolean | undefined;\n}"
+    "signature": "export interface MockServerOptions {\n    /** Seed for deterministic mock generation. */\n    readonly seed?: number | undefined;\n    /** Log mock requests to console. */\n    readonly verbose?: boolean | undefined;\n    /**\n     * Derive a JSON Schema from a response validator that carries none (zod/valibot expose a Standard Schema\n     * validator but no `.jsonSchema`), so their routes mock real data instead of `{}`. Fail-safe: throwing or\n     * returning undefined falls back to `{}`, as today. Ready-made for zod: `@nifrajs/testing/zod`.\n     */\n    readonly reflectJsonSchema?: (schema: unknown) => JsonSchema | undefined;\n}"
   },
   {
     "name": "mountIslands",
@@ -6542,6 +6645,13 @@
     "package": "@nifrajs/content",
     "signature": "export interface ParseEntryOptions<S extends StandardSchemaV1> {\n    readonly raw: string;\n    readonly slug: string;\n    /** Standard Schema validating the frontmatter - a typo'd/missing field throws (a build-time failure,\n     * never a broken page). */\n    readonly schema: S;\n}"
   },
+  {
+    "name": "parseFrames",
+    "kind": "function",
+    "package": "@nifrajs/web",
+    "signature": "export declare function parseFrames(stack: string): DiagnosticFrame[];",
+    "doc": "/**\n * Parse a V8/Node stack into structured frames. Handles the `at fn (path:line:col)`, bare\n * `at path:line:col`, and `at async fn (...)` shapes; a frame that doesn't match keeps its raw text\n * with no location (so nothing is silently dropped).\n */"
+  },
   {
     "name": "parseFrontmatter",
     "kind": "function",
@@ -6933,7 +7043,7 @@
     "kind": "function",
     "package": "@nifrajs/cli",
     "signature": "export declare function publicDocsTools(): McpTool[];",
-    "doc": "/** The two project-independent tools, reading the package's bundled corpus from disk (CLI use). */"
+    "doc": "/** The project-independent tools, reading the package's bundled corpus from disk (CLI use): the text\n * docs tools plus the `nifra_examples_app` MCP Apps widget tool. */"
   },
   {
     "name": "publicEnvDefines",
@@ -7601,6 +7711,13 @@
     "signature": "export declare function resolvePublicPath(root: string, pathname: string): string | undefined;",
     "doc": "/**\n * Resolve a URL pathname to an absolute path **confined** to `root`, or `undefined` if it escapes.\n *\n * This is a user-path-to-filesystem sink, which makes it the one part of this feature with a security\n * consequence. Decode first (`%2e%2e%2f` is `../`), then normalize, then verify the result is still\n * under `root` by prefix - checking the *resolved* path rather than scanning the input for `..`,\n * because a blocklist over encodings is exactly the kind of check that gets bypassed.\n */"
   },
+  {
+    "name": "resolveRouteFile",
+    "kind": "function",
+    "package": "@nifrajs/ts-plugin",
+    "signature": "export declare function resolveRouteFile(path: string, routes: readonly RouteLocation[]): string | undefined;",
+    "doc": "/**\n * Resolve a route path literal to the first route whose pattern matches it. Query/hash are ignored\n * (a link's `?tab=x` does not change which route file serves it). Returns the route's `file`, or\n * undefined when the value is not a path or matches no route.\n */"
+  },
   {
     "name": "respondMcpHttp",
     "kind": "function",
@@ -7920,6 +8037,13 @@
     "signature": "export interface RouteLike {\n    readonly method: string;\n    readonly path: string;\n    readonly schema?: {\n        readonly body?: unknown;\n        readonly query?: unknown;\n        readonly response?: unknown;\n    } | undefined;\n}",
     "doc": "/** A registered route as seen by {@link buildOpenApiDocument} - structurally a `@nifrajs/core`\n * `RouteDescriptor` (so `app.routes()` is passed straight through). */"
   },
+  {
+    "name": "RouteLocation",
+    "kind": "interface",
+    "package": "@nifrajs/ts-plugin",
+    "signature": "export interface RouteLocation {\n    readonly pattern: string;\n    readonly file: string;\n}",
+    "doc": "/** A route as the plugin needs it: its URL pattern and the source file that serves it. */"
+  },
   {
     "name": "RouteManifest",
     "kind": "interface",
@@ -9130,6 +9254,20 @@
     "signature": "export declare function solidSvgComponentBunPlugin(generate: \"dom\" | \"ssr\"): BunPlugin;",
     "doc": "/** The Solid SVG-component plugin. `generate` selects the Solid `\"dom\"`/`\"ssr\"` output, matching\n * `solidBunPlugin`. A plain `import \"./icon.svg\"` (asset URL) is untouched - only `?component` matches. */"
   },
+  {
+    "name": "sortRoutesBySpecificity",
+    "kind": "function",
+    "package": "@nifrajs/core",
+    "signature": "export declare function sortRoutesBySpecificity<T extends {\n    readonly pattern: CompiledRoutePattern;\n}>(routes: T[]): T[];",
+    "doc": "/**\n * Sort compiled routes most-specific-first - a static segment beats a dynamic one, the order the router\n * resolves a path in. The single home for that precedence: the web router, the mock server, and the\n * editor plugin all order routes through this one comparator, so which file a path resolves to can never\n * diverge between runtime, client, and editor. Sorts in place and returns the same array.\n */"
+  },
+  {
+    "name": "SourceReader",
+    "kind": "type",
+    "package": "@nifrajs/web",
+    "signature": "export type SourceReader = (file: string) => string | undefined;",
+    "doc": "/** Reads a source file's text, or returns undefined if it cannot (missing, binary, permission). */"
+  },
   {
     "name": "SpanStatus",
     "kind": "type",
@@ -9855,6 +9993,13 @@
     "signature": "export declare class TopicRegistry {\n    private readonly topics;\n    private readonly memberships;\n    subscribe(topic: string, ws: NifraWebSocket): void;\n    unsubscribe(topic: string, ws: NifraWebSocket): void;\n    /** Drop every subscription for a connection - called on close so a registry never leaks dead sockets. */\n    unsubscribeAll(ws: NifraWebSocket): void;\n    /** Send `data` to every connection subscribed to `topic`. Per-socket send errors are isolated. */\n    publish(topic: string, data: string | ArrayBufferView | ArrayBuffer): void;\n}",
     "doc": "/**\n * In-process pub/sub for `ws.subscribe(topic)` + `app.publish(topic, data)`. **Single-instance only** -\n * topics live in this process's memory, so a multi-instance deploy (multiple servers behind a load\n * balancer) needs an external fan-out (Redis pub/sub, a Cloudflare Durable Object, NATS, …) bridged to\n * `app.publish`. The same registry instance is shared by an app's connections and its `publish`.\n */"
   },
+  {
+    "name": "topUserFrame",
+    "kind": "function",
+    "package": "@nifrajs/web",
+    "signature": "export declare function topUserFrame(frames: readonly DiagnosticFrame[], root: string | undefined): DiagnosticFrame | undefined;",
+    "doc": "/** The first frame that points at the user's own source - what the codeframe should show. */"
+  },
   {
     "name": "TraceContext",
     "kind": "type",
@@ -10048,8 +10193,7 @@
     "name": "UnsupportedMockSchemaError",
     "kind": "class",
     "package": "@nifrajs/mock",
-    "signature": "export declare class UnsupportedMockSchemaError extends Error {\n    readonly keyword: string;\n    constructor(keyword: string, message: string);\n}",
-    "doc": "/**\n * `@nifrajs/mock` - contract-based mock server.\n *\n * Reads a Nifra app's registered routes and their Standard Schema / JSON Schema\n * response definitions, then generates fake responses from supported JSON Schema keywords. Use it\n * for frontend-first development, agent testing, or CI smoke tests.\n */"
+    "signature": "export declare class UnsupportedMockSchemaError extends Error {\n    readonly keyword: string;\n    constructor(keyword: string, message: string);\n}"
   },
   {
     "name": "UploadResult",
@@ -10631,14 +10775,14 @@
     "name": "VERSION",
     "kind": "const",
     "package": "@nifrajs/core",
-    "signature": "export declare const VERSION: \"2.3.0\";",
+    "signature": "export declare const VERSION: \"2.4.0\";",
     "doc": "/**\n * Current package version. A hardcoded literal on purpose - core runs on the edge (no fs), so it can't\n * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and\n * `check:publish` asserts it equals `@nifrajs/core`'s package version.\n */"
   },
   {
     "name": "VERSION",
     "kind": "const",
     "package": "nifra",
-    "signature": "export declare const VERSION: \"2.3.0\";",
+    "signature": "export declare const VERSION: \"2.4.0\";",
     "doc": "/**\n * Current package version. A hardcoded literal on purpose - core runs on the edge (no fs), so it can't\n * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and\n * `check:publish` asserts it equals `@nifrajs/core`'s package version.\n */"
   },
   {
@@ -10933,5 +11077,12 @@
     "package": "@nifrajs/client",
     "signature": "export interface WsHandle<In, Out> {\n    /** Send one typed frame (JSON-encoded). Queued until the socket opens, so it never throws. */\n    send(message: In): void;\n    /** Async-iterate incoming typed frames. Ends when the socket closes (or `signal` aborts). */\n    messages(options?: {\n        signal?: AbortSignal;\n    }): AsyncIterableIterator<Out>;\n    /** Callback form of {@link messages}; returns an unsubscribe. */\n    onMessage(callback: (message: Out) => void): () => void;\n    /** Resolves when the socket is open (rejects on a connect failure). */\n    readonly opened: Promise<void>;\n    close(code?: number, reason?: string): void;\n    /** The underlying socket, for anything off the typed contract (binary frames, bufferedAmount…). */\n    readonly raw: WebSocket;\n}",
     "doc": "/**\n * A live typed WebSocket connection to an `app.ws()` route. `send` accepts the route's\n * `messageSchema` input type (validated server-side at the trust boundary); received frames are\n * typed from its `sendSchema` and JSON-parsed. Binary frames are not part of the typed contract\n * and are ignored by `messages()`/`onMessage` - use `raw` for them.\n */"
+  },
+  {
+    "name": "zodJsonSchema",
+    "kind": "function",
+    "package": "@nifrajs/testing",
+    "signature": "export declare function zodJsonSchema(schema: unknown): JsonSchema | undefined;",
+    "doc": "/**\n * Convert a zod schema to a JSON Schema the mock/mutation generators understand, or `undefined` when the\n * value is not a convertible zod schema. Options chosen for this consumer:\n *   - target \"draft-7\" → the keyword set `@nifrajs/mock` + the laboratory's `candidateMutations` read\n *   - io \"input\"       → the request-side constraints a hostile payload must violate (pre-transform)\n *   - reused \"inline\"  → no `$ref`/`$defs`; the mock generator fails closed on `$ref`\n *\n * Fail-safe: a non-zod value, or an unconvertible schema, returns `undefined` → the schema stays opaque\n * (NO_WITNESS / `{}`), exactly as before this bridge existed.\n */"
   }
 ]

package/package.json

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

package/src/check.ts

@@ -1709,10 +1709,14 @@ export async function collectCheckResult(
     }
     for (const finding of dr.duplicateInstalls) {
       const copies = finding.copies.map((copy) => `${copy.version} at ${copy.path}`).join("; ")
+      const identityHint =
+        finding.package === "@nifrajs/core"
+          ? " (a second @nifrajs/core collapses `typeof backend` to `any` at `.merge()` - usually that error's root cause)"
+          : ""
       diagnostics.push({
         rule: "duplicate-install",
         severity: "error",
-        message: `${finding.package} resolves to multiple physical copies (${copies}) - module identity is unsafe`,
+        message: `${finding.package} resolves to multiple physical copies (${copies}) - module identity is unsafe${identityHint}`,
         fix: "align dependency ranges and reinstall from the workspace root",
         suggestion: {
           kind: "manual",

package/src/cli.ts

@@ -89,9 +89,12 @@ Usage:
                                          nifra_run (backend), nifra_render (SSR a page), nifra_docs,
                                          nifra_example (verified snippets), nifra_scaffold (route→file),
                                          nifra_check (drift gate + fixes), nifra_levels (verification
-                                         ladder), nifra_doctor (deps + duplicate installs).
+                                         ladder), nifra_doctor (deps), nifra_explain (structured errors),
+                                         nifra_inspect (request traces), nifra_learn (guided build path).
   nifra docs-mcp [--port <n>]            Serve the PUBLIC docs MCP over HTTP (nifra_docs + nifra_example) -
                                          self-host on a VPS so any remote agent can learn nifra. Default :8787.
+  nifra learn   [<step>]                 Print the guided build-an-app path (the human view of nifra_learn):
+                                         no arg for the step index, a number for one step's goal/do/verify.
   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.
@@ -133,9 +136,10 @@ Usage:
   nifra upgrade <version>                Run the per-release upgrade recipe for <version>: sweep every
                 [--write] [--no-verify]  matching dependency pin (preserving ^/~/exact), move removed
                 [--list] [--json]        packages, apply exact imports, then verify with nifra check.
-                                         Dry-run by default; --write applies then verifies (--no-verify
+                [--allow-downgrade]      Dry-run by default; --write applies then verifies (--no-verify
                                          to skip). --list shows available targets. Fail-closed on an
-                                         unknown version. Deterministic + idempotent.
+                                         unknown version or a rollback (--allow-downgrade overrides).
+                                         Deterministic + idempotent.
   nifra port    [--target <t>] [--json]  Portability linter: print a feature × deploy-target capability
                 [--ci] [--strict]        matrix (in-memory stores, in-process cron/WebSocket, Bun/Deno
                                          globals, node: builtins) with file:line evidence. --target auto-
@@ -150,7 +154,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.3.0"
+const CLI_VERSION = "2.4.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
@@ -532,6 +536,18 @@ async function main(): Promise<void> {
     console.log(`nifra docs MCP (HTTP) → ${server.url}`)
     return
   }
+  // `learn` prints the guided build-an-app path (the human head of `nifra_learn`). Project-independent:
+  // the path is static, so no project needs to load. `nifra learn` for the index, `nifra learn 3` for a step.
+  if (command === "learn") {
+    const { renderLearnResult } = await import("./learn.ts")
+    const stepArg = argv[1]
+    console.log(
+      renderLearnResult(
+        stepArg !== undefined && /^\d+$/.test(stepArg) ? Number(stepArg) : undefined,
+      ),
+    )
+    return
+  }
   // `check` is a pure cwd-based gate (typecheck + lint) - it must run even when the project doesn't
   // load (API-only, not built yet), so it dispatches before the eager `loadApp` below.
   if (command === "check") {
@@ -768,6 +784,7 @@ async function main(): Promise<void> {
         json: argv.includes("--json"),
         list: argv.includes("--list"),
         verify: !argv.includes("--no-verify"),
+        allowDowngrade: argv.includes("--allow-downgrade"),
       })
       if (!ok) process.exitCode = 1
     } catch (err) {

package/src/doctor.ts

@@ -668,6 +668,14 @@ export async function runDoctor(
       for (const copy of finding.copies) {
         console.log(`      ${copy.version} at ${copy.path} ← ${copy.importers.join(", ")}`)
       }
+      if (finding.package === "@nifrajs/core") {
+        console.log(
+          "      ↳ a second @nifrajs/core breaks module identity: `typeof backend` collapses to `any`",
+        )
+        console.log(
+          "        at `.merge()` and route-type inference silently degrades - usually that error's root cause.",
+        )
+      }
     }
     console.log(
       "\n  Align dependency ranges and reinstall from the workspace root; doctor never deletes installs.",

package/src/learn.ts

@@ -0,0 +1,152 @@
+/**
+ * The guided learn path - a SEQUENCE for building a nifra app end to end, as opposed to the random-access
+ * search of `nifra_docs`/`nifra_example`. It is deliberately thin on embedded code: each step points at the
+ * tool that produces the CORRECT, verified artifact (`nifra_scaffold` for a route, `nifra_example` for a
+ * verified snippet, `nifra_run`/`nifra_render` to see it work), so an agent walks the path by composing the
+ * existing tools rather than pasting code that can drift from the installed version.
+ *
+ * One source, two heads: `nifra_learn` (MCP) serves it to an agent as structured steps; `nifra learn` (CLI)
+ * prints the same path for a human. Add or reorder steps here and both update.
+ */
+
+export interface LearnStep {
+  /** Stable slug, e.g. `page-route`. */
+  readonly id: string
+  readonly title: string
+  /** What you will have once this step is done. */
+  readonly goal: string
+  /** How to do it - prefer directing to the tool that emits the correct artifact over inline code. */
+  readonly do: string
+  /** How to confirm it worked. */
+  readonly verify: string
+  /** The `nifra_*` tools that carry out this step. */
+  readonly tools: readonly string[]
+  /** A `nifra_docs`/`nifra_example` query for going deeper. */
+  readonly seeAlso?: string | undefined
+}
+
+export const LEARN_PATH: readonly LearnStep[] = [
+  {
+    id: "create-app",
+    title: "Create the app",
+    goal: "A running nifra dev server with one page route.",
+    do: "Scaffold a new project with `npm create nifra@latest`, pick your framework adapter (React/Solid/Vue/Svelte/Preact), then `npm run dev`.",
+    verify: "The dev server prints a localhost URL and the default page renders.",
+    tools: ["nifra_context"],
+    seeAlso: "project structure routes backend",
+  },
+  {
+    id: "page-route",
+    title: "Add a page route",
+    goal: "A second page, server-rendered, reachable by URL.",
+    do: "Ask nifra_scaffold for the path (e.g. /about) - it returns the exact `routes/` file and a contract-correct page stub. File-based: `routes/about.tsx` serves `/about`.",
+    verify: "nifra_render /about returns the rendered HTML.",
+    tools: ["nifra_scaffold", "nifra_render"],
+    seeAlso: "page routes file-based routing layouts",
+  },
+  {
+    id: "loader",
+    title: "Load data for a page",
+    goal: "A page whose data is fetched on the server before render.",
+    do: "Export a `loader` from the route and read its result in the component. Get the exact shape from nifra_example ('loader').",
+    verify: "nifra_render the page and confirm the loaded data is in the HTML.",
+    tools: ["nifra_example", "nifra_render"],
+    seeAlso: "loader server data page",
+  },
+  {
+    id: "api-route",
+    title: "Add a typed API route",
+    goal: "A backend endpoint with a typed request/response contract.",
+    do: "Add the route to `backend.ts` with an @nifrajs/schema body/query/response schema. nifra_context shows the resulting contract and the exact typed-client call form.",
+    verify:
+      "nifra_run { method, path, body } and check the status + parsed body; nifra_check confirms the contract typechecks.",
+    tools: ["nifra_context", "nifra_run", "nifra_check"],
+    seeAlso: "api route schema validation backend",
+  },
+  {
+    id: "typed-client",
+    title: "Call the API, fully typed",
+    goal: "The page calls the API through the compile-time typed client - no hand-written client twin.",
+    do: "Use @nifrajs/client against the backend type. The call form is exactly what nifra_context prints for that route; a drifted call is a compile error, not a runtime surprise.",
+    verify: "nifra_check passes; nifra_run the page path and see the data flow end to end.",
+    tools: ["nifra_context", "nifra_check", "nifra_run"],
+    seeAlso: "typed client treaty end-to-end types",
+  },
+  {
+    id: "protect",
+    title: "Protect a route",
+    goal: "A route that requires an authenticated session.",
+    do: "Wire @nifrajs/auth (or @nifrajs/better-auth) and gate the route. nifra_example ('protected route') has the verified pattern; nifra_assure reports whether the gate is actually enforced.",
+    verify:
+      "nifra_run the route unauthenticated (expect 401/redirect) and authenticated (expect 200); nifra_assure shows the enforcement evidence.",
+    tools: ["nifra_example", "nifra_assure", "nifra_run"],
+    seeAlso: "auth session protected route better-auth",
+  },
+  {
+    id: "background-work",
+    title: "Do work in the background",
+    goal: "A request that enqueues a job instead of blocking on slow work.",
+    do: "Define a job with @nifrajs/jobs and enqueue it from a route. nifra_example ('job') has the shape; nifra_inspect shows the enqueue landing on the dev server.",
+    verify:
+      "nifra_run the route, then nifra_inspect the dev server to see the request completed fast and the effect fired.",
+    tools: ["nifra_example", "nifra_run", "nifra_inspect"],
+    seeAlso: "jobs queue background enqueue",
+  },
+  {
+    id: "ship",
+    title: "Build and deploy",
+    goal: "A production build served by your chosen runtime.",
+    do: "Pick an adapter (@nifrajs/node, @nifrajs/workers, @nifrajs/deno, or a static/Vercel target) and run the production build. nifra_levels shows what the app already proves before you ship.",
+    verify:
+      "The build completes and the artifact serves the app; nifra_check + nifra_levels are green.",
+    tools: ["nifra_levels", "nifra_check"],
+    seeAlso: "deploy build adapters node workers deno",
+  },
+]
+
+/** The compact index: numbered steps with their goal, plus how to drill into one. */
+function renderIndex(): string {
+  const lines = LEARN_PATH.map((step, i) => `${i + 1}. ${step.title} - ${step.goal} [${step.id}]`)
+  return [
+    `nifra learn path (${LEARN_PATH.length} steps). Call nifra_learn with step: N for the detail of step N.`,
+    "",
+    ...lines,
+  ].join("\n")
+}
+
+/** One step's full detail, with a pointer to the next. */
+function renderStep(step: LearnStep, index: number): string {
+  const parts = [
+    `Step ${index + 1}/${LEARN_PATH.length}: ${step.title}  [${step.id}]`,
+    "",
+    `Goal:   ${step.goal}`,
+    `Do:     ${step.do}`,
+    `Verify: ${step.verify}`,
+    `Tools:  ${step.tools.join(", ")}`,
+  ]
+  if (step.seeAlso !== undefined) {
+    parts.push(`See:    nifra_docs / nifra_example "${step.seeAlso}"`)
+  }
+  const next = LEARN_PATH[index + 1]
+  parts.push(
+    "",
+    next !== undefined
+      ? `Next:   step ${index + 2} (${next.title})`
+      : "Done - you have shipped a nifra app.",
+  )
+  return parts.join("\n")
+}
+
+/**
+ * Render the learn path. No `step` (or an out-of-range one) returns the index; a valid 1-based `step`
+ * returns that step's detail. Kept pure so `nifra_learn` and `nifra learn` render identically.
+ */
+export function renderLearnResult(step?: number): string {
+  if (step === undefined) return renderIndex()
+  const index = step - 1
+  const found = LEARN_PATH[index]
+  if (found === undefined) {
+    return `No step ${step}. The path has ${LEARN_PATH.length} steps.\n\n${renderIndex()}`
+  }
+  return renderStep(found, index)
+}