@nifrajs/cli 2.0.0 → 2.2.0

package/docs/llms-full.txt

@@ -780,15 +780,15 @@ cache. Pass the same `draftSecret` to `createWebApp` and
 
 ```ts
 // doc-check: skip — fragment spanning three files: your `app`, `env`, `redirect`, and route `slug`.
-// 1. A route you gate yourself flips draft mode on for the editor.
-import { enableDraft, disableDraft } from "@nifrajs/web"
+// 1. Mount the preview entry point your CMS links to. It checks the token in CONSTANT TIME,
+//    sets the signed HttpOnly cookie, and refuses an off-site ?to= (an open redirect otherwise).
+import { previewEndpoint, disableDraft } from "@nifrajs/web"
 
-app.get("/api/preview", async (c) => {
-  if (c.query.token !== env.PREVIEW_TOKEN) return new Response("nope", { status: 401 })
-  await enableDraft(c, env.DRAFT_SECRET) // signed, HttpOnly cookie
-  return redirect(String(c.query.to ?? "/"))
-})
+const preview = previewEndpoint({ secret: env.PREVIEW_TOKEN, draftSecret: env.DRAFT_SECRET })
+app.get("/api/preview", (c) => preview(c.req)) // ?token=…&to=/posts/hello
 app.get("/api/preview/exit", (c) => (disableDraft(c), redirect("/")))
+// Gating it yourself instead? Use enableDraft(c, env.DRAFT_SECRET) AFTER your own check — and
+// compare the token in constant time, since === leaks it one character at a time.
 
 // 2. Loaders branch on ctx.draft to load unpublished content.
 export async function loader({ api, draft }: LoaderArgs<typeof app>) {
@@ -1731,12 +1731,23 @@ treated as a substitute for static provenance.
 
 ```ts
 // doc-check: skip — combines route and assurance-config excerpts.
-// route: exact effect declaration + runtime beacon at the owned adapter seam
-import { useCapability } from "@nifrajs/core/capabilities"
+// route: exact effect declaration + correlated execution at the owned adapter seam
+import { executeCapability } from "@nifrajs/core/capabilities"
+
+app.aroundCapability(async (effect, next) => {
+  // Ask an entitlement service or short-lived approval gate using token-only metadata.
+  // effect.signal aborts on request cancellation or the interceptor timeout.
+  if (!policyAllows(effect.capability, effect.target)) return // deny fail-closed
+  await next()
+}, { timeoutMs: 5_000 })
 
 app.post("/orders", { capabilities: ["db.write"] }, async (c) => {
-  useCapability(c, "db.write") // undeclared use fails before the effect
-  return orders.write(c.body)
+  return executeCapability(
+    c,
+    "db.write",
+    { target: "repo:orders" },
+    ({ signal }) => orders.write(c.body, { signal }),
+  )
 })
 
 // in nifra.assurance.ts, alongside policy:
@@ -1766,6 +1777,51 @@ Domain writes on `GET`/`HEAD` are hard violations. Each write definition may
 require request idempotency or durable command/provider-key evidence. The lockfile contains only
 method, path, and capability tokens—no payloads or tenant data—and CI never rewrites it.
 
