@nifrajs/web 2.1.0 → 2.3.0

package/dist/public-dir.js

@@ -0,0 +1,89 @@
+/**
+ * `public/` - user-authored static files, served identically in dev and in production.
+ *
+ * The asymmetry this closes: `nifra dev` served `public/` for free because the HMR path runs on Vite
+ * and Vite serves `public/` by default, while production had no `publicDir` concept at all. So a file
+ * worked all the way through development and 404'd the moment it was deployed. The failure is
+ * inverted - it appears only in production, and only for the assets nobody smoke-tests - and it has
+ * already shipped once as a self-hosted webfont that silently fell back to a system font in prod.
+ *
+ * One owner for both sides is the fix, not a second implementation that happens to agree today.
+ *
+ * Distinct from `publicPath` in `build.ts`, which is the URL prefix for content-hashed bundle chunks.
+ * The names collide and the concepts do not: `publicPath` never covers user-authored files.
+ */
+import { realpath } from "node:fs/promises";
+import { normalize, resolve, sep } from "node:path";
+const IMMUTABLE = "public, max-age=31536000, immutable";
+const ONE_DAY = "public, max-age=86400";
+/**
+ * Resolve a URL pathname to an absolute path **confined** to `root`, or `undefined` if it escapes.
+ *
+ * This is a user-path-to-filesystem sink, which makes it the one part of this feature with a security
+ * consequence. Decode first (`%2e%2e%2f` is `../`), then normalize, then verify the result is still
+ * under `root` by prefix - checking the *resolved* path rather than scanning the input for `..`,
+ * because a blocklist over encodings is exactly the kind of check that gets bypassed.
+ */
+export function resolvePublicPath(root, pathname) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(pathname);
+    }
+    catch {
+        return undefined; // malformed percent-encoding: not a path we will guess at
+    }
+    // A NUL can truncate a path in a downstream syscall; refuse rather than normalize it away.
+    if (decoded.includes("\0"))
+        return undefined;
+    const rootResolved = resolve(root);
+    const candidate = resolve(rootResolved, `.${normalize(decoded)}`);
+    if (candidate !== rootResolved && !candidate.startsWith(rootResolved + sep))
+        return undefined;
+    return candidate;
+}
+/**
+ * Build a static-file handler for `dir`.
+ *
+ * Returns `undefined` on any miss so the caller **falls through to routing** - a static probe must
+ * never shadow a route. That ordering is also why a `routes/robots.txt.tsx` beats a
+ * `public/robots.txt` only if the caller checks routes first; the documented precedence is that the
+ * static probe runs first, so `public/` wins, and an app wanting the route should not ship both.
+ */
+export function servePublicDir(options) {
+    const root = resolve(options.dir);
+    const rootReal = realpath(root).catch(() => undefined);
+    const hashedPrefix = options.hashedPrefix ?? "/assets/";
+    const hashed = options.cache?.hashed ?? IMMUTABLE;
+    const assets = options.cache?.assets ?? ONE_DAY;
+    return async (request) => {
+        if (request.method !== "GET" && request.method !== "HEAD")
+            return undefined;
+        const { pathname } = new URL(request.url);
+        // A production manifest can reject page routes without touching the filesystem.
+        if (options.files !== undefined && !options.files.has(pathname))
+            return undefined;
+        const abs = resolvePublicPath(root, pathname);
+        if (abs === undefined)
+            return undefined;
+        const [resolvedRoot, resolvedFile] = await Promise.all([
+            rootReal,
+            realpath(abs).catch(() => undefined),
+        ]);
+        if (resolvedRoot === undefined ||
+            resolvedFile === undefined ||
+            (resolvedFile !== resolvedRoot && !resolvedFile.startsWith(resolvedRoot + sep))) {
+            return undefined;
+        }
+        const file = Bun.file(resolvedFile);
+        if (!(await file.exists()))
+            return undefined;
+        const headers = new Headers({
+            "cache-control": pathname.startsWith(hashedPrefix) ? hashed : assets,
+        });
+        // HEAD must not carry a body, but must otherwise match GET's headers.
+        return request.method === "HEAD"
+            ? new Response(null, { headers })
+            : new Response(file, { headers });
+    };
+}
+//# sourceMappingURL=public-dir.js.map

package/dist/public-dir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-dir.js","sourceRoot":"","sources":["../src/public-dir.ts"],"names":[],"mappings":"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"}

package/dist/query.d.ts

@@ -1,8 +1,8 @@
 /**
- * The agnostic keyed query-cache — a `query(key, fn)` primitive with in-flight dedup, `staleTime`
+ * The agnostic keyed query-cache - a `query(key, fn)` primitive with in-flight dedup, `staleTime`
  * freshness, prefix `invalidateQueries`, imperative cache read/write, prefetch, SSR dehydrate/hydrate,
  * infinite (paged) queries, and standalone mutations. Pure logic, no `window`, no framework, no
- * `Date.now`/timers (the clock is injected) — so it unit-tests deterministically and is safe to import
+ * `Date.now`/timers (the clock is injected) - so it unit-tests deterministically and is safe to import
  * from the SSR core's main entry. A per-adapter binding (`useQuery`/`useMutation`/`createQuery`)
  * subscribes to a query/mutation's `subscribe`/`snapshot` store (the same shape the router + fetchers
  * use).
@@ -13,13 +13,13 @@
  */
 /** A query's lifecycle status. `pending` = no data yet; `success`/`error` once it has settled once. */
 export type QueryStatus = "pending" | "success" | "error";
-/** A query's observable state — what a binding renders. A new (frozen) object per transition, so a
+/** A query's observable state - what a binding renders. A new (frozen) object per transition, so a
  * `useSyncExternalStore`/signal binding can compare by reference. */
 export interface QueryState<T = unknown> {
     readonly status: QueryStatus;
     readonly data: T | undefined;
     readonly error: unknown;
-    /** True while a fetch is in flight — the initial load OR a background refetch (data may still show). */
+    /** True while a fetch is in flight - the initial load OR a background refetch (data may still show). */
     readonly isFetching: boolean;
     /** When `data` was last set (via the injected clock); drives `staleTime`. `-Infinity` until first set. */
     readonly updatedAt: number;
@@ -41,14 +41,14 @@ export interface QueryOptions {
     readonly staleTime?: number;
 }
 export interface QueryClientOptions {
-    /** Monotonic clock in ms — injected so the core stays deterministic + testable; the adapter binding
+    /** Monotonic clock in ms - injected so the core stays deterministic + testable; the adapter binding
      * passes `() => Date.now()`. */
     readonly now: () => number;
     /** Data stays fresh this long after a fetch; older ⇒ refetch on the next `fetch()` (default `0`). */
     readonly staleTime?: number;
     /** Evict an entry this long (ms) after its last subscriber leaves (default 5 min). */
     readonly gcTime?: number;
-    /** Hard cap on cached entries — LRU-evict the oldest *unsubscribed* entry past it (default 1000). */
+    /** Hard cap on cached entries - LRU-evict the oldest *unsubscribed* entry past it (default 1000). */
     readonly max?: number;
 }
 /** An infinite (paged) query's accumulated data: the fetched `pages` in order + the `pageParam` each
@@ -58,7 +58,7 @@ export interface InfiniteData<T, P> {
     readonly pageParams: readonly P[];
 }
 /** Options for an {@link InfiniteQueryHandle}. `getNextPageParam` (required) derives the param for the
- * next page from the last page — return `undefined`/`null` to signal there is no next page. */
+ * next page from the last page - return `undefined`/`null` to signal there is no next page. */
 export interface InfiniteQueryOptions<T, P> extends QueryOptions {
     /** The param the FIRST page is fetched with. */
     readonly initialPageParam: P;
@@ -85,7 +85,7 @@ export interface InfiniteQueryHandle<T, P> {
     /** Whether a page can be prepended (derived from `getPreviousPageParam` of the first page). */
     hasPreviousPage: () => boolean;
 }
-/** A serializable snapshot of the cache's successful queries — the SSR→client bridge payload. */
+/** A serializable snapshot of the cache's successful queries - the SSR→client bridge payload. */
 export interface DehydratedState {
     readonly queries: ReadonlyArray<{
         readonly key: unknown;
@@ -119,7 +119,7 @@ export interface QueryClient {
 }
 /**
  * Hash a query key to a stable cache string. Object keys are sorted (so `{a,b}` ≡ `{b,a}`); arrays
- * keep order. Keys must be serializable — a function/symbol in the key throws (it can't be a stable
+ * keep order. Keys must be serializable - a function/symbol in the key throws (it can't be a stable
  * identity). Mirrors TanStack Query's structural hashing.
  */
 export declare function hashQueryKey(key: unknown): string;
@@ -154,7 +154,7 @@ export interface MutationHandle<TData, TVariables> {
     reset: () => void;
 }
 /**
- * Create a standalone mutation state machine — framework-agnostic, so a per-adapter `useMutation`
+ * Create a standalone mutation state machine - framework-agnostic, so a per-adapter `useMutation`
  * binding just subscribes to it. Single-flight by a monotonic token: overlapping `mutate` calls each
  * run their `fn`, but only the latest publishes state (an older, slower response can't clobber a newer
  * one). The callbacks fire in TanStack order: `onMutate` (before), then `onSuccess`/`onError`, then

package/dist/query.js

@@ -1,8 +1,8 @@
 /**
- * The agnostic keyed query-cache — a `query(key, fn)` primitive with in-flight dedup, `staleTime`
+ * The agnostic keyed query-cache - a `query(key, fn)` primitive with in-flight dedup, `staleTime`
  * freshness, prefix `invalidateQueries`, imperative cache read/write, prefetch, SSR dehydrate/hydrate,
  * infinite (paged) queries, and standalone mutations. Pure logic, no `window`, no framework, no
- * `Date.now`/timers (the clock is injected) — so it unit-tests deterministically and is safe to import
+ * `Date.now`/timers (the clock is injected) - so it unit-tests deterministically and is safe to import
  * from the SSR core's main entry. A per-adapter binding (`useQuery`/`useMutation`/`createQuery`)
  * subscribes to a query/mutation's `subscribe`/`snapshot` store (the same shape the router + fetchers
  * use).
@@ -13,7 +13,7 @@
  */
 /**
  * Hash a query key to a stable cache string. Object keys are sorted (so `{a,b}` ≡ `{b,a}`); arrays
- * keep order. Keys must be serializable — a function/symbol in the key throws (it can't be a stable
+ * keep order. Keys must be serializable - a function/symbol in the key throws (it can't be a stable
  * identity). Mirrors TanStack Query's structural hashing.
  */
 export function hashQueryKey(key) {
@@ -54,7 +54,7 @@ export function createQueryClient(options) {
     const max = options.max ?? 1000;
     const cache = new Map();
     // Lazily evict entries whose GC timer has elapsed (no subscribers), then enforce the hard cap by
-    // dropping the oldest-inserted unsubscribed entries. Called on every `query()` — no background timer.
+    // dropping the oldest-inserted unsubscribed entries. Called on every `query()` - no background timer.
     const sweep = () => {
         const t = now();
         for (const [h, e] of cache) {
@@ -91,8 +91,8 @@ export function createQueryClient(options) {
             handle: undefined,
         };
         const emit = () => {
-            // Iterate the live set — no per-emit copy (the common case is 0–1 subscribers). Contract: a
-            // listener must not synchronously subscribe/unsubscribe during notification — `useSyncExternalStore`/
+            // Iterate the live set - no per-emit copy (the common case is 0-1 subscribers). Contract: a
+            // listener must not synchronously subscribe/unsubscribe during notification - `useSyncExternalStore`/
             // signal/store bindings don't (un/subscribe happens in a later effect/cleanup tick).
             if (entry.listeners.size === 0)
                 return;
@@ -105,20 +105,20 @@ export function createQueryClient(options) {
         };
         const isStale = () => entry.invalidated || now() - entry.state.updatedAt >= entry.staleTime;
         entry.run = (force) => {
-            // Dedup — but join the in-flight fetch ONLY when it belongs to the current generation. An
+            // Dedup - but join the in-flight fetch ONLY when it belongs to the current generation. An
             // `invalidateQueries` bumps `generation`, so a fetch that started *before* the invalidation is
             // superseded and must NOT satisfy this call (its data is pre-mutation); fall through and kick a
             // fresh fetch instead of returning the stale in-flight one.
             if (entry.promise !== undefined && entry.promiseGen === entry.generation)
                 return entry.promise;
             if (!force && entry.state.status === "success" && !isStale())
-                return Promise.resolve(entry.state.data); // fresh cache hit — no fn call
+                return Promise.resolve(entry.state.data); // fresh cache hit - no fn call
             const gen = entry.generation;
             entry.setState({ ...entry.state, isFetching: true }); // show the background/initial fetch
             const promise = (async () => {
                 try {
                     const data = await entry.fn();
-                    // A newer generation (a later invalidate/refetch) owns the entry now — discard this result
+                    // A newer generation (a later invalidate/refetch) owns the entry now - discard this result
                     // rather than publishing pre-mutation data as fresh or clearing `invalidated`. The fetch
                     // that superseded this one publishes the post-mutation data.
                     if (gen !== entry.generation)
@@ -148,7 +148,7 @@ export function createQueryClient(options) {
             snapshot: () => entry.state,
             subscribe: (listener) => {
                 entry.subscribers++;
-                entry.gcAt = undefined; // in use again — cancel any pending eviction
+                entry.gcAt = undefined; // in use again - cancel any pending eviction
                 entry.listeners.add(listener);
                 return () => {
                     entry.listeners.delete(listener);
@@ -185,7 +185,7 @@ export function createQueryClient(options) {
             if (!keyMatchesPrefix(entry.key, keyOrPrefix))
                 continue;
             entry.invalidated = true; // next fetch refetches even within staleTime
-            // Supersede any in-flight fetch begun before this point — its result is pre-mutation and must
+            // Supersede any in-flight fetch begun before this point - its result is pre-mutation and must
             // not resolve as "fresh" or clear `invalidated`. The refetch below (or the next `fetch()`)
             // starts a new generation that publishes the post-mutation data.
             entry.generation++;
@@ -200,13 +200,13 @@ export function createQueryClient(options) {
             : undefined;
     };
     const setQueryData = (key, updater) => {
-        // Create a placeholder entry if none exists — its `fn` throws until a real `query(key, fn)` re-binds
+        // Create a placeholder entry if none exists - its `fn` throws until a real `query(key, fn)` re-binds
         // it, so a `setQueryData` for a key nobody queries yet never triggers a fetch on its own.
         const entry = upsert(key, cache.get(hashQueryKey(key))?.fn ??
             (() => Promise.reject(new Error("[nifra/web] query has no fetcher (setQueryData-only key)"))), defaultStaleTime);
         const prev = entry.state.status === "success" ? entry.state.data : undefined;
         const data = typeof updater === "function" ? updater(prev) : updater;
-        // A direct write is the new truth — bump the generation so any in-flight fetch can't overwrite it,
+        // A direct write is the new truth - bump the generation so any in-flight fetch can't overwrite it,
         // and clear the invalidated flag (the caller just supplied fresh data).
         entry.generation++;
         entry.invalidated = false;
@@ -391,7 +391,7 @@ const IDLE_MUTATION = Object.freeze({
     variables: undefined,
 });
 /**
- * Create a standalone mutation state machine — framework-agnostic, so a per-adapter `useMutation`
+ * Create a standalone mutation state machine - framework-agnostic, so a per-adapter `useMutation`
  * binding just subscribes to it. Single-flight by a monotonic token: overlapping `mutate` calls each
  * run their `fn`, but only the latest publishes state (an older, slower response can't clobber a newer
  * one). The callbacks fire in TanStack order: `onMutate` (before), then `onSuccess`/`onError`, then
@@ -427,7 +427,7 @@ export function createMutation(fn, callbacks = {}) {
         mutate: async (variables) => {
             const mine = ++token;
             setState({ status: "pending", data: undefined, error: undefined, variables });
-            // Only await a callback when one is actually supplied — an `await undefined` would insert a
+            // Only await a callback when one is actually supplied - an `await undefined` would insert a
             // needless microtask before the mutationFn runs (and complicates single-flight timing).
             if (cbs.onMutate !== undefined)
                 await cbs.onMutate(variables);

package/dist/route-manifest.d.ts

@@ -0,0 +1,91 @@
+/**
+ * `@nifrajs/web/route-manifest` - what each route actually DOES, as one artifact.
+ *
+ * The facts are already in the route modules: `prerender`, `getStaticPaths`, `revalidate`, `hydrate`.
+ * What has never existed is anywhere to read them together. To answer "which pages are static?", "which
+ * ones revalidate, and how often?", "which ship no JS?", you open every route file and hold the answer in
+ * your head - and the answer changes on the target you deploy to, which is nowhere near the route file.
+ *
+ * That gap is not just inconvenient. The interesting cases are the ones where a route's declaration and
+ * its deploy target disagree, and there is currently nothing that can notice: an ISR route on a target
+ * with no revalidation story regenerates on every request; a `static` build containing a route that was
+ * never prerenderable ships a page that 404s. Both are silent, and both are decided at build time by
+ * information no single place holds.
+ *
+ * So this derives one record per route - render mode, hydration, cache policy - resolves it against the
+ * target, and reports what the target cannot honour. Pure and fs-free: it takes an already-built
+ * `Manifest` so it runs at build time, in `nifra routes`, and in a test with a hand-built manifest.
+ */
+import type { Manifest, RouteModule } from "./manifest.js";
+/**
+ * How a route produces its HTML.
+ *
+ * - `static`  - prerendered at build; served as a file, no server render at request time.
+ * - `isr`     - server-rendered, then cached and revalidated on a timer (`export const revalidate`).
+ * - `ssr`     - server-rendered per request. The default, and the only mode that needs a live server.
+ */
+export type RenderMode = "static" | "isr" | "ssr";
+/** What a route needs from its host in order to behave as declared. */
+export type RouteCapability = "server" | "revalidation";
+/** One route's resolved behaviour. */
+export interface RouteManifestEntry {
+    /** The route's id (its key in the build manifest and in `routes`). */
+    readonly id: string;
+    /** The matching pattern, e.g. `/blog/:slug`. */
+    readonly pattern: string;
+    readonly mode: RenderMode;
+    /** Whether the full-document client is shipped. `false` means the page loads no framework JS. */
+    readonly hydrate: boolean;
+    /** Revalidation window in seconds. Present only for `isr`. */
+    readonly revalidate?: number;
+    /**
+     * Concrete paths prerendered at build. Present for `static` routes: a single path for a static route,
+     * one per `getStaticPaths` entry for a dynamic one. Absent means "no path was enumerated", which for a
+     * dynamic route is exactly the condition that makes it unprerenderable.
+     */
+    readonly prerenderedPaths?: readonly string[];
+    /** What this route needs from the host to behave as declared. */
+    readonly requires: readonly RouteCapability[];
+}
+/** A route whose declaration the chosen target cannot honour, and what actually happens if it ships. */
+export interface RouteManifestConflict {
+    readonly id: string;
+    readonly pattern: string;
+    readonly capability: RouteCapability;
+    /** What goes wrong on this target - the consequence, not the rule that was broken. */
+    readonly consequence: string;
+}
+/** The whole artifact: every route's behaviour, plus anything the target cannot honour. */
+export interface RouteManifest {
+    /** The deploy target this was resolved against, when one was given. */
+    readonly target?: string;
+    readonly routes: readonly RouteManifestEntry[];
+    readonly conflicts: readonly RouteManifestConflict[];
+    /** Route counts by mode - the summary a report leads with. */
+    readonly totals: Readonly<Record<RenderMode, number>>;
+}
+/**
+ * Derive one route's behaviour from its module exports.
+ *
+ * `prerender`/`getStaticPaths` win over `revalidate`: a page rendered at build time is not revalidated at
+ * runtime, so if a route declares both, the build-time answer is the one that describes what ships. That
+ * combination is worth surfacing rather than silently resolving, which is what `conflicts` is for once a
+ * target is known.
+ */
+export declare function deriveRouteEntry(id: string, pattern: string, module: Pick<RouteModule, "prerender" | "getStaticPaths" | "revalidate" | "hydrate">, prerenderedPaths?: readonly string[]): RouteManifestEntry;
+/**
+ * Build the route manifest for a discovered app, optionally resolved against a deploy target.
+ *
+ * `prerendered` maps a route id to the concrete paths the build actually emitted for it - pass what
+ * `prerenderRoutes` produced. Without it, dynamic routes are reported by their declaration alone, which
+ * is the right answer before a build has run and the wrong one after.
+ */
+export declare function buildRouteManifest(manifest: Manifest, options?: {
+    readonly target?: string;
+    readonly prerendered?: Readonly<Record<string, readonly string[]>>;
+    /** Runtime capabilities supplied outside generated entries (for example an explicit `withISR`). */
+    readonly capabilities?: readonly RouteCapability[];
+}): Promise<RouteManifest>;
+/** Render the manifest as a readable report - the `nifra routes --modes` output. */
+export declare function renderRouteManifest(manifest: RouteManifest): string;
+//# sourceMappingURL=route-manifest.d.ts.map

package/dist/route-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-manifest.d.ts","sourceRoot":"","sources":["../src/route-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAE1D;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,KAAK,GAAG,KAAK,CAAA;AAEjD,uEAAuE;AACvE,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,cAAc,CAAA;AAEvD,sCAAsC;AACtC,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,iGAAiG;IACjG,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7C,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;CAC9C;AAED,wGAAwG;AACxG,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAA;IACpC,sFAAsF;IACtF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,2FAA2F;AAC3F,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAC9C,QAAQ,CAAC,SAAS,EAAE,SAAS,qBAAqB,EAAE,CAAA;IACpD,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAA;CACtD;AAKD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,gBAAgB,GAAG,YAAY,GAAG,SAAS,CAAC,EACpF,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,GACnC,kBAAkB,CAyBpB;AA0BD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE;IACP,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAA;IAClE,mGAAmG;IACnG,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,eAAe,EAAE,CAAA;CAC9C,GACL,OAAO,CAAC,aAAa,CAAC,CAuCxB;AAED,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CA2CnE"}

package/dist/route-manifest.js

@@ -0,0 +1,128 @@
+/** A route is dynamic when its pattern carries a param or wildcard segment. */
+const isDynamic = (pattern) => /[:*]/.test(pattern);
+/**
+ * Derive one route's behaviour from its module exports.
+ *
+ * `prerender`/`getStaticPaths` win over `revalidate`: a page rendered at build time is not revalidated at
+ * runtime, so if a route declares both, the build-time answer is the one that describes what ships. That
+ * combination is worth surfacing rather than silently resolving, which is what `conflicts` is for once a
+ * target is known.
+ */
+export function deriveRouteEntry(id, pattern, module, prerenderedPaths) {
+    const wantsPrerender = module.prerender === true || module.getStaticPaths !== undefined;
+    // A dynamic route is only really static if concrete paths were enumerated for it. `getStaticPaths`
+    // declares the intent; the paths are the evidence, and without them there is nothing prerendered to
+    // serve. Treating intent as sufficient is how a "static" build ships a page that 404s.
+    const enumerated = prerenderedPaths !== undefined && prerenderedPaths.length > 0;
+    const isStatic = wantsPrerender && (!isDynamic(pattern) || enumerated);
+    const mode = isStatic ? "static" : module.revalidate !== undefined ? "isr" : "ssr";
+    const requires = [];
+    if (mode !== "static")
+        requires.push("server");
+    if (mode === "isr")
+        requires.push("revalidation");
+    const entry = { id, pattern, mode, hydrate: module.hydrate !== false, requires };
+    if (mode === "isr" && module.revalidate !== undefined)
+        entry.revalidate = module.revalidate;
+    if (prerenderedPaths !== undefined)
+        entry.prerenderedPaths = prerenderedPaths;
+    return entry;
+}
+/**
+ * What each deploy target can actually do.
+ *
+ * `static` is the one that matters: it has no server at all, so every non-prerendered route is a page
+ * that will 404 in production while working perfectly in dev. The rest all run a server; they differ in
+ * how revalidation is wired, not in whether it exists, so this deliberately does not invent finer
+ * distinctions it cannot verify.
+ */
+const TARGET_CAPABILITIES = {
+    bun: ["server"],
+    node: ["server"],
+    deno: ["server"],
+    "cf-pages": ["server"],
+    vercel: ["server"],
+    static: [],
+};
+const CONSEQUENCE = {
+    server: "this target ships no server, so the route is never rendered - the URL 404s in production while working in dev. Add `export const prerender = true` (or `getStaticPaths` for a dynamic route), or build for a target that runs a server.",
+    revalidation: "this target cannot revalidate a cached page, so `revalidate` has no effect and the route renders on every request.",
+};
+/**
+ * Build the route manifest for a discovered app, optionally resolved against a deploy target.
+ *
+ * `prerendered` maps a route id to the concrete paths the build actually emitted for it - pass what
+ * `prerenderRoutes` produced. Without it, dynamic routes are reported by their declaration alone, which
+ * is the right answer before a build has run and the wrong one after.
+ */
+export async function buildRouteManifest(manifest, options = {}) {
+    const entries = [];
+    for (const route of manifest.routes) {
+        // Loading the module is what makes this authoritative rather than a guess from the filename: the
+        // render mode lives in the module's exports and nowhere else.
+        const module = (await route.load());
+        entries.push(deriveRouteEntry(route.id, route.pattern, module, options.prerendered?.[route.id]));
+    }
+    entries.sort((a, b) => a.pattern.localeCompare(b.pattern));
+    const conflicts = [];
+    const capabilities = options.capabilities ??
+        (options.target === undefined ? undefined : TARGET_CAPABILITIES[options.target]);
+    if (capabilities !== undefined) {
+        for (const entry of entries) {
+            for (const capability of entry.requires) {
+                if (capabilities.includes(capability))
+                    continue;
+                conflicts.push({
+                    id: entry.id,
+                    pattern: entry.pattern,
+                    capability,
+                    consequence: CONSEQUENCE[capability],
+                });
+            }
+        }
+    }
+    const totals = { static: 0, isr: 0, ssr: 0 };
+    for (const entry of entries)
+        totals[entry.mode] += 1;
+    const result = { routes: entries, conflicts, totals };
+    if (options.target !== undefined)
+        result.target = options.target;
+    return result;
+}
+/** Render the manifest as a readable report - the `nifra routes --modes` output. */
+export function renderRouteManifest(manifest) {
+    const lines = [];
+    lines.push(manifest.target === undefined
+        ? "nifra route manifest"
+        : `nifra route manifest - target: ${manifest.target}`);
+    lines.push("");
+    if (manifest.routes.length === 0) {
+        lines.push("no routes found.");
+        return lines.join("\n");
+    }
+    const width = Math.max(10, ...manifest.routes.map((r) => r.pattern.length)) + 2;
+    lines.push(`${"route".padEnd(width)}${"mode".padEnd(9)}${"hydrate".padEnd(9)}cache`);
+    lines.push("-".repeat(width + 18 + 24));
+    for (const route of manifest.routes) {
+        const cache = route.mode === "isr"
+            ? `revalidate ${route.revalidate}s`
+            : route.mode === "static"
+                ? `prerendered${route.prerenderedPaths ? ` (${route.prerenderedPaths.length})` : ""}`
+                : "per request";
+        lines.push(route.pattern.padEnd(width) +
+            route.mode.padEnd(9) +
+            (route.hydrate ? "yes" : "no").padEnd(9) +
+            cache);
+    }
+    lines.push("");
+    lines.push(`${manifest.totals.static} static · ${manifest.totals.isr} isr · ${manifest.totals.ssr} ssr`);
+    if (manifest.conflicts.length > 0) {
+        lines.push("");
+        lines.push(`✗ ${manifest.conflicts.length} route(s) the target cannot honour:`);
+        for (const conflict of manifest.conflicts) {
+            lines.push(`  ✗ ${conflict.pattern} - ${conflict.consequence}`);
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=route-manifest.js.map

package/dist/route-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-manifest.js","sourceRoot":"","sources":["../src/route-manifest.ts"],"names":[],"mappings":"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"}