@nifrajs/cli 2.14.1 → 3.1.0

package/dist/rules/routes.js

@@ -1,3 +1,4 @@
+import { RESERVED_KEY_READOUT, reservedKeyFor } from "@nifrajs/client";
 import { diagnostic } from "../diagnostics.js";
 import { commentBlockHasMarker } from "./comment-markers.js";
 /**
@@ -5,26 +6,18 @@ import { commentBlockHasMarker } from "./comment-markers.js";
  * once before the registry runs - no rule re-walks source).
  *
  * NF-C018 exists because the typed client's proxy intercepts a fixed set of property names before
- * path resolution (`resolveSegment` + the thenable guard in @nifrajs/client): the seven HTTP verbs
- * (case-insensitively), `subscribe`, `ws`, `index`, and `then`. A route whose path contains a
- * static segment spelling one of these cannot be reached by DOT ACCESS - `api.delete.post` resolves
- * the DELETE verb, not the path. The typed spelling is a call on the parent node
- * (`api.api("delete").post()`, treaty.ts `CollisionEscape`), and the client type rejects the dot
- * access with the same guidance - so the collision is a warning that teaches the escape spelling,
- * not a blocking error: the route IS reachable, just not by the spelling its name suggests.
+ * path resolution (`resolveSegment` + the thenable guard in @nifrajs/client). A route whose path
+ * contains a static segment spelling one of these cannot be reached by DOT ACCESS -
+ * `api.delete.post` resolves the DELETE verb, not the path. The typed spelling is a call on the
+ * parent node (`api.api("delete").post()`, treaty.ts `SegmentCall`), and the client type rejects
+ * the dot access with the same guidance - so the collision is a warning that teaches the call
+ * spelling, not a blocking error: the route IS reachable, just not by the spelling its name
+ * suggests.
+ *
+ * The set itself is NOT copied here. It comes from `@nifrajs/client`'s `reserved.ts`, which is the
+ * one place it is written down and the one place the freeze policy lives - a lint that carried its
+ * own copy is a lint that can disagree with the compiler it is explaining.
  */
-const RESERVED_VERB_SEGMENTS = new Set([
-    "get",
-    "post",
-    "put",
-    "patch",
-    "delete",
-    "head",
-    "options",
-]);
-// Intercepted by exact match only (`key === "subscribe"` etc.), unlike the lowercased verbs.
-const RESERVED_EXACT_SEGMENTS = new Set(["subscribe", "ws", "index", "then"]);
-const RESERVED_READOUT = "get/post/put/patch/delete/head/options (any casing), subscribe, ws, index, then";
 /** Opt-out pragma for a route deliberately served only to NON-typed-client consumers. */
 const RESERVED_SEGMENT_PRAGMA = "nifra-expect reserved-segment";
 /** Parse-don't-cast over the project fact: a malformed entry is dropped, never trusted. */
@@ -54,15 +47,6 @@ function routeEscapeHint(path, colliding) {
     const before = segments.slice(0, Math.max(segments.indexOf(colliding), 0));
     return `${["api", ...before].join(".")}("${colliding}")`;
 }
-/** The reserved key a static path segment collides with, or undefined. Params/wildcards never collide. */
-function reservedCollision(segment) {
-    if (segment.startsWith(":") || segment.startsWith("*"))
-        return undefined;
-    if (RESERVED_EXACT_SEGMENTS.has(segment))
-        return segment;
-    const lower = segment.toLowerCase();
-    return RESERVED_VERB_SEGMENTS.has(lower) ? lower : undefined;
-}
 export const reservedSegmentRule = {
     code: "NF-C018",
     title: "Route segment collides with a reserved client proxy key",
@@ -73,7 +57,7 @@ export const reservedSegmentRule = {
             for (const segment of route.path.split("/")) {
                 if (segment === "")
                     continue;
-                const collision = reservedCollision(segment);
+                const collision = reservedKeyFor(segment);
                 if (collision === undefined)
                     continue;
                 let lines = linesByFile.get(route.file);
@@ -88,8 +72,11 @@ export const reservedSegmentRule = {
                     severity: "warn",
                     file: route.file,
                     line: route.line,
-                    message: `${route.method} ${route.path} - segment '${segment}' collides with the reserved client proxy key '${collision}' (reserved: ${RESERVED_READOUT}); dot access cannot reach it - call the parent node with the segment instead (\`${routeEscapeHint(route.path, segment)}\`), rename the segment, or mark an intentionally non-typed-client route with \`// ${RESERVED_SEGMENT_PRAGMA}\` above the registration`,
+                    message: `${route.method} ${route.path} - segment '${segment}' collides with the reserved client proxy key '${collision}' (reserved: ${RESERVED_KEY_READOUT}); dot access cannot reach it - call the parent node with the segment instead (\`${routeEscapeHint(route.path, segment)}\`), rename the segment, or mark an intentionally non-typed-client route with \`// ${RESERVED_SEGMENT_PRAGMA}\` above the registration. \`nifra fix --code NF-C018\` rewrites the broken call sites for you`,
                     evidence: [`${route.method} ${route.path}`, `segment: ${segment}`],
+                    // The route is fine; what needs editing is every typed-client call site the collision
+                    // broke, which the recipe finds from the compiler rather than from this one finding.
+                    fix: { recipe: "client.reserved-segment", command: "nifra fix --code NF-C018" },
                     verify: "nifra check --lints-only",
                 }));
                 break; // one finding per route, even if several segments collide

package/dist/rules/routes.js.map

@@ -1 +1 @@
-{"version":3,"file":"routes.js","sourceRoot":"","sources":["../../src/rules/routes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAG5D;;;;;;;;;;;;GAYG;AACH,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC;IAC1D,KAAK;IACL,MAAM;IACN,KAAK;IACL,OAAO;IACP,QAAQ;IACR,MAAM;IACN,SAAS;CACV,CAAC,CAAA;AACF,6FAA6F;AAC7F,MAAM,uBAAuB,GAAwB,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAA;AAClG,MAAM,gBAAgB,GACpB,iFAAiF,CAAA;AAEnF,yFAAyF;AACzF,MAAM,uBAAuB,GAAG,+BAA+B,CAAA;AAS/D,2FAA2F;AAC3F,SAAS,UAAU,CAAC,GAAgB;IAClC,MAAM,GAAG,GAAuB,GAAG,CAAC,OAAO,CAAC,MAAM,CAAA;IAClD,MAAM,GAAG,GAAsB,EAAE,CAAA;IACjC,KAAK,MAAM,IAAI,IAAI,GAAG,EAAE,CAAC;QACvB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YAAE,SAAQ;QAC9E,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;QACvD,IACE,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;YAC/B,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;YAC/B,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ;YACjC,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;YAE/B,SAAQ;QACV,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAA;IAC9F,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;GAIG;AACH,SAAS,eAAe,CAAC,IAAY,EAAE,SAAiB;IACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,EAAE,CAAC,CAAA;IACpE,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IAC1E,OAAO,GAAG,CAAC,KAAK,EAAE,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,SAAS,IAAI,CAAA;AAC1D,CAAC;AAED,0GAA0G;AAC1G,SAAS,iBAAiB,CAAC,OAAe;IACxC,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAA;IACxE,IAAI,uBAAuB,CAAC,GAAG,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAA;IACxD,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAA;IACnC,OAAO,sBAAsB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AAC9D,CAAC;AAED,MAAM,CAAC,MAAM,mBAAmB,GAAc;IAC5C,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,yDAAyD;IAChE,KAAK,CAAC,IAAI,CAAC,GAAG;QACZ,MAAM,QAAQ,GAAiB,EAAE,CAAA;QACjC,MAAM,WAAW,GAAG,IAAI,GAAG,EAA6B,CAAA;QACxD,KAAK,MAAM,KAAK,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACpC,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC5C,IAAI,OAAO,KAAK,EAAE;oBAAE,SAAQ;gBAC5B,MAAM,SAAS,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAA;gBAC5C,IAAI,SAAS,KAAK,SAAS;oBAAE,SAAQ;gBACrC,IAAI,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBACvC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;oBACxB,KAAK,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;oBAC/D,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;gBACpC,CAAC;gBACD,IAAI,qBAAqB,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,uBAAuB,CAAC;oBAAE,SAAQ;gBAC/E,QAAQ,CAAC,IAAI,CACX,UAAU,CAAC;oBACT,IAAI,EAAE,SAAS;oBACf,QAAQ,EAAE,MAAM;oBAChB,IAAI,EAAE,KAAK,CAAC,IAAI;oBAChB,IAAI,EAAE,KAAK,CAAC,IAAI;oBAChB,OAAO,EAAE,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,eAAe,OAAO,kDAAkD,SAAS,gBAAgB,gBAAgB,oFAAoF,eAAe,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,sFAAsF,uBAAuB,2BAA2B;oBACvZ,QAAQ,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,YAAY,OAAO,EAAE,CAAC;oBAClE,MAAM,EAAE,0BAA0B;iBACnC,CAAC,CACH,CAAA;gBACD,MAAK,CAAC,0DAA0D;YAClE,CAAC;QACH,CAAC;QACD,OAAO,QAAQ,CAAA;IACjB,CAAC;CACF,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAc;IAC3C,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,8BAA8B;IACrC,KAAK,CAAC,IAAI,CAAC,GAAG;QACZ,MAAM,QAAQ,GAAiB,EAAE,CAAA;QACjC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAwC,CAAA;QAC9D,KAAK,MAAM,KAAK,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACpC,IAAI,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YACjC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,IAAI,GAAG,IAAI,GAAG,EAAE,CAAA;gBAChB,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;YAC9B,CAAC;YACD,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,EAAE,CAAA;YAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YAC3B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;gBACpB,SAAQ;YACV,CAAC;YACD,QAAQ,CAAC,IAAI,CACX,UAAU,CAAC;gBACT,IAAI,EAAE,SAAS;gBACf,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,OAAO,EAAE,GAAG,GAAG,oDAAoD,KAAK,CAAC,IAAI,kEAAkE;gBAC/I,QAAQ,EAAE,CAAC,GAAG,EAAE,4BAA4B,KAAK,CAAC,IAAI,EAAE,CAAC;gBACzD,MAAM,EAAE,0BAA0B;aACnC,CAAC,CACH,CAAA;QACH,CAAC;QACD,OAAO,QAAQ,CAAA;IACjB,CAAC;CACF,CAAA;AAED,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,mBAAmB,EAAE,kBAAkB,CAAC,CAAC,CAAA"}
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../../src/rules/routes.ts"],"names":[],"mappings":"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"}

package/dist/workspace-link.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Resolving a WORKSPACE-LINKED dependency back to the directory it really lives in.
+ *
+ * A workspace link is the one install whose realpath deliberately leaves the project: `link:` and
+ * `workspaces` entries point at a source checkout, routinely in a sibling repository. That is exactly
+ * what makes such a package able to go stale (its `dist/` is nobody's build step) and exactly what a
+ * project-contained path check rejects - so the rebuild has to resolve the escape on purpose, under
+ * its own rules, rather than reuse `resolveInsideProject`.
+ *
+ * The rules that keep it safe:
+ *   - the path is never taken from a diagnostic; it is re-derived from the package NAME by walking the
+ *     project's own `node_modules` chain, so only a symlink the package manager already created can be
+ *     reached, and only a package the project actually declares;
+ *   - a copy that resolves INSIDE `node_modules` is a registry tarball - immutable, never stale, and
+ *     never rebuilt;
+ *   - the package must declare the build script itself. nifra runs the project's own script, never a
+ *     command of its own composition, and never through a shell.
+ */
+export declare function isPackageName(value: string): boolean;
+/** The package's own build script name, or `undefined` when it declares none. */
+export declare function buildScriptName(meta: Record<string, unknown> | undefined): string | undefined;
+export type WorkspaceLinkResolution = {
+    readonly ok: true;
+    readonly dir: string;
+    readonly buildScript: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Resolve `name` to the workspace-linked checkout the project loads it from, refusing with a stated
+ * reason rather than resolving to nothing. The upward walk is unbounded on purpose: it has to reach the
+ * same hoisted copy the staleness scan found, which in a monorepo sits above the package being checked.
+ * It only ever inspects `node_modules/<name>` directories, so it cannot wander into an arbitrary path.
+ */
+export declare function resolveWorkspaceLinkedPackage(cwd: string, name: string): Promise<WorkspaceLinkResolution>;
+//# sourceMappingURL=workspace-link.d.ts.map

package/dist/workspace-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-link.d.ts","sourceRoot":"","sources":["../src/workspace-link.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAaH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAK7F;AAED,MAAM,MAAM,uBAAuB,GAC/B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACzE;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAEnD;;;;;GAKG;AACH,wBAAsB,6BAA6B,CACjD,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,uBAAuB,CAAC,CAwBlC"}

package/dist/workspace-link.js

@@ -0,0 +1,72 @@
+/**
+ * Resolving a WORKSPACE-LINKED dependency back to the directory it really lives in.
+ *
+ * A workspace link is the one install whose realpath deliberately leaves the project: `link:` and
+ * `workspaces` entries point at a source checkout, routinely in a sibling repository. That is exactly
+ * what makes such a package able to go stale (its `dist/` is nobody's build step) and exactly what a
+ * project-contained path check rejects - so the rebuild has to resolve the escape on purpose, under
+ * its own rules, rather than reuse `resolveInsideProject`.
+ *
+ * The rules that keep it safe:
+ *   - the path is never taken from a diagnostic; it is re-derived from the package NAME by walking the
+ *     project's own `node_modules` chain, so only a symlink the package manager already created can be
+ *     reached, and only a package the project actually declares;
+ *   - a copy that resolves INSIDE `node_modules` is a registry tarball - immutable, never stale, and
+ *     never rebuilt;
+ *   - the package must declare the build script itself. nifra runs the project's own script, never a
+ *     command of its own composition, and never through a shell.
+ */
+import { sep } from "node:path";
+import { resolvedInstalledCopy } from "@nifrajs/web/internal/parity";
+/** The one script name a rebuild will run. Guessing among `prepare`/`compile`/`build:*` would risk
+ * running something that is not the build at all; a package that names it differently is reported as
+ * un-automatable instead. */
+const BUILD_SCRIPT = "build";
+/** A package name npm would accept, with no path segment that could climb out of `node_modules`. */
+const PACKAGE_NAME = /^@?[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)?$/;
+export function isPackageName(value) {
+    return PACKAGE_NAME.test(value) && !value.split("/").some((part) => part === "." || part === "..");
+}
+/** The package's own build script name, or `undefined` when it declares none. */
+export function buildScriptName(meta) {
+    const scripts = meta?.scripts;
+    if (typeof scripts !== "object" || scripts === null)
+        return undefined;
+    const script = scripts[BUILD_SCRIPT];
+    return typeof script === "string" && script.trim().length > 0 ? BUILD_SCRIPT : undefined;
+}
+/**
+ * Resolve `name` to the workspace-linked checkout the project loads it from, refusing with a stated
+ * reason rather than resolving to nothing. The upward walk is unbounded on purpose: it has to reach the
+ * same hoisted copy the staleness scan found, which in a monorepo sits above the package being checked.
+ * It only ever inspects `node_modules/<name>` directories, so it cannot wander into an arbitrary path.
+ */
+export async function resolveWorkspaceLinkedPackage(cwd, name) {
+    if (!isPackageName(name))
+        return { ok: false, reason: `not a package name: ${name}` };
+    // Boundary "" and the `node_modules` refusal below mirror `collectStaleWorkspaceDists` exactly, so
+    // the rebuild always lands on the same copy the staleness scan flagged.
+    const copy = await resolvedInstalledCopy(cwd, "", name);
+    if (copy === undefined)
+        return { ok: false, reason: `${name} is not installed under ${cwd}` };
+    if (copy.path.includes(`${sep}node_modules${sep}`)) {
+        return {
+            ok: false,
+            reason: `${name} resolves to a registry install (${copy.path}), which cannot be stale or rebuilt`,
+        };
+    }
+    const meta = (await Bun.file(`${copy.path}${sep}package.json`)
+        .json()
+        .catch(() => undefined));
+    if (meta === undefined)
+        return { ok: false, reason: `${copy.path} has no readable package.json` };
+    const buildScript = buildScriptName(meta);
+    if (buildScript === undefined) {
+        return {
+            ok: false,
+            reason: `${name} declares no "${BUILD_SCRIPT}" script in ${copy.path}/package.json, so its artifact cannot be rebuilt automatically - build it the way that package expects`,
+        };
+    }
+    return { ok: true, dir: copy.path, buildScript };
+}
+//# sourceMappingURL=workspace-link.js.map

package/dist/workspace-link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-link.js","sourceRoot":"","sources":["../src/workspace-link.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AAC/B,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAA;AAEpE;;6BAE6B;AAC7B,MAAM,YAAY,GAAG,OAAO,CAAA;AAE5B,oGAAoG;AACpG,MAAM,YAAY,GAAG,2CAA2C,CAAA;AAEhE,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI,CAAC,CAAA;AACpG,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,eAAe,CAAC,IAAyC;IACvE,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,CAAA;IAC7B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,SAAS,CAAA;IACrE,MAAM,MAAM,GAAI,OAAmC,CAAC,YAAY,CAAC,CAAA;IACjE,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAA;AAC1F,CAAC;AAMD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,GAAW,EACX,IAAY;IAEZ,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,uBAAuB,IAAI,EAAE,EAAE,CAAA;IACrF,mGAAmG;IACnG,wEAAwE;IACxE,MAAM,IAAI,GAAG,MAAM,qBAAqB,CAAC,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,CAAA;IACvD,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,2BAA2B,GAAG,EAAE,EAAE,CAAA;IAC7F,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,GAAG,eAAe,GAAG,EAAE,CAAC,EAAE,CAAC;QACnD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,GAAG,IAAI,oCAAoC,IAAI,CAAC,IAAI,qCAAqC;SAClG,CAAA;IACH,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,GAAG,GAAG,cAAc,CAAC;SAC3D,IAAI,EAAE;SACN,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAwC,CAAA;IACjE,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,+BAA+B,EAAE,CAAA;IACjG,MAAM,WAAW,GAAG,eAAe,CAAC,IAAI,CAAC,CAAA;IACzC,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,GAAG,IAAI,iBAAiB,YAAY,eAAe,IAAI,CAAC,IAAI,wGAAwG;SAC7K,CAAA;IACH,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,CAAA;AAClD,CAAC"}

package/docs/examples.json

@@ -309,7 +309,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",