+### Durable approval, compensation, and reconciliation
+
+The durable execution subpath turns the capability boundary into a crash-visible workflow.
+Approval resumes are HMAC-signed, expire, bind to the tenant, principal, capability, target, and
+digest, and are consumed atomically once. The effect journal marks execution before the provider
+call, so a crash after an external commit remains `ambiguous` for reconciliation instead
+of being retried blindly. Typed sagas persist compensation arguments separately from the sealed
+token-only ledger and compensate committed steps in reverse order with retry/backoff state.
+
+```ts
+// doc-check: skip — durable store implementations are deployment-specific.
+import {
+  createApprovalCoordinator,
+  createDurableEffectJournal,
+  createSagaEngine,
+} from "@nifrajs/core/durable-execution"
+import { effectTracing } from "@nifrajs/otel/effects"
+
+const effects = effectTracing({ exporter })
+app.use(effects)
+
+const approval = createApprovalCoordinator({
+  store: durableApprovalStore, // must declare durability: "durable"
+  secret: approvalHmacKey,     // 32+ random bytes, stored separately
+})
+const journal = createDurableEffectJournal({ store: durableEffectStore })
+
+await executeCapability(c, "payments.charge", {
+  target: "provider:stripe",
+  digest,
+  journal,
+  approval: {
+    gate: approval,
+    tenantId: c.principal.tenantId,
+    principalId: c.principal.userId,
+    resumeToken,
+  },
+}, ({ effectId, signal }) => payments.charge(input, { idempotencyKey: effectId, signal }))
+
+const sagas = createSagaEngine({
+  store: durableSagaStore,
+  observer: effects.observer,
+})
+```
+
 ### Already built in
 
 These add to Nifra's standing defaults: strict-by-default schema validation (unknown fields
@@ -2761,11 +2817,13 @@ the command printed by the build.
 
 ## Nifra — Dev & HMR
 
-> Use `nifra dev` for a Vite-backed state-preserving HMR loop, or `@nifrajs/web/dev` for a Bun-native live-reload loop. Production builds use Bun.
+> Use `nifra dev` for a Vite-backed state-preserving HMR loop, or `@nifrajs/web/dev` for a Bun-native HMR loop with no Vite dependency. Production builds use Bun.
 
-Nifra gives you two local development loops. Use `nifra dev` for
-state-preserving UI edits, or use `@nifrajs/web/dev` when you want a Bun-only
-live-reload server. Both serve your real SSR app locally.
+Nifra gives you two local development loops, and the rule between them is that one
+toolchain owns a whole phase. **Both** give you React Fast Refresh with state
+preserved. Use `nifra dev` (Vite) for the plugin ecosystem, or
+`nifra dev --bun` for one bundler across dev and prod with no Vite dependency.
+Both serve your real SSR app locally, and neither mixes the two bundlers in one process.
 
 ### Two loops, same app
 
@@ -2776,9 +2834,9 @@ use when
 
 `@nifrajs/web/dev`
 
-rebuild + full-page live-reload
+Bun HMR + Fast Refresh (native)
 none (Bun only)
-default; zero extra deps
+one bundler dev+prod; no Vite dep (no CSS Modules)
 
 `@nifrajs/web/vite`
 
@@ -2826,50 +2884,44 @@ can edit routes, components, loaders, actions, and styles in one local loop.
 
 ### Framework coverage
 
-All five adapters have a dev setup. Pass the framework's official Vite plugin, and for Vue,
-Svelte, and Solid, preload the matching Nifra compiler plugin for server rendering.
+All five adapters have a dev setup. Pass the framework's official Vite plugin and you are
+done: under `nifra dev` the Vite pipeline compiles both halves, so the same plugin
+that transforms your components for the browser also transforms them for SSR. No separate
+server-side compiler plugin to preload, and no way for the two halves to disagree about a
+specifier.
 
 framework
-client (Vite plugin)
-SSR compile
+Vite plugin (client + SSR)
 local state on edit
 
 React
 
 `@vitejs/plugin-react`
 
-Bun-native
 preserved (Fast Refresh)
 
 Preact
 
 `@preact/preset-vite`
 
-Bun-native
 preserved (prefresh)
 
 Vue
 
 `@vitejs/plugin-vue`
 
-`vueBunPlugin` preload
-
 preserved (rerender)
 
 Solid
 
 `vite-plugin-solid` (`{ ssr: true }`)
 
-`solidBunPlugin` preload
-
 resets (solid-refresh)
 
 Svelte
 
 `@sveltejs/vite-plugin-svelte`
 
-`svelteBunPlugin` preload
-
 resets (svelte HMR)
 
 For **React, Preact, and Vue**, an edit hot-swaps with component state preserved.
@@ -2912,17 +2964,72 @@ instead.
 
 ### The zero-dep alternative
 
-`@nifrajs/web/dev` is a self-contained server: it builds the client on boot,
-serves SSR, watches the routes, and does a full-page reload on change.
+`nifra dev --bun` (library: `@nifrajs/web/dev`) is self-contained —
+no Vite anywhere. `Bun.serve`'s native HMR bundles and hot-reloads the client while
+Bun's runtime resolves SSR, and it applies **React Fast Refresh natively**: editing
+a component-only module swaps its markup with `useState` state intact, no reload. The
+boundary rule is the same as Vite's (see below). The real prize is that dev and production use
+the _same bundler_, so the dev/prod seam disappears.
+
+One gap: **CSS Modules**. Bun's dev-server bundler has no
+`*.module.css` transform (its production `Bun.build` does), so the CLI
+refuses `--bun` for a CSS-Modules app rather than serving a broken client. Plain CSS
+and Tailwind work normally.
 
 ```ts
 // doc-check: skip — fragment: routesDir/outDir/clientModule/createApp are your app's dev config.
-// dev.ts — Bun-native live reload
+// dev.ts — Bun-native HMR, no Vite in the process
 import { createDevServer } from "@nifrajs/web/dev"
-// builds the client on boot, serves SSR, watches routes, full-page live-reload on change.
+// Bun.serve bundles + hot-reloads the client; Bun's runtime resolves SSR. An edit reloads the
+// changed module graph — with React Fast Refresh (state preserved) applied natively by Bun, no plugin.
+// CSS + the entry URL come from Bun. Plain CSS/Tailwind work; *.module.css does not (Bun's dev bundler).
 const server = await createDevServer({ routesDir, outDir, clientModule, createApp })
 ```
 
+### Production is Bun — with a Vite escape hatch
+
+Production builds default to **Bun** (`buildClient` /
+`nifra build`): faster, Bun-native, and the profile Nifra is tuned for. If an app
+genuinely needs a **Vite-only transform** with no Bun equivalent, you can run a
+Vite/Rollup production client build instead — but it must carry the same client-leak guards the
+Bun build enforces, or a second pipeline becomes a way for server-only code to reach the
+browser unnoticed. Add `viteLeakGuard()`: it runs the _same_ detection and
+emits the _same_ error as the Bun build (one implementation, adapted to Rollup's graph),
+so `node:` builtins and `server-only` modules fail the build either way.
+
+```ts
+// vite.config.ts — a Vite/Rollup PRODUCTION client build (the escape hatch, not the default).
+// Only reach for this when an app needs a Vite-only transform with no Bun equivalent; nifra's default
+// production bundler stays Bun (buildClient), which is faster and Bun-native.
+import { viteLeakGuard } from "@nifrajs/web/plugins/vite-leak-guard"
+
+export default {
+  build: {
+    // The SAME two client-leak guards nifra's Bun build runs — server-only code or a node: builtin
+    // reaching the browser fails the build, with the identical error message. A second production
+    // pipeline must not ship without them.
+    rollupOptions: { plugins: [viteLeakGuard()] },
+  },
+}
+```
+
+For the full deploy, `nifra build --vite --target <t>` builds
+_both_ halves — client and SSR worker — with Vite and assembles the identical per-target
+deploy dir the Bun build produces (same `_worker.js` / `server.js`, same
+`_routes.json`, same prerender + size report). Only the bundler differs: both go
+through one orchestrator, so the deploy shape can't drift between pipelines. The leak guards run
+automatically.
+
+You usually don't need the flag. `nifra build` picks the bundler from your config:
+Bun by default, but Vite when your _only_ transforms are `vitePlugins`, and it
+prints the reason. That case is the one where the phase defaults would otherwise bite — dev runs
+Vite, so your plugins run; the Bun build reads `clientPlugins`/
+`serverPlugins` and never `vitePlugins`, so it would drop them and still
+succeed. An app declaring both slots has supplied the Bun equivalent on purpose, so it keeps the
+faster Bun default. `--vite` and `--bun` force the choice; `--bun`
+is refused for a `vitePlugins`-only app rather than silently building without your
+transforms.
+
 ### Styling (CSS)
 
 Import a stylesheet anywhere — `import "./app.css"` in a route, layout, or component.
@@ -5754,6 +5861,33 @@ import { defineAssurancePolicy } from "@nifrajs/core/assurance"
   IP-restriction, and security-header modules publish reflection-safe enforcement evidence.
   An ordered `AssurancePolicy` classifies every route and fails closed on missing or forbidden
   evidence without adding work to the request path.
+- **Owned effect execution.** `executeCapability()` correlates intent and terminal evidence with an
+  opaque `effectId`, records outcomes automatically, and forwards request cancellation. Add
+  order-scoped `aroundCapability()` policies for async approval/admission; they receive token-only
+  metadata, have bounded timeouts, and must call `next()` exactly once before the effect can run.
+- **Durable workflows (opt in).** `@nifrajs/core/durable-execution` provides tenant/principal-bound,
+  signed single-use approval resumes; a durable effect journal + reconciliation scanner; and a typed
+  saga state machine with reverse compensation, retry/backoff, and ambiguous-crash detection. Production
+  constructors reject stores that do not declare `durability: "durable"`. Operational scans use bounded
+  cursor pages through `reconcileEffectsPage()` / `reconcileSagasPage()`. Provider-confirmed manual
+  review uses effect-ID-bound `resolveAmbiguity()`, followed by `resume()` or `compensate()`.
+- **Production durable adapters.** `@nifrajs/core/durable-adapters` supplies
+  `PostgresDurableExecutionAdapter`, `SQLiteDurableExecutionAdapter`, and
+  `DurableObjectExecutionAdapter`. Each exposes compatible `effects`, `approvals`, `sagas`, and
+  `leases` stores. Run `runDurableExecutionAdapterConformance()` against the deployment backend.
+- **Bounded reconciliation workers.** `@nifrajs/core/reconciliation-worker` runs effect or saga
+  scans under an atomic lease with durable cursor checkpoints, a finite page budget, bounded handler
+  concurrency, filters, cancellation, and token-only metrics. A worker invocation always terminates.
+- **Rich wire values (opt in).** `@nifrajs/core/wire` round-trips dates, bigints, maps, sets, binary,
+  shared references, and cycles through JSON transports. Decoding validates every reachable shape,
+  preserves owned `__proto__` keys without prototype mutation, and enforces configurable node, depth,
+  collection-entry, and decoded-byte limits.
+- **Versioned transport codecs (opt in).** Add `.use(transportCodecs(registry))` from
+  `@nifrajs/core/transport-plugin` and configure the typed
+  client's `transport` option with the same registry. `@nifrajs/core/transport-codec` negotiates
+  bounded HTTP representations and supplies the same frame/loader adapters for WebSockets and
+  deferred data. Import `richWireCodec()` from `@nifrajs/core/transport-codec-rich`; the separate
+  subpath keeps rich-wire code out of plain JSON bundles.
 
 ```ts
 import { defineAssurancePolicy, evaluateRouteAssurance, NIFRA_ASSURANCE } from "@nifrajs/core/assurance"
@@ -7375,7 +7509,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/otel
 
-`ActiveObservation`, `AttributeValue`, `causalitySpanLink`, `combineObservationAdapters`, `consoleSpanExporter`, `createObservationLifecycle`, `EndObservation`, `formatTraceparent`, `generateSpanId`, `generateTraceId`, `NifraSpan`, `ObservationAdapter`, `ObservationClock`, `ObservationContext`, `ObservationLifecycle`, `ObservationLifecycleOptions`, `ObservationLink`, `ObservationParent`, `otlpExporter`, `OtlpExporter`, `OtlpExporterOptions`, `ParsedTraceparent`, `parseTraceparent`, `SpanStatus`, `StartObservation`, `TraceContext`, `traceHeaders`, `tracing`, `TracingOptions`
+`ActiveObservation`, `AttributeValue`, `causalitySpanLink`, `combineObservationAdapters`, `consoleSpanExporter`, `createObservationLifecycle`, `effectTracing`, `EffectTracingOptions`, `EffectTracingPlugin`, `EndObservation`, `formatTraceparent`, `generateSpanId`, `generateTraceId`, `NifraSpan`, `ObservationAdapter`, `ObservationClock`, `ObservationContext`, `ObservationLifecycle`, `ObservationLifecycleOptions`, `ObservationLink`, `ObservationParent`, `otlpExporter`, `OtlpExporter`, `OtlpExporterOptions`, `ParsedTraceparent`, `parseTraceparent`, `SpanStatus`, `StartObservation`, `TraceContext`, `traceHeaders`, `tracing`, `TracingOptions`
 
 ## @nifrajs/prompt
 
@@ -7403,7 +7537,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/web
 
-`Action`, `ACTION_GLOBAL`, `apiKey`, `assertRenderAdapterConformance`, `BrowserNavigate`, `buildManifest`, `CachedResponse`, `CacheStore`, `canonical`, `clientEntry`, `ClientRouter`, `ClientRouterOptions`, `createClientRouter`, `createMatcher`, `createMutation`, `createQueryClient`, `createWebApp`, `CreateWebAppOptions`, `DATA_GLOBAL`, `DATA_HEADER`, `DEFAULT_DEV_PORT`, `defer`, `Deferred`, `DehydratedState`, `disableDraft`, `DRAFT_COOKIE`, `DraftCookieControls`, `enableDraft`, `EnableDraftOptions`, `enumerateStaticRoutes`, `Fetcher`, `FetcherState`, `FetchRouteData`, `filePathToPattern`, `filePathToPatterns`, `FontDisplay`, `fontFace`, `FontFace`, `fontPreload`, `FontPreloadInput`, `FontSource`, `generateClientEntry`, `GenerateClientEntryOptions`, `generateServerManifest`, `GenerateServerManifestOptions`, `getBrowserNavigate`, `GetStaticPaths`, `hashQueryKey`, `InfiniteData`, `InfiniteQueryHandle`, `InfiniteQueryOptions`, `isDraftEnabled`, `ISR_REVALIDATE_HEADER`, `ISR_STATUS_HEADER`, `ISRApp`, `ISROptions`, `ISRPlatform`, `jsonLd`, `KVCacheStore`, `KVCacheStoreOptions`, `KVNamespaceLike`, `LayoutEntry`, `LinkDescriptor`, `Loader`, `LoaderContext`, `manifest`, `Manifest`, `MemoryCacheStore`, `MemoryCacheStoreOptions`, `mergeHeads`, `meta`, `Meta`, `MetaArgs`, `MetaInput`, `MountRouterOptions`, `MutationCallbacks`, `MutationHandle`, `MutationState`, `MutationStatus`, `NavigateOptions`, `openGraph`, `OpenGraphInput`, `PRE_HYDRATION_GUARD`, `QueryClient`, `QueryClientOptions`, `QueryHandle`, `QueryOptions`, `QueryState`, `QueryStatus`, `redirect`, `REDIRECT_HEADER`, `RedirectOptions`, `RenderAdapter`, `RenderAdapterConformanceError`, `RenderAdapterConformanceFixture`, `RenderedPage`, `renderPage`, `RenderPageOptions`, `renderPageResult`, `RenderProps`, `resolveMeta`, `revalidate`, `REVALIDATE_HEADER`, `revalidateEndpoint`, `RevalidateEndpointOptions`, `RevalidateResult`, `ROUTE_GLOBAL`, `RouteEntry`, `RouteMatch`, `RouteModule`, `RoutePattern`, `RouterState`, `routeStyles`, `ScriptDescriptor`, `serializeData`, `ServerOnly`, `setBrowserNavigate`, `StaticPath`, `StaticPaths`, `StaticRoutes`, `styles`, `Submission`, `SubmitOptions`, `withISR`
+`Action`, `ACTION_GLOBAL`, `apiKey`, `assertRenderAdapterConformance`, `BrowserNavigate`, `buildManifest`, `CachedResponse`, `CacheStore`, `canonical`, `clientEntry`, `ClientRouter`, `ClientRouterOptions`, `createClientRouter`, `createMatcher`, `createMutation`, `createQueryClient`, `createWebApp`, `CreateWebAppOptions`, `DATA_GLOBAL`, `DATA_HEADER`, `DEFAULT_DEV_PORT`, `defer`, `Deferred`, `DehydratedState`, `disableDraft`, `DRAFT_COOKIE`, `DraftCookieControls`, `enableDraft`, `EnableDraftOptions`, `enumerateStaticRoutes`, `Fetcher`, `FetcherState`, `FetchRouteData`, `filePathToPattern`, `filePathToPatterns`, `FontDisplay`, `fontFace`, `FontFace`, `fontPreload`, `FontPreloadInput`, `FontSource`, `gate`, `generateClientEntry`, `GenerateClientEntryOptions`, `generateServerManifest`, `GenerateServerManifestOptions`, `getBrowserNavigate`, `GetStaticPaths`, `gone`, `hashQueryKey`, `InfiniteData`, `InfiniteQueryHandle`, `InfiniteQueryOptions`, `isDraftEnabled`, `ISR_REVALIDATE_HEADER`, `ISR_STATUS_HEADER`, `ISRApp`, `ISROptions`, `ISRPlatform`, `jsonLd`, `KVCacheStore`, `KVCacheStoreOptions`, `KVNamespaceLike`, `LAYOUT_DATA_GLOBAL`, `LayoutEntry`, `LinkDescriptor`, `Loader`, `LoaderContext`, `manifest`, `Manifest`, `MemoryCacheStore`, `MemoryCacheStoreOptions`, `mergeHeads`, `meta`, `Meta`, `MetaArgs`, `MetaInput`, `MountRouterOptions`, `MutationCallbacks`, `MutationHandle`, `MutationState`, `MutationStatus`, `NAV_FROM_HEADER`, `NavigateOptions`, `notFound`, `openGraph`, `OpenGraphInput`, `PRE_HYDRATION_GUARD`, `previewEndpoint`, `PreviewEndpointOptions`, `PublicDirCache`, `QueryClient`, `QueryClientOptions`, `QueryHandle`, `QueryOptions`, `QueryState`, `QueryStatus`, `redirect`, `REDIRECT_HEADER`, `RedirectOptions`, `RenderAdapter`, `RenderAdapterConformanceError`, `RenderAdapterConformanceFixture`, `RenderedPage`, `renderPage`, `RenderPageOptions`, `renderPageResult`, `RenderProps`, `resolveMeta`, `resolvePublicPath`, `RETAIN_HEADER`, `revalidate`, `REVALIDATE_HEADER`, `revalidateEndpoint`, `RevalidateEndpointOptions`, `RevalidateResult`, `ROUTE_GLOBAL`, `RouteEntry`, `RouteMatch`, `RouteModule`, `RoutePattern`, `RouterState`, `routeStyles`, `ScriptDescriptor`, `serializeData`, `servePublicDir`, `ServePublicDirOptions`, `ServerOnly`, `setBrowserNavigate`, `StaticPath`, `StaticPaths`, `StaticRoutes`, `STATUS_HEADER`, `statusPage`, `StatusPageOptions`, `styles`, `Submission`, `SubmitOptions`, `withISR`
 
 ## @nifrajs/web-preact