@nifrajs/cli 2.3.0 → 2.5.0

package/src/mcp.ts

@@ -12,12 +12,18 @@
  *   - `nifra_docs`    - keyword-search the framework docs; returns only the matching sections.
  *   - `nifra_example` - a verified, copy-pasteable snippet for a task (typechecked against the live API,
  *     so it can't hallucinate a drifted nifra API).
+ *   - `nifra_learn`   - the guided, ordered path to build a nifra app end to end (create → deploy), each
+ *     step naming the tool that emits the correct artifact and how to verify it.
  *   - `nifra_scaffold`- map a URL path to the correct `routes/` file + a contract-correct page stub.
  *   - `nifra_check`   - the drift gate (typecheck + lints, each with a structured fix), for an agent to fix against.
  *   - `nifra_assure`  - route classification + enforcement-evidence gate.
  *   - `nifra_levels`  - the cumulative verification ladder (L0 contract → L4 invariants): what the
  *     project actually proves, and why each level it misses does not hold.
  *   - `nifra_doctor`  - package.json dependency drift detector, with safe local-version auto-fix.
+ *   - `nifra_explain` - resolve an error (pasted, or the dev server's last) into a structured
+ *     diagnostic: stable code, a codeframe in the user's source, and the recognised cause + fix.
+ *   - `nifra_inspect` - read the running dev server's recent request traces (method/path/status/
+ *     duration/ISR) from the DevTools plugin: what your requests ACTUALLY did, not a guess.
  *
  * Wire it into a client (e.g. Claude Desktop / Cursor) as: command `nifra`, args `["mcp"]`, run in the
  * project root. The protocol is hand-rolled (newline-delimited JSON-RPC 2.0 over stdio), including
@@ -75,6 +81,67 @@ function childPath(name: "mcp-run" | "mcp-render" | "mcp-ws"): string {
  */
 const CHILD_TIMEOUT_MS = 30_000
 
+/** 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. */
+export const LOCAL_TOOL_FETCH_TIMEOUT_MS = 2_000
+export const LOCAL_TOOL_MAX_RESPONSE_BYTES = 1_048_576
+
+/** Accept only a concrete TCP port. Port 0 (bind-any-free-port) is not a valid read target. */
+export function validateLocalPort(port: unknown): number | undefined {
+  return typeof port === "number" && Number.isInteger(port) && port >= 1 && port <= 65_535
+    ? port
+    : undefined
+}
+
+/** Read a dev-tool response without allowing an untrusted localhost service to allocate unbounded memory. */
+export async function readBoundedResponse(
+  response: Response,
+  maxBytes = LOCAL_TOOL_MAX_RESPONSE_BYTES,
+): Promise<string> {
+  const declared = response.headers.get("content-length")
+  if (declared !== null) {
+    const length = Number(declared)
+    if (Number.isFinite(length) && length > maxBytes)
+      throw new Error("response exceeded the size limit")
+  }
+  if (response.body === null) return ""
+  const reader = response.body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      if (value === undefined) continue
+      total += value.byteLength
+      if (total > maxBytes) {
+        await reader.cancel()
+        throw new Error("response exceeded the size limit")
+      }
+      chunks.push(value)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+  const bytes = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return new TextDecoder().decode(bytes)
+}
+
+const notNifraResponse = (service: string): string =>
+  JSON.stringify(
+    {
+      code: "NIFRA_NOT_DEV_SERVER",
+      message: `The service on this port is not a Nifra ${service} endpoint.`,
+    },
+    null,
+    2,
+  )
+
 const timeoutMessage = (label: string, ms: number): string =>
   `${label} timed out after ${ms / 1000}s and was terminated.\n` +
   `The app was loaded but the process did not finish. Most often this is a module-level side effect ` +
@@ -668,6 +735,176 @@ export function projectTools(
         return describeProject(await loadAppCached(), filter)
       },
     },
+    {
+      name: "nifra_explain",
+      description:
+        "Turn a nifra error into a STRUCTURED diagnostic instead of eyeballing a stack trace: a stable `code`, the top frame in YOUR source, a codeframe around the offending line, and - when nifra recognises the failure - the plain-language `cause` + `fix` + docs anchor. Pass `error` (and `stack` if you have it, e.g. from nifra_run/nifra_test output or a failing build) to explain a specific failure; or pass `port` to fetch the running dev server's most recent SSR failure from `/__nifra/last-error`. Returns the same JSON the dev overlay renders.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          error: {
+            type: "string",
+            description:
+              "The error message to explain (copy it from nifra_run/nifra_test output or a failing build).",
+          },
+          stack: {
+            type: "string",
+            description:
+              "The error's stack trace, if you have it - enables the source codeframe and the top user frame.",
+          },
+          name: {
+            type: "string",
+            description:
+              "The error's class name (e.g. TypeError, SchemaError), if known - sharpens classification.",
+          },
+          port: {
+            type: "number",
+            description:
+              "Instead of a pasted error, fetch the running dev server's most recent SSR failure from this port.",
+          },
+        },
+        additionalProperties: false,
+      },
+      handler: async (args) => {
+        const { error, stack, name, port } = args as {
+          error?: string
+          stack?: string
+          name?: string
+          port?: number
+        }
+        if (error !== undefined || stack !== undefined) {
+          const { buildDiagnostic } = await import("@nifrajs/web/diagnostic")
+          const e = new Error(error ?? "")
+          if (name !== undefined) e.name = name
+          if (stack !== undefined) e.stack = stack
+          return JSON.stringify(buildDiagnostic(e, { root: cwd }), null, 2)
+        }
+        if (port !== undefined) {
+          const validPort = validateLocalPort(port)
+          if (validPort === undefined) {
+            return JSON.stringify(
+              { code: "NIFRA_INVALID_PORT", message: "port must be an integer from 1 to 65535." },
+              null,
+              2,
+            )
+          }
+          const { LAST_ERROR_PATH } = await import("@nifrajs/web/diagnostic")
+          try {
+            const res = await fetch(`http://127.0.0.1:${validPort}${LAST_ERROR_PATH}`, {
+              signal: AbortSignal.timeout(LOCAL_TOOL_FETCH_TIMEOUT_MS),
+            })
+            if (res.headers.get("x-nifra-diagnostic") !== "true")
+              return notNifraResponse("diagnostic")
+            if (!res.ok) {
+              return JSON.stringify(
+                {
+                  code: "NIFRA_NONE",
+                  message: `dev server at :${validPort} returned ${res.status}`,
+                },
+                null,
+                2,
+              )
+            }
+            return await readBoundedResponse(res)
+          } catch (cause) {
+            return JSON.stringify(
+              {
+                code: "NIFRA_NONE",
+                message: `could not reach a nifra dev server at :${validPort} - ${cause instanceof Error ? cause.message : String(cause)}`,
+              },
+              null,
+              2,
+            )
+          }
+        }
+        return JSON.stringify(
+          {
+            code: "NIFRA_NONE",
+            message:
+              "Pass `error` (and `stack` if available) to explain a failure, or `port` to fetch the dev server's last error.",
+          },
+          null,
+          2,
+        )
+      },
+    },
+    {
+      name: "nifra_inspect",
+      description:
+        "Observe what your requests ACTUALLY did on the running dev server - the recent request traces the DevTools plugin records: `{ method, path, status, durationMs, isrStatus, bodyBytes }` per request. The read no other tool gives you: after nifra_run or a real browser request, call this to SEE the outcome (which route answered, the status, how long, ISR hit/miss) instead of guessing. Pass `port` (the running dev server); narrow with `path` (a path prefix) or `limit` (most recent N). Requires the app to mount `@nifrajs/web`'s `devtools()` plugin (which auto-enables in development).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          port: { type: "number", description: "The running dev server's port." },
+          path: { type: "string", description: "Only traces whose path starts with this prefix." },
+          limit: { type: "number", description: "Return only the most recent N traces." },
+        },
+        required: ["port"],
+        additionalProperties: false,
+      },
+      handler: async (args) => {
+        const { port, path, limit } = args as { port?: number; path?: string; limit?: number }
+        if (port === undefined) {
+          return JSON.stringify(
+            {
+              events: [],
+              note: "Pass `port` - the running dev server whose request traces to read.",
+            },
+            null,
+            2,
+          )
+        }
+        try {
+          const validPort = validateLocalPort(port)
+          if (validPort === undefined) {
+            return JSON.stringify(
+              {
+                events: [],
+                code: "NIFRA_INVALID_PORT",
+                note: "port must be an integer from 1 to 65535.",
+              },
+              null,
+              2,
+            )
+          }
+          const url = new URL(`http://127.0.0.1:${validPort}/_nifra/devtools/state`)
+          if (path !== undefined) url.searchParams.set("path", path)
+          if (limit !== undefined) url.searchParams.set("limit", String(limit))
+          const res = await fetch(url, {
+            signal: AbortSignal.timeout(LOCAL_TOOL_FETCH_TIMEOUT_MS),
+          })
+          if (res.headers.get("x-nifra-devtools") !== "true") return notNifraResponse("DevTools")
+          if (res.status === 404) {
+            return JSON.stringify(
+              {
+                events: [],
+                note: "No DevTools endpoint on that server. Mount `devtools()` from @nifrajs/web and run in development.",
+              },
+              null,
+              2,
+            )
+          }
+          if (!res.ok) {
+            return JSON.stringify(
+              { events: [], note: `DevTools state returned ${res.status}.` },
+              null,
+              2,
+            )
+          }
+          return await readBoundedResponse(res)
+        } catch (cause) {
+          const validPort = validateLocalPort(port)
+          return JSON.stringify(
+            {
+              events: [],
+              note: `Could not reach a dev server at :${validPort ?? String(port)} - ${cause instanceof Error ? cause.message : String(cause)}`,
+            },
+            null,
+            2,
+          )
+        }
+      },
+    },
     {
       name: "nifra_routes",
       description:

package/src/upgrade.ts

@@ -33,6 +33,8 @@ export interface UpgradeOptions {
   readonly list?: boolean
   /** After `--write`, run `nifra check` and fail the command if it fails. Default true. */
   readonly verify?: boolean
+  /** Permit a target BELOW the installed version (a rollback). Default false → fail-closed. */
+  readonly allowDowngrade?: boolean
 }
 
 export interface PinChange {
@@ -65,6 +67,8 @@ export interface UpgradePlan {
   readonly pins: readonly PinChange[]
   readonly dependencyMoves: readonly DependencyMoveChange[]
   readonly importMoves: readonly ImportChange[]
+  /** Pins refused because the target is BELOW the installed version (a rollback). Empty when allowed. */
+  readonly downgrades: readonly PinChange[]
   readonly notes: readonly string[]
 }
 
@@ -78,7 +82,7 @@ const DEP_FIELDS = [
 // Only a bare semver spec is rewritten. Anything else - workspace:*, link:/file:, npm: aliases, git
 // urls, "*", "latest", or a multi-part range - is intentionally left untouched (skipped, not guessed).
 const SEMVER_SPEC =
-  /^([\^~]|>=|<=|>|<|=)?\s*(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
+  /^([\^~]|>=|<=|>|<|=)?\s*(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/
 
 /**
  * Rewrite a dependency version spec to `toVersion`, preserving the range operator (`^`, `~`, …).
@@ -92,6 +96,67 @@ export function rewriteVersionSpec(spec: string, toVersion: string): string | nu
   return next === spec ? null : next
 }
 
+/** Numeric core (major, minor, patch) of a semver spec, ignoring the range operator + prerelease/build. */
+export function specVersionTuple(spec: string): readonly [number, number, number] | null {
+  const match = SEMVER_SPEC.exec(spec.trim())
+  if (!match) return null
+  return [Number(match[2]), Number(match[3]), Number(match[4])]
+}
+
+interface ParsedSpecVersion {
+  readonly core: readonly [number, number, number]
+  readonly prerelease: readonly (number | string)[]
+}
+
+function parseSpecVersion(spec: string): ParsedSpecVersion | null {
+  const match = SEMVER_SPEC.exec(spec.trim())
+  if (!match) return null
+  const prerelease = (match[5] ?? "").split(".")
+  return {
+    core: [Number(match[2]), Number(match[3]), Number(match[4])],
+    prerelease:
+      match[5] === undefined
+        ? []
+        : prerelease.map((part) => (/^\d+$/.test(part) ? Number(part) : part)),
+  }
+}
+
+/** Compare two semver cores: <0 when a<b, 0 equal, >0 when a>b. */
+export function compareSemverCore(
+  a: readonly [number, number, number],
+  b: readonly [number, number, number],
+): number {
+  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2]
+}
+
+/** Compare full semver precedence, including prereleases (`2.3.0-beta` < `2.3.0`). */
+export function compareSemverSpec(a: string, b: string): number {
+  const left = parseSpecVersion(a)
+  const right = parseSpecVersion(b)
+  if (left === null || right === null) return 0
+  const core = compareSemverCore(left.core, right.core)
+  if (core !== 0) return core
+  if (left.prerelease.length === 0 || right.prerelease.length === 0) {
+    return left.prerelease.length === right.prerelease.length
+      ? 0
+      : left.prerelease.length === 0
+        ? 1
+        : -1
+  }
+  const length = Math.max(left.prerelease.length, right.prerelease.length)
+  for (let i = 0; i < length; i++) {
+    const x = left.prerelease[i]
+    const y = right.prerelease[i]
+    if (x === undefined || y === undefined) return x === undefined ? -1 : 1
+    if (typeof x === "number" && typeof y === "number") {
+      if (x !== y) return x - y
+    } else if (typeof x === "number") return -1
+    else if (typeof y === "number") return 1
+    else if (x !== y) return x < y ? -1 : 1
+  }
+  return 0
+}
+
 const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
 
 /**
@@ -102,15 +167,21 @@ const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\
 export function pinSweepText(
   text: string,
   rules: readonly { match: string; to: string }[],
-): { text: string; changes: Array<Omit<PinChange, "file">> } {
+  allowDowngrade = false,
+): {
+  text: string
+  changes: Array<Omit<PinChange, "file">>
+  downgrades: Array<Omit<PinChange, "file">>
+} {
   let parsed: Record<string, unknown>
   try {
     parsed = JSON.parse(text) as Record<string, unknown>
   } catch {
-    return { text, changes: [] }
+    return { text, changes: [], downgrades: [] }
   }
   let out = text
   const changes: Array<Omit<PinChange, "file">> = []
+  const downgrades: Array<Omit<PinChange, "file">> = []
   for (const field of DEP_FIELDS) {
     const deps = parsed[field]
     if (typeof deps !== "object" || deps === null) continue
@@ -122,6 +193,19 @@ export function pinSweepText(
       if (!rule) continue
       const next = rewriteVersionSpec(rawSpec, rule.to)
       if (next === null) continue
+      // Refuse a rollback: `upgrade <version>` pins an exact target, so an OLD target on a newer install
+      // walks dependencies backward (e.g. ^2.3.0 → ^2.0.0) and can break a shared-package peer range.
+      const current = specVersionTuple(rawSpec)
+      const target = specVersionTuple(rule.to)
+      if (
+        !allowDowngrade &&
+        current !== null &&
+        target !== null &&
+        compareSemverSpec(rawSpec, rule.to) > 0
+      ) {
+        downgrades.push({ field, name, from: rawSpec, to: next })
+        continue
+      }
       // Replace exactly `"name"<ws>:<ws>"spec"`, preserving the surrounding whitespace.
       const pattern = new RegExp(`("${escapeRegExp(name)}"\\s*:\\s*")${escapeRegExp(rawSpec)}(")`)
       const replaced = out.replace(pattern, `$1${next}$2`)
@@ -131,7 +215,7 @@ export function pinSweepText(
       }
     }
   }
-  return { text: out, changes }
+  return { text: out, changes, downgrades }
 }
 
 function dependencyObjectRange(
@@ -289,10 +373,16 @@ function scan(cwd: string, pattern: string): string[] {
 }
 
 /** Compute the plan (and, when `write`, apply it) for a target recipe against `cwd`. */
-export function computeUpgrade(cwd: string, recipe: UpgradeRecipe, write: boolean): UpgradePlan {
+export function computeUpgrade(
+  cwd: string,
+  recipe: UpgradeRecipe,
+  write: boolean,
+  allowDowngrade = false,
+): UpgradePlan {
   const pins: PinChange[] = []
   const dependencyMoves: DependencyMoveChange[] = []
   const importMoves: ImportChange[] = []
+  const downgrades: PinChange[] = []
 
   if ((recipe.dependencyMoves?.length ?? 0) > 0 || recipe.pins.length > 0) {
     for (const rel of scan(cwd, "**/package.json")) {
@@ -300,8 +390,9 @@ export function computeUpgrade(cwd: string, recipe: UpgradeRecipe, write: boolea
       const original = readFileSync(abs, "utf8")
       const moved = moveDependenciesText(original, recipe.dependencyMoves ?? [])
       for (const change of moved.changes) dependencyMoves.push({ file: rel, ...change })
-      const pinned = pinSweepText(moved.text, recipe.pins)
+      const pinned = pinSweepText(moved.text, recipe.pins, allowDowngrade)
       for (const change of pinned.changes) pins.push({ file: rel, ...change })
+      for (const d of pinned.downgrades) downgrades.push({ file: rel, ...d })
       if (write && pinned.text !== original) writeFileSync(abs, pinned.text)
     }
   }
@@ -322,6 +413,7 @@ export function computeUpgrade(cwd: string, recipe: UpgradeRecipe, write: boolea
     pins,
     dependencyMoves,
     importMoves,
+    downgrades,
     notes: recipe.notes ?? [],
   }
 }
@@ -366,6 +458,19 @@ function renderPlan(plan: UpgradePlan, write: boolean): string {
   return lines.join("\n").trimEnd()
 }
 
+/** Explain a refused rollback: which pins would roll back, why it's blocked, and the escape hatch. */
+function renderDowngradeRefusal(version: string, downgrades: readonly PinChange[]): string {
+  return [
+    `nifra upgrade → ${version}: refusing to DOWNGRADE ${downgrades.length} pin(s) below what's installed.`,
+    "",
+    ...downgrades.map((d) => `  ${d.file}  ${d.name}: ${d.from} → ${d.to}  (would roll back)`),
+    "",
+    "`nifra upgrade <version>` sets each pin to exactly <version>; an older target on a newer install",
+    "rolls dependencies backward and can violate a shared-package peer range. Target a version >= the",
+    "installed one, or pass --allow-downgrade if the rollback is intended.",
+  ].join("\n")
+}
+
 /** CLI entry. Returns false (→ non-zero exit) on an unknown version, no project, or a failed verify. */
 export async function runUpgrade(cwd: string, options: UpgradeOptions): Promise<boolean> {
   if (options.list) {
@@ -399,7 +504,20 @@ export async function runUpgrade(cwd: string, options: UpgradeOptions): Promise<
   }
 
   const write = options.write === true
-  const plan = computeUpgrade(cwd, recipe, write)
+  const allowDowngrade = options.allowDowngrade === true
+
+  // Fail-closed on rollback: a dry pass writes nothing, so we can refuse before any package.json is touched.
+  const preview = computeUpgrade(cwd, recipe, false, allowDowngrade)
+  if (preview.downgrades.length > 0) {
+    if (options.json) {
+      console.log(JSON.stringify({ ...preview, write: false, refused: "downgrade" }, null, 2))
+    } else {
+      console.error(renderDowngradeRefusal(recipe.version, preview.downgrades))
+    }
+    return false
+  }
+
+  const plan = write ? computeUpgrade(cwd, recipe, true, allowDowngrade) : preview
 
   if (options.json) {
     console.log(JSON.stringify({ ...plan, write }, null, 2))