@nifrajs/cli 2.14.1 → 3.1.0

package/src/mcp.ts

@@ -104,6 +104,8 @@ function childPath(name: "mcp-run" | "mcp-render" | "mcp-ws"): string {
  * within one attention span rather than after minutes of polling.
  */
 const CHILD_TIMEOUT_MS = 30_000
+/** Maximum stdout or stderr retained from a project subprocess. The process is killed at the limit. */
+export const CHILD_OUTPUT_MAX_BYTES = 1_048_576
 
 /** Local dev-tool reads are intentionally bounded: MCP runs in an agent process and must not hang on or
  * buffer an unrelated loopback service just because a caller supplied its port. */
@@ -172,6 +174,47 @@ const timeoutMessage = (label: string, ms: number): string =>
   `that keeps the event loop alive (a database pool, a Redis client, an interval) opened during import ` +
   `rather than lazily. Check for top-level connections in the app entry or anything it imports.`
 
+export interface BoundedOutput {
+  readonly text: string
+  readonly truncated: boolean
+}
+
+/** Read child output incrementally and cancel as soon as the byte budget is crossed. */
+export async function readBoundedStream(
+  stream: ReadableStream<Uint8Array>,
+  maxBytes = CHILD_OUTPUT_MAX_BYTES,
+  onLimit?: () => void,
+): Promise<BoundedOutput> {
+  const reader = stream.getReader()
+  const decoder = new TextDecoder()
+  const chunks: string[] = []
+  let totalBytes = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) {
+        chunks.push(decoder.decode())
+        return { text: chunks.join(""), truncated: false }
+      }
+      if (value === undefined) continue
+      const remaining = maxBytes - totalBytes
+      if (remaining <= 0 || value.byteLength > remaining) {
+        if (remaining > 0) {
+          chunks.push(decoder.decode(value.subarray(0, remaining), { stream: true }))
+          chunks.push(decoder.decode())
+        }
+        await reader.cancel()
+        onLimit?.()
+        return { text: chunks.join(""), truncated: true }
+      }
+      totalBytes += value.byteLength
+      chunks.push(decoder.decode(value, { stream: true }))
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}
+
 async function spawnChild(
   child: "mcp-run" | "mcp-render" | "mcp-ws",
   cwd: string,
@@ -185,30 +228,46 @@ async function spawnChild(
     stdout: "pipe",
     stderr: "pipe",
   })
-  const abort = (): void => proc.kill()
+  let killed = false
+  const kill = (): void => {
+    if (killed) return
+    killed = true
+    proc.kill()
+  }
+  const abort = (): void => kill()
   signal?.addEventListener("abort", abort, { once: true })
   let timedOut = false
   const timer = setTimeout(() => {
     timedOut = true
-    proc.kill()
+    kill()
   }, CHILD_TIMEOUT_MS)
