@nifrajs/cli 2.14.1 → 3.2.0

package/docs/examples.json

@@ -1,4 +1,16 @@
 [
+  {
+    "name": "AGENT_APP",
+    "topic": "Nifra - Coding agents",
+    "slug": "agents",
+    "code": "import { AgentAppClient, HttpAgentTransport } from \"@nifrajs/agent-app\"\n\ndeclare function currentToken(): string\ndeclare function render(view: unknown): void\n\nconst client = new AgentAppClient(new HttpAgentTransport({\n  endpoint: \"http://127.0.0.1:8787\",\n  authorize: () => currentToken(), // minted per request; never stored by the transport\n}))\n\nconst session = await client.createSession()\nfor await (const view of client.send(\"summarize the diff\")) {\n  render(view) // content-free status, counts, coordinates, and error codes\n}"
+  },
+  {
+    "name": "PROTOCOLS",
+    "topic": "Nifra - Coding agents",
+    "slug": "agents",
+    "code": "import { server } from \"@nifrajs/core\"\nimport { mountA2A } from \"@nifrajs/a2a\"\nimport { mountAgUI } from \"@nifrajs/ag-ui\"\nimport type { AgentPorts } from \"@nifrajs/agent\"\nimport { agent } from \"./agent\"\n\ndeclare const myModelPort: AgentPorts[\"model\"]\ndeclare const myStateStore: NonNullable<AgentPorts[\"state\"]>\n\nconst app = server()\nconst ports = () => ({\n  model: myModelPort,\n  capabilities: [\"search.read\"],\n  state: myStateStore, // scope this to the request subject\n})\n\nmountA2A(app, {\n  agent,\n  card: { url: \"https://api.example.com/a2a\", version: \"1.0.0\" },\n  ports,\n})\nmountAgUI(app, { agent, ports })\n\n// A2A: GET the card, POST JSON-RPC, optional SSE streaming.\n// AG-UI: POST RunAgentInput, receive the event stream over SSE."
+  },
   {
     "name": "TELEMETRY",
     "topic": "Nifra - Coding agents",
@@ -101,6 +113,12 @@
     "slug": "causality",
     "code": "import { createMemoryCausalityStore, startCausality } from \"@nifrajs/core/causality\"\n\nconst recorder = createMemoryCausalityStore()\nconst requestId = crypto.randomUUID()\n\n// One root node at the ingress boundary. executionId is the graph's identity:\n// generate it once, then propagate it.\nconst step = startCausality(\"request\", requestId, { executionId: crypto.randomUUID() })\n\n// step.context propagates; step.record is what a durable adapter appends.\nawait recorder.record(step.record)"
   },
+  {
+    "name": "STYLEX_CONFIG",
+    "topic": "Nifra - CLI",
+    "slug": "cli",
+    "code": "// nifra.config.ts - Bun's client and SSR build transforms.\nimport { stylexBunPlugin } from \"@nifrajs/web/plugins/stylex\"\n\nexport const clientPlugins = [stylexBunPlugin(\"dom\")]\nexport const serverPlugins = [stylexBunPlugin(\"ssr\")]"
+  },
   {
     "name": "DUAL_API",
     "topic": "Nifra - Framework contract",
@@ -263,12 +281,30 @@
     "slug": "index",
     "code": "import { server } from \"@nifrajs/core/server\"\n\nserver()\n  .get(\"/\", () => ({ hello: \"world\" }))\n  .get(\"/users/:id\", (c) => ({ id: c.params.id }))\n  .listen(3000)"
   },
+  {
+    "name": "BUS_PATTERN",
+    "topic": "Nifra - Islands: the AI-safe interactivity lane",
+    "slug": "islands",
+    "code": "import { createIslandBus } from \"@nifrajs/web/islands\"\n\n// One typed channel, created once and closed over by every enhancer that needs it.\ntype CartEvents = { \"cart:add\": { sku: string }; \"cart:count\": number }\nconst bus = createIslandBus<CartEvents>()\n\nconst off = bus.on(\"cart:count\", (n) => console.log(\"cart now has\", n, \"items\"))\nbus.emit(\"cart:add\", { sku: \"ABC-1\" })\noff() // unsubscribe - also usable directly as an island's cleanup"
+  },
   {
     "name": "HONO",
     "topic": "Nifra - Migrate route by route",
     "slug": "migrate-route-by-route",
     "code": "import { Hono } from \"hono\"\nimport { server } from \"@nifrajs/core/server\"\nimport { t } from \"@nifrajs/schema\"\n\nconst legacy = new Hono()\nlegacy.get(\"/users\", (c) => c.json({ source: \"hono\", users: [] }))\nlegacy.post(\"/users\", async (c) => c.json(await c.req.json()))\n\nexport const app = server()\n  // The wildcard is a literal mount prefix, not a typed Nifra route.\n  .mountFetch(\"/legacy/*\", legacy.fetch, { stripPrefix: true })\n  // Typed routes take precedence, so move one route out of Hono at a time.\n  .get(\"/legacy/users/:id\", (c) => ({ id: c.params.id, source: \"nifra\" }))\n  .post(\n    \"/users\",\n    { body: t.object({ name: t.string() }) },\n    (c) => ({ id: crypto.randomUUID(), name: c.body.name }),\n  )"
   },
+  {
+    "name": "CORE",
+    "topic": "Nifra - nano: explicit reactivity for small apps",
+    "slug": "nano",
+    "code": "import { signal, computed } from \"@nifrajs/web/nano\"\n\n// State is a signal: reads are .get(), writes are .set(...). Every edge is a call you can see.\nconst count = signal(0)\n\n// Derived state declares its dependencies EXPLICITLY - the array is the whole contract. It\n// recomputes when (and only when) a listed source changes. Object.is-deduped, like signal.\nconst doubled = computed(() => count.get() * 2, [count])\n\nconst off = doubled.subscribe((v) => console.log(\"doubled is now\", v))\ncount.set(5) // logs: doubled is now 10\noff()        // unsubscribe"
+  },
+  {
+    "name": "RESOURCE",
+    "topic": "Nifra - nano: explicit reactivity for small apps",
+    "slug": "nano",
+    "code": "import { signal, resource } from \"@nifrajs/web/nano\"\n\nconst userId = signal(1)\n\n// resource(fetcher, [deps]) is an async cell: it fetches immediately and again whenever a declared\n// dep changes. The fetcher gets an AbortSignal; a superseded fetch is aborted and its late result\n// dropped, so the newest request always wins - no stale-response flicker to hand-guard.\nconst user = resource(async (sig) => {\n  const res = await fetch(`/api/users/${userId.get()}`, { signal: sig })\n  return (await res.json()) as { name: string }\n}, [userId])\n\n// The value is an explicit union - status is \"pending\" | \"error\" | \"ready\", never a secret undefined.\nconst off = user.subscribe((s) => {\n  if (s.status === \"ready\") console.log(\"got\", s.value.name)\n})\nuserId.set(2) // refetches; the deps array is what NF-C023 checks against the fetcher's .get() reads\n// ...on teardown: off()"
+  },
   {
     "name": "CACHING",
     "topic": "Nifra - Plugins & middleware",
@@ -309,7 +345,7 @@
     "name": "PORTABLE_HOOK",
     "topic": "Nifra - Plugins & middleware",
     "slug": "plugins",
-    "code": "import type { Middleware } from \"@nifrajs/core/server\"\n\n// ONE implementation, fast on every runtime: on Bun/Deno it mutates the\n// response's own Headers in place; on Node it writes the outcome record on the\n// direct socket writer - no Web Request/Response is ever built for it.\nexport function serverName(value: string): Middleware {\n  return {\n    onResponseHeaders(headers, req, status) {\n      if (status < 500) headers.set(\"server\", value)\n    },\n  }\n}"
+    "code": "import { responseObserver } from \"@nifrajs/core/response-observer\"\nimport { server } from \"@nifrajs/core/server\"\nimport type { Middleware } from \"@nifrajs/core/server\"\n\n// ONE implementation, fast on every runtime: on Bun/Deno it mutates the\n// response's own Headers in place; on Node it writes the outcome record on the\n// direct socket writer - no Web Request/Response is ever built for it.\nexport function serverName(value: string): Middleware {\n  return {\n    onResponseHeaders(headers, req, status) {\n      if (status < 500) headers.set(\"server\", value)\n    },\n  }\n}\n\nconst app = server().use(responseObserver()).use(serverName(\"nifra\"))"
   },
   {
     "name": "RELIABILITY",