@nifrajs/cli 3.2.0 → 3.3.0

package/dist/cli.js

@@ -192,7 +192,7 @@ set in the process environment is never overwritten by a file.
 
 ${renderCommandCatalogHelp()}`;
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const CLI_VERSION = "3.2.0";
+const CLI_VERSION = "3.3.0";
 // A render adapter + nifra server are opaque to the CLI (it just forwards them); cast at the seam.
 const asAdapter = (v) => v;
 const asBunPlugins = (v) => v;

package/dist/mcp-http.js

@@ -23,7 +23,7 @@ import { loadTypesCorpus } from "./types-search.js";
 export { examplesAppTool, examplesWidget } from "./mcp-app-tool.js";
 export { docsTools } from "./mcp-docs-tools.js";
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const VERSION = "3.2.0";
+const VERSION = "3.3.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) => `nifra docs MCP - POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call). Tools: ${tools

package/docs/examples.json

@@ -361,19 +361,19 @@
   },
   {
     "name": "BUILD",
-    "topic": "Nifra - Rendering: SSG & ISR",
+    "topic": "Nifra - Rendering: SSR, streaming, SSG & ISR",
     "slug": "rendering",
     "code": "// build.ts - buildClient, then prerender opted-in routes to static HTML.\nimport { buildClient, prerenderRoutes, cloudflarePagesRoutes } from \"@nifrajs/web/build\"\nimport { discoverRoutes } from \"@nifrajs/web/fs\"\n\nawait buildClient({ routesDir: \"./routes\", outDir: \"./dist\", clientModule: \"@nifrajs/web-react/client\" })\nconst { app } = await import(\"./server\")\nconst { prerendered } = await prerenderRoutes({\n  app,\n  routes: discoverRoutes(\"./routes\").routes,\n  outDir: \"./dist\", // writes <path>/index.html + <path>/_data.json per prerendered route\n})\n\n// Hybrid deploy (Cloudflare Pages): serve prerendered HTML + _data.json from the CDN; everything\n// else falls through to the SSR worker.\nconst paths = prerendered.map((p) => p.path)\nBun.write(\"./dist/_routes.json\", JSON.stringify(cloudflarePagesRoutes({ prerendered: paths })))"
   },
   {
     "name": "FONTS",
-    "topic": "Nifra - Rendering: SSG & ISR",
+    "topic": "Nifra - Rendering: SSR, streaming, SSG & ISR",
     "slug": "rendering",
     "code": "// fonts.css - a CLS-safe @font-face for a self-hosted font (the pipeline bundles + hashes it).\nimport { fontFace } from \"@nifrajs/web\"\nexport default fontFace({\n  family: \"Inter\",\n  src: [{ url: \"/fonts/inter-var.woff2\" }], // self-host it - never hotlink a CDN\n  weight: \"100 900\",                        // variable font\n  sizeAdjust: \"100.06%\", ascentOverride: \"90%\", // optional: stop fallback->web-font layout shift\n})\n\n// a root layout - preload the file so it downloads WITH the document (not after CSS parse):\nimport { fontPreload } from \"@nifrajs/web\"\nexport const meta = { link: [fontPreload({ href: \"/fonts/inter-var.woff2\" })] }"
   },
   {
     "name": "ISR",
-    "topic": "Nifra - Rendering: SSG & ISR",
+    "topic": "Nifra - Rendering: SSR, streaming, SSG & ISR",
     "slug": "rendering",
     "code": "// server.ts - wrap the app with Incremental Static Regeneration.\nimport { createWebApp, withISR, MemoryCacheStore } from \"@nifrajs/web\"\nimport { reactAdapter } from \"@nifrajs/web-react\"\nimport { clientEntry, manifest } from \"./server-manifest\" // generated by buildServer\n\nconst app = createWebApp({ adapter: reactAdapter, manifest, clientEntry })\nconst store = new MemoryCacheStore() // dev / single-instance only\n\n// GET text/html responses are cached + served stale-while-revalidate. Default freshness 60s.\nconst isr = withISR(app, { store, revalidate: 60, now: () => Date.now() })\nBun.serve({ fetch: (req) => isr(req) })"
   },
@@ -473,6 +473,12 @@
     "slug": "types-first",
     "code": "import { client } from \"@nifrajs/client\"\nimport type { app } from \"./server\"   // a TYPE import - server code never ships to the client\n\nconst api = client<typeof app>(\"https://api.example.com\")\n\nconst res = await api.users({ id: \"42\" }).get()   // path + params autocomplete, no codegen\nif (res.ok) {\n  res.data.name        // typed from the route's response schema\n} else {\n  res.error            // client-call failures are returned, never thrown\n}"
   },
+  {
+    "name": "INLINE",
+    "topic": "Nifra - Types-first architecture",
+    "slug": "types-first",
+    "code": "import { server } from \"@nifrajs/core/server\"\n\nexport const app = server()\n  .get(\"/users/:id\", (c) => ({ id: c.params.id, name: \"Ada\" }))\n  // c.params.id is inferred from the path; the return type becomes the client response.\n  .post(\"/users\", () => ({ created: true }))\n\n// No schema, annotation, or codegen is required for the route types."
+  },
   {
     "name": "OPENAPI",
     "topic": "Nifra - Types-first architecture",
@@ -489,7 +495,7 @@
     "name": "SCHEMA",
     "topic": "Nifra - Types-first architecture",
     "slug": "types-first",
-    "code": "import { t } from \"@nifrajs/schema\"\n\n// One contract, defined once. Everything below is derived from it.\nexport const GetUser = {\n  params: t.object({ id: t.string() }),\n  response: t.object({\n    id: t.string(),\n    name: t.string(),\n    role: t.union([t.literal(\"admin\"), t.literal(\"user\")]),\n  }),\n}"
+    "code": "import { t } from \"@nifrajs/schema\"\n\n// Add a schema when the boundary needs runtime validation or a declared contract.\nexport const GetUser = {\n  params: t.object({ id: t.string() }),\n  response: t.object({\n    id: t.string(),\n    name: t.string(),\n    role: t.union([t.literal(\"admin\"), t.literal(\"user\")]),\n  }),\n}"
   },
   {
     "name": "BASIC",

package/docs/llms-full.txt

@@ -958,15 +958,48 @@ function Row({ id }: { id: string }) {
 const anyPending = useFetchers().some((f) => f.snapshot().pending)
 ```
 
-## Nifra - Rendering: SSG & ISR
+## Nifra - Rendering: SSR, streaming, SSG & ISR
 
-> Prerender static routes, enumerate dynamic ones, and cache rendered pages with stale-while-revalidate - on every runtime including the edge.
+> Render critical HTML first, stream deferred data progressively, prerender static routes, and cache rendered pages with stale-while-revalidate - on every runtime including the edge.
 
 Nifra renders on one framework-agnostic seam, so the same app can be server-rendered per
-request (the default), **prerendered** to static files at build (SSG), or cached and served
+request (the default), streamed progressively, **prerendered** to static files at build (SSG), or cached and served
 **stale-while-revalidate** (ISR) - and every strategy works on Bun, Node, Deno, **and**
 the edge.
 
+### Progressive rendering with `defer()`
+
+Keep critical loader data in the first HTML shell and mark slower, non-critical values with
+`defer()`. Nifra flushes the document shell and the adapter's rendered stream first,
+then sends each deferred resolution through `<Await>` without a second data
+fetch. The same protocol works for actions and soft navigations, including NDJSON on the client
+side.
+
+```ts
+import { defer } from "@nifrajs/web"
+
+export async function loader({ api }: LoaderArgs<typeof app>) {
+  return {
+    product: (await api.products.get()).data, // critical: rendered in the first shell
+    reviews: defer(api.reviews.get()),        // non-critical: streamed when ready
+  }
+}
+
+export default function Product(props: { data: LoaderData<typeof loader> }) {
+  return (
+    <>
+      <ProductSummary product={props.data.product} />
+      <Await resolve={props.data.reviews} fallback={<p>Loading reviews…</p>}>
+        {(reviews) => <Reviews items={reviews} />}
+      </Await>
+    </>
+  )
+}
+```
+
+This is request-time progressive SSR/partial rendering. It is distinct from build-time SSG:
+the shell is not a precomputed PPR artifact, and deferred values remain request-scoped.
+
 ### SSG - prerender at build
 
 Opt a static route into prerendering with `export const prerender = true`. Its
@@ -4240,7 +4273,7 @@ the command printed by the build.
 
 ## Nifra - Coding agents
 
-> Nifra's agent layer: live MCP tools for coding agents, bounded typed turns, resumable evidence, a coding-agent host, browser views, A2A and AG-UI bridges, and token-only telemetry.
+> Nifra's agent layer: live MCP tools, bounded repairable turns, native approvals, resumable evidence, content-free browser views, capability registry, decision inbox, Run Studio, A2A, and AG-UI.
 
 Nifra ships an MCP server. It is not a documentation lookup bolted onto a framework: an agent
 can read the project, learn the real API, run actual requests against the backend it just
@@ -4324,6 +4357,8 @@ nifra_check             # typecheck + lints, each with a structured fix
 nifra_fix               # applies the mechanical ones
 nifra_run    {request}  # a real request through the backend: status, headers, parsed body
 nifra_render {path}     # SSR a page route, returns the HTML
+nifra_inspect {port}    # recent dev-server request traces: status, duration, ISR hit/miss
+nifra_explain {error}   # turn a failure into a structured diagnostic and fix
 nifra_test              # bun test, bounded structured results
 
 # 4. What does it now prove?
@@ -4465,8 +4500,28 @@ bunx nifra-agent --backend pi --message "run the checks and explain failures"
 ```
 
 The public host keeps live queues and captured evidence bounded, filters verification process
-environments, and treats extensions as an explicit opt-in. The local process adapter and
-extension worker are crash-containment helpers, not hostile-code sandboxes.
+environments, and treats extensions as an explicit opt-in. Post-turn `check`,
+`assure`, or `test` gates emit `verification.completed` and
+`repair.required`; when enabled, the host sends a bounded repair prompt and reruns
+the gate until it passes or the attempt cap is reached. The local process adapter and extension
+worker are crash-containment helpers, not hostile-code sandboxes.
+
+```ts
+# Post-turn gates are opt-in. A failed gate becomes bounded repair work.
+bunx nifra-agent --backend pi --message "implement the change" \
+  --verify-after-turn check,assure --max-repair-attempts 2
+
+# Set --max-repair-attempts 0 for observe-only verification.
+```
+
+### Native approval protocol
+
+`@nifrajs/coding-agent` can pause a native tool call at the decision boundary and
+emit `approval.required` with an opaque approval id, action, capability, and bounded
+coordinates. Resolve it through the host or RPC with `approval.resolve`; the backend
+emits `approval.resolved` and only then executes the tool. Denial, cancellation,
+timeout, and closed sessions all fail closed, and `approvalTimeoutMs` bounds how long
+a pending decision can remain open.
 
 ### Expose the same agent to other clients
 
@@ -4509,11 +4564,15 @@ auth and authorization middleware, and scope every injected port to the request
 ### Browser views and the Workbench
 
 `@nifrajs/agent-app` is a backend-free browser SDK for negotiated commands, ordered
-and resumable event streams, approvals, handoffs, and Run Studio projections. Its public views
-contain structure - statuses, counters, coordinates, and error codes - rather than prompts,
-tool payloads, model output, or filesystem paths. The optional Workbench uses that same surface:
-run `bun run --filter '@nifrajs/workbench' dev -- --cwd /path/to/project` for the
-local browser client.
+and resumable event streams, approvals, handoffs, and Run Studio projections. It negotiates
+optional features including `approvals`, `checkpoint`,
+`fork`, `handoff`, `inbox`, `reload`,
+`resume`, and `workflows`, so a browser can degrade deliberately when a
+host does not offer one. Its public views contain structure - statuses, counters, coordinates,
+and error codes - rather than prompts, tool payloads, model output, or filesystem paths. The
+optional Workbench uses that same surface: run
+`bun run --filter '@nifrajs/workbench' dev -- --cwd /path/to/project` for the local
+browser client.
 
 ```ts
 import { AgentAppClient, HttpAgentTransport } from "@nifrajs/agent-app"
@@ -4532,14 +4591,30 @@ for await (const view of client.send("summarize the diff")) {
 }
 ```
 
+### Capability registry, decision inbox, and Run Studio
+
+The Workbench's `registry.list` view shows content-free identity cards for admitted
+capabilities: kind, name, version, schema digest, required capability tokens, and approval,
+retry, idempotency, and isolation classes. It never renders a prompt, input schema, tool
+payload, model output, or filesystem path.
+
+The `inbox` feature lists pending approval and handoff boundaries by exact structural
+coordinate - run, node, capability, child vector, request id, and expiry. Every approve, deny,
+assign, resolve, or cancel command carries that coordinate, so stale, mismatched, or expired
+decisions are refused by the host. `run.studio` projects the same bounded evidence
+into a run graph, retry/recovery timeline, eval comparison, and deterministic fault-injection
+view. These are presentation-safe views: content stays in the host.
+
 ### Evidence, streaming, and telemetry
 
 `@nifrajs/agent` runs bounded typed turns with tool contracts, budgets, approvals,
 resumable token-only evidence, model deltas, and a transient shared-state channel. Add an
 `evidenceLog` to the HTTP seams for SSE replay after a dropped connection; replay
-resumes evidence and never re-executes the turn. `@nifrajs/agent-telemetry` converts
-the same constrained evidence into fail-open OpenTelemetry run and step spans. Providers,
-credentials, durable storage, retention, and tenant policy remain application-owned ports.
+resumes evidence and never re-executes the turn. The additive run-lifecycle contract supplies
+content-free snapshots, ordered evidence refs, feature negotiation, handoff state, and cursor
+resume. `@nifrajs/agent-telemetry` converts the same constrained evidence into
+fail-open OpenTelemetry run and step spans. Providers, credentials, durable storage, retention,
+and tenant policy remain application-owned ports.
 
 ### Projects without a web config
 
@@ -7962,21 +8037,41 @@ isolated fixtures and a test database. Never point a contract laboratory at prod
 
 ## Nifra - Types-first architecture
 
-> One schema is the single source of truth: it drives runtime validation, inferred TypeScript types, the no-codegen typed client, an OpenAPI document, and the MCP contract your agents read.
+> Nifra infers route types from path literals and handlers automatically, with optional Standard Schemas for validation, explicit contracts, OpenAPI, and agent-readable APIs.
+
+Nifra starts with automatic inference. A route's path literal, handler context, and return
+value produce its TypeScript surface; add a Standard Schema when you need runtime validation,
+coercion, or an explicit request/response contract. The same server type then drives the
+no-codegen client and the agent-readable API surface.
+
+### Inline inference first
+
+The chainable builder is fully type-inferred. Path parameters are parsed from the route
+pattern, handler context is typed automatically, and plain return values become the success
+response seen by the client. This is the quick-start style, similar to Elysia's inline route
+inference.
 
-In Nifra a single schema is the **source of truth**. The same definition drives runtime
-validation, inferred TypeScript types, the no-codegen typed client, an OpenAPI document, and
-the contract your coding agents read - so the five never drift apart.
+```ts
+import { server } from "@nifrajs/core/server"
+
+export const app = server()
+  .get("/users/:id", (c) => ({ id: c.params.id, name: "Ada" }))
+  // c.params.id is inferred from the path; the return type becomes the client response.
+  .post("/users", () => ({ created: true }))
 
-### One schema
+// No schema, annotation, or codegen is required for the route types.
+```
+
+### Schemas at the trust boundary
 
-Define request inputs and the response shape once with `t`. Nothing here is
-framework-specific; it's a plain object you attach to a route.
+Attach a Standard Schema when inputs must be validated before the handler runs, or when you
+want an explicit response contract. Path params are already inferred from `:id`;
+the `params` schema below adds runtime constraints/coercion as well.
 
 ```ts
 import { t } from "@nifrajs/schema"
 
-// One contract, defined once. Everything below is derived from it.
+// Add a schema when the boundary needs runtime validation or a declared contract.
 export const GetUser = {
   params: t.object({ id: t.string() }),
   response: t.object({
@@ -8006,9 +8101,10 @@ export const app = server().get("/users/:id", GetUser, (c) => {
 
 ### Inferred types
 
-The same schema types the handler: `c.params.id` is `string`, and the
-return value is checked against `response`. Change the schema and the handler
-stops compiling until it matches - types and validation can't disagree.
+Without a schema, `c.params.id` is still `string` and the handler return
+is captured automatically. With a schema, its output types the handler and its declared
+`response` constrains what the handler may return. Change either the route or the
+contract and the typed client follows at compile time.
 
 ### The typed client
 
@@ -8030,6 +8126,16 @@ if (res.ok) {
 }
 ```
 
+### Contract-first when the surface must be separate
+
+Inline inference is the default. If the API needs to be shared, versioned, or implemented by
+more than one service, declare it with `defineContract` and connect handlers with
+`implement`. That keeps the contract type available without importing a server
+implementation into the client.
+
+See [Framework contract](/docs/contract) for the decoupled form and its scaling
+guidance.
+
 ### OpenAPI
 
 The `openapi()` middleware builds an OpenAPI 3.1 document from your registered

package/docs/types.json

@@ -10237,7 +10237,7 @@
     "name": "NativeApprovalPort",
     "kind": "interface",
     "package": "@nifrajs/coding-agent",
-    "signature": "export interface NativeApprovalPort {\n    request(input: {\n        readonly sessionId: string;\n        readonly tool: NativeTool;\n        readonly input: unknown;\n        readonly signal: AbortSignal;\n    }): boolean | PromiseLike<boolean>;\n}"
+    "signature": "export interface NativeApprovalPort {\n    request(input: {\n        readonly sessionId: string;\n        /** Stable, bounded identifier for this approval boundary. */\n        readonly approvalId: string;\n        readonly turnId: string;\n        readonly callId: string;\n        readonly action: string;\n        readonly capability: string;\n        readonly tool: NativeTool;\n        readonly input: unknown;\n        readonly signal: AbortSignal;\n    }): boolean | PromiseLike<boolean>;\n}"
   },
   {
     "name": "NativeGatewayModelPortOptions",
@@ -10528,14 +10528,14 @@
     "name": "NifraBackend",
     "kind": "class",
     "package": "@nifrajs/coding-agent",
-    "signature": "export declare class NifraBackend implements AgentBackend {\n    readonly info: AgentBackendInfo;\n    private readonly options;\n    private readonly sessions;\n    constructor(options: NifraBackendOptions);\n    createSession(input: CreateSessionInput): Promise<AgentSessionSnapshot>;\n    send(input: SendMessageInput): AsyncIterable<AgentEvent>;\n    cancel(sessionId: string, reason?: string): Promise<void>;\n    snapshot(sessionId: string): Promise<AgentSessionSnapshot>;\n    reload(sessionId: string): Promise<ReloadResult>;\n    close(sessionId: string): Promise<void>;\n    private run;\n    private consumeModel;\n    private finish;\n    private emit;\n    private update;\n    private requireSession;\n    private now;\n}",
+    "signature": "export declare class NifraBackend implements AgentBackend {\n    readonly info: AgentBackendInfo;\n    private readonly options;\n    private readonly sessions;\n    private readonly pendingApprovals;\n    constructor(options: NifraBackendOptions);\n    createSession(input: CreateSessionInput): Promise<AgentSessionSnapshot>;\n    send(input: SendMessageInput): AsyncIterable<AgentEvent>;\n    cancel(sessionId: string, reason?: string): Promise<void>;\n    snapshot(sessionId: string): Promise<AgentSessionSnapshot>;\n    reload(sessionId: string): Promise<ReloadResult>;\n    resolveApproval(sessionId: string, approvalId: string, approved: boolean, reason?: string): Promise<boolean | undefined>;\n    close(sessionId: string): Promise<void>;\n    private run;\n    private consumeModel;\n    private finish;\n    private requestApproval;\n    private settleApproval;\n    private emit;\n    private update;\n    private requireSession;\n    private now;\n}",
     "doc": "/**\n * Small provider port for a future Nifra-native backend.\n *\n * It deliberately knows only messages, tools, and the protocol. Provider SDKs, credentials, UI,\n * and framework packages stay outside this module. A model may return one response or stream\n * deltas followed by a final response.\n */"
   },
   {
     "name": "NifraBackendOptions",
     "kind": "interface",
     "package": "@nifrajs/coding-agent",
-    "signature": "export interface NifraBackendOptions {\n    readonly model: NativeModelPort;\n    readonly tools?: readonly NativeTool[];\n    readonly approval?: NativeApprovalPort;\n    readonly maxSteps?: number;\n    readonly maxMessageChars?: number;\n    readonly now?: () => number;\n}"
+    "signature": "export interface NifraBackendOptions {\n    readonly model: NativeModelPort;\n    readonly tools?: readonly NativeTool[];\n    readonly approval?: NativeApprovalPort;\n    /** Maximum time a protocol-visible native approval may remain unresolved. */\n    readonly approvalTimeoutMs?: number;\n    readonly maxSteps?: number;\n    readonly maxMessageChars?: number;\n    readonly now?: () => number;\n}"
   },
   {
     "name": "NifraContextLike",
@@ -18148,14 +18148,14 @@
     "name": "VERSION",
     "kind": "const",
     "package": "@nifrajs/core",
-    "signature": "export declare const VERSION: \"3.2.0\";",
+    "signature": "export declare const VERSION: \"3.3.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: \"3.2.0\";",
+    "signature": "export declare const VERSION: \"3.3.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 */"
   },
   {

package/package.json

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

package/src/cli.ts

@@ -216,7 +216,7 @@ set in the process environment is never overwritten by a file.
 ${renderCommandCatalogHelp()}`
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const CLI_VERSION = "3.2.0"
+const CLI_VERSION = "3.3.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

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 = "3.2.0"
+const VERSION = "3.3.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 =>