+  let outputExceeded = false
   try {
     proc.stdin.write(JSON.stringify(input))
     await proc.stdin.end()
     const [out, err] = await Promise.all([
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
+      readBoundedStream(proc.stdout, CHILD_OUTPUT_MAX_BYTES, () => {
+        outputExceeded = true
+        kill()
+      }),
+      readBoundedStream(proc.stderr, CHILD_OUTPUT_MAX_BYTES, () => {
+        outputExceeded = true
+        kill()
+      }),
     ])
     await proc.exited
     if (signal?.aborted) {
       const reason = typeof signal.reason === "string" ? `: ${signal.reason}` : ""
       return `${label} cancelled${reason}.`
     }
+    if (outputExceeded) {
+      return `${label} output exceeded ${CHILD_OUTPUT_MAX_BYTES} bytes and was terminated.`
+    }
     // A killed child may still have flushed a complete result before the timer fired; prefer real
     // output over the timeout message so a slow-but-successful render is not reported as a failure.
-    const text = out.trim()
+    const text = out.text.trim()
     if (timedOut && text === "") return timeoutMessage(label, CHILD_TIMEOUT_MS)
-    return text || `${label} failed:\n${err.trim() || "(no output)"}`
+    return text || `${label} failed:\n${err.text.trim() || "(no output)"}`
   } finally {
     clearTimeout(timer)
     signal?.removeEventListener("abort", abort)
@@ -345,7 +404,23 @@ export class WarmWorker {
     for (;;) {
       const { done, value } = await reader.read()
       if (done) break
+      if (value !== undefined && value.byteLength > CHILD_OUTPUT_MAX_BYTES) {
+        this.stderrBuffer = boundedAppend(
+          this.stderrBuffer,
+          `warm ${this.label} worker stdout exceeded ${CHILD_OUTPUT_MAX_BYTES} bytes\n`,
+        )
+        this.stop()
+        return
+      }
       this.stdoutBuffer += decoder.decode(value, { stream: true })
+      if (this.stdoutBuffer.length > CHILD_OUTPUT_MAX_BYTES) {
+        this.stderrBuffer = boundedAppend(
+          this.stderrBuffer,
+          `warm ${this.label} worker stdout exceeded ${CHILD_OUTPUT_MAX_BYTES} bytes\n`,
+        )
+        this.stop()
+        return
+      }
       let nl = this.stdoutBuffer.indexOf("\n")
       while (nl !== -1) {
         const line = this.stdoutBuffer.slice(0, nl).trim()

package/src/recipes/3.0.0.ts

@@ -0,0 +1,24 @@
+import type { UpgradeRecipe } from "./index.ts"
+
+/**
+ * Upgrade recipe for the Nifra 3.0 fixed-group cutover.
+ *
+ * No package is removed and no import specifier moves this release, so the runner only pins the
+ * fixed version group. The two breaking changes are structural - a redirect return value and the
+ * reserved typed-client segment types - and stay as explicit notes, one of which points at a codemod.
+ */
+export const recipe: UpgradeRecipe = {
+  version: "3.0.0",
+  pins: [
+    { match: "@nifrajs/", to: "3.0.0" },
+    { match: "create-nifra", to: "3.0.0" },
+    { match: "nifra", to: "3.0.0" },
+  ],
+  importMoves: [],
+  notes: [
+    "Read the 2.x → 3.0 migration guide: https://nifra.dev/docs/migrate-3.",
+    "`redirect(...)` now returns plain render data, not a `Response`. Read it with `.plain` (`{ status, headers, body }`) or `toResponse()`, add headers with the second argument, and assert on `.plain` in tests. `return redirect()` / `throw redirect()` are unchanged, and cookies still apply.",
+    "Reserved typed-client segment keys are a frozen contract: a property or bracket access on a reserved-named route segment no longer type-checks. Run `nifra fix --code NF-C018` to rewrite the affected call sites; `nifra routes` annotates a colliding route with the spelling that reaches it.",
+    "On Node, `@nifrajs/proxy` defaults to the undici transport. Pass an explicit `transport` to `createProxy` to override it.",
+  ],
+}

package/src/recipes/index.ts

@@ -6,6 +6,7 @@
 
 import { recipe as v1_8_0 } from "./1.8.0.ts"
 import { recipe as v2_0_0 } from "./2.0.0.ts"
+import { recipe as v3_0_0 } from "./3.0.0.ts"
 
 /** A pin rule: every dependency whose name starts with `match` is set to version `to`. */
 export interface PinRule {
@@ -40,6 +41,7 @@ export interface UpgradeRecipe {
 const RECIPES: Record<string, UpgradeRecipe> = {
   [v1_8_0.version]: v1_8_0,
   [v2_0_0.version]: v2_0_0,
+  [v3_0_0.version]: v3_0_0,
 }
 
 export function getRecipe(version: string): UpgradeRecipe | undefined {

package/src/release-verification.ts

@@ -103,6 +103,14 @@ const DEFAULT_GATES: readonly ReleaseGateSpec[] = [
     remediation:
       "Run `bun run check:size` and either reduce the bundle or update the reviewed budget.",
   },
+  // Appended, not inserted: RELEASE_GATES below composes this list BY INDEX
+  // (`slice(0, 3)`, `[3]`), so a gate added in the middle would silently re-point those.
+  {
+    id: "changesets",
+    commands: [["run", "check:changesets"]],
+    remediation:
+      "Run `bun run changeset` and name every package whose source changed, so the release documents it.",
+  },
 ]
 
 const RELEASE_GATES: readonly ReleaseGateSpec[] = [
@@ -183,6 +191,15 @@ const RELEASE_GATES: readonly ReleaseGateSpec[] = [
     remediation:
       "Run `bun run check:pipeline-parity` and fix the development and production manifest drift.",
   },
+  // Last in release mode on purpose: this is the gate on what the release SAYS, and it is the only
+  // one whose failure is invisible afterwards - a shipped version cannot grow the changelog line it
+  // never had.
+  {
+    id: "changesets",
+    commands: [["run", "check:changesets"]],
+    remediation:
+      "Run `bun run changeset` and name every package whose source changed, so the release documents it.",
+  },
 ]
 
 const runBunCommand = async (spec: ReleaseCommandSpec): Promise<ReleaseCommandResult> => {

package/src/rules/routes.ts

@@ -1,3 +1,4 @@
+import { RESERVED_KEY_READOUT, reservedKeyFor } from "@nifrajs/client"
 import { type Diagnostic, diagnostic } from "../diagnostics.ts"
 import { commentBlockHasMarker } from "./comment-markers.ts"
 import type { CheckRule, RuleContext } from "./index.ts"
@@ -7,27 +8,18 @@ import type { CheckRule, RuleContext } from "./index.ts"
  * 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: ReadonlySet<string> = 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: ReadonlySet<string> = 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"
@@ -69,14 +61,6 @@ function routeEscapeHint(path: string, colliding: string): string {
   return `${["api", ...before].join(".")}("${colliding}")`
 }
 
-/** The reserved key a static path segment collides with, or undefined. Params/wildcards never collide. */
-function reservedCollision(segment: string): string | undefined {
-  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: CheckRule = {
   code: "NF-C018",
   title: "Route segment collides with a reserved client proxy key",
@@ -86,7 +70,7 @@ export const reservedSegmentRule: CheckRule = {
     for (const route of routeFacts(ctx)) {
       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)
         if (lines === undefined) {
@@ -100,8 +84,11 @@ export const reservedSegmentRule: CheckRule = {
             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",
           }),
         )

package/src/workspace-link.ts

@@ -0,0 +1,80 @@
+/**
+ * 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: string): boolean {
+  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: Record<string, unknown> | undefined): string | undefined {
+  const scripts = meta?.scripts
+  if (typeof scripts !== "object" || scripts === null) return undefined
+  const script = (scripts as Record<string, unknown>)[BUILD_SCRIPT]
+  return typeof script === "string" && script.trim().length > 0 ? BUILD_SCRIPT : 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 async function resolveWorkspaceLinkedPackage(
+  cwd: string,
+  name: string,
+): Promise<WorkspaceLinkResolution> {
+  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)) as Record<string, unknown> | 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 }
+}