@nifrajs/cli 3.5.0 → 4.0.2

package/src/sync-manifest.ts

@@ -12,6 +12,7 @@
 
 import { join } from "node:path"
 import { Glob } from "bun"
+import { codeUnitOrder } from "./internal/code-unit-order.ts"
 
 // The marker `generateServerManifest` writes at the top of the file - so a user file merely named
 // `server-manifest.ts` is never mistaken for a generated one. Mirrors `nifra check`'s drift scan.
@@ -20,6 +21,14 @@ const GENERATED_MARKER = "GENERATED by @nifrajs/web generateServerManifest"
 // routes dir relative to the manifest and strips imports to route-relative keys.
 const ROUTES_PREFIX = /["'](\.{1,2}(?:\/[^"'/]+)*?\/routes\/)[^"']+["']/
 const IGNORED = /(^|\/)(node_modules|dist(-[a-z0-9]+)?|build|\.nifra|\.git|\.wrangler|coverage)\//
+// The fs codes that mean the routes dir is absent or unreadable. Every other throw is the route table
+// refusing to build, which must fail the command rather than read as "no manifest found".
+const ROUTES_DIR_UNAVAILABLE = new Set(["ENOENT", "ENOTDIR", "EACCES", "EPERM"])
+
+function routesDirUnavailable(error: unknown): boolean {
+  if (typeof error !== "object" || error === null || !("code" in error)) return false
+  return typeof error.code === "string" && ROUTES_DIR_UNAVAILABLE.has(error.code)
+}
 
 export interface SyncManifestResult {
   /** The committed server-manifest file (relative to cwd). */
@@ -33,12 +42,16 @@ export interface SyncManifestResult {
   /** Set when the sync was REFUSED because discovery found zero routes for a manifest that had some
    * (`routes/` likely emptied by mistake) - the manifest was left untouched rather than wiped. */
   readonly refusedEmpty?: boolean
+  /** Set when the `routes/` tree could not be built into a route table (a duplicate route, two routes of
+   * one shape sharing a path, ...) - the manifest was left untouched and the sync failed. */
+  readonly error?: string
 }
 
 /**
  * Discover every generated `server-manifest.ts` under `cwd` and re-sync its route table from the live
  * `routes/` tree, preserving baked client assets. Returns one result per generated manifest. Never throws
- * on a per-manifest miss (an unreadable/absent routes dir is skipped).
+ * on a per-manifest failure: an absent or unreadable routes dir is skipped, and a route table that fails
+ * to build is reported in that manifest's `error`.
  */
 export async function syncServerManifests(cwd: string): Promise<SyncManifestResult[]> {
   const { discoverRoutes } = await import("@nifrajs/web/fs")
@@ -59,8 +72,11 @@ export async function syncServerManifests(cwd: string): Promise<SyncManifestResu
     let next: string
     try {
       next = resyncServerManifestSource(source, discoverRoutes(routesDir), routesPrefix)
-    } catch {
-      continue // routes dir gone/unreadable - not a manifest we can sync
+    } catch (error) {
+      if (routesDirUnavailable(error)) continue // not a manifest we can sync
+      const message = error instanceof Error ? error.message : String(error)
+      results.push({ file: rel, changed: false, added: [], removed: [], error: message })
+      continue
     }
     const before = parseManifestRouteFiles(source, routesPrefix)
     const after = parseManifestRouteFiles(next, routesPrefix)
@@ -77,36 +93,51 @@ export async function syncServerManifests(cwd: string): Promise<SyncManifestResu
     const drift = diffManifestRoutes(before, after)
     results.push({ file: rel, changed, added: drift.missing, removed: drift.extra })
   }
-  return results.sort((a, b) => a.file.localeCompare(b.file))
+  return results.sort((a, b) => codeUnitOrder(a.file, b.file))
 }
 
-/** CLI entry: sync every generated manifest, print a per-file summary + the client-rebuild caveat. */
-export async function runSyncManifest(cwd: string): Promise<boolean> {
-  const results = await syncServerManifests(cwd)
-  if (results.length === 0) {
-    console.log("nifra sync-manifest: no generated server-manifest.ts found under this directory.")
-    return true
-  }
+/** True when no manifest's route table failed to build. */
+export function syncManifestsOk(results: readonly SyncManifestResult[]): boolean {
+  return results.every((r) => r.error === undefined)
+}
+
+/** Per-file summary lines + the client-rebuild caveat. */
+export function renderSyncManifestResults(results: readonly SyncManifestResult[]): string[] {
+  if (results.length === 0)
+    return ["nifra sync-manifest: no generated server-manifest.ts found under this directory."]
+  const lines: string[] = []
   let anyChanged = false
   for (const r of results) {
-    if (r.refusedEmpty) {
-      console.log(
+    if (r.error !== undefined) {
+      lines.push(
+        `✖ ${r.file}: routes/ does not build a route table; left untouched.`,
+        `    ${r.error}`,
+      )
+    } else if (r.refusedEmpty) {
+      lines.push(
         `⚠ ${r.file}: refused - routes/ has zero routes but the manifest had some; left untouched (delete the manifest yourself if this is intentional).`,
       )
     } else if (r.changed) {
       anyChanged = true
-      console.log(`✓ synced ${r.file}`)
-      if (r.added.length > 0) console.log(`    added:   ${r.added.join(", ")}`)
-      if (r.removed.length > 0) console.log(`    removed: ${r.removed.join(", ")}`)
+      lines.push(`✓ synced ${r.file}`)
+      if (r.added.length > 0) lines.push(`    added:   ${r.added.join(", ")}`)
+      if (r.removed.length > 0) lines.push(`    removed: ${r.removed.join(", ")}`)
     } else {
-      console.log(`• ${r.file} already in sync`)
+      lines.push(`• ${r.file} already in sync`)
     }
   }
   if (anyChanged) {
-    console.log(
+    lines.push(
       "\nRe-synced the server manifest's route table. If you added or changed a HYDRATING route\n" +
         "component (not just a loader / SSR-only route), also run a full build so the client bundle matches.",
     )
   }
-  return true
+  return lines
+}
+
+/** CLI entry: sync every generated manifest and print the summary. False when a route table failed to build. */
+export async function runSyncManifest(cwd: string): Promise<boolean> {
+  const results = await syncServerManifests(cwd)
+  console.log(renderSyncManifestResults(results).join("\n"))
+  return syncManifestsOk(results)
 }

package/src/sync-routes.ts

@@ -24,9 +24,10 @@ export interface SyncRoutesResult {
 }
 
 /**
- * Generate the route-search types `.d.ts` from `<cwd>/routes` (the nifra convention). Returns `null` when
- * there is no `routes/` directory (an API-only project - nothing to type). Never loads `framework.ts`: it
- * needs only the route tree, so it works before a build and on a broken framework config.
+ * Generate the route-search types `.d.ts` from `<cwd>/routes` (the nifra convention). Returns
+ * `null` when there is no `routes/` directory (an API-only project - nothing to type). Never loads
+ * `backend/framework.ts`: it needs only the route tree, so it works before a build and on a broken
+ * framework config.
  */
 export async function syncRouteTypes(cwd: string): Promise<SyncRoutesResult | null> {
   const routesDir = join(cwd, "routes")

package/src/test-tool.ts

@@ -1,3 +1,6 @@
+import { type HeadTailOutput, readHeadTail } from "./mcp-io.ts"
+import { mcpProjectPathError, resolveMcpProjectPath } from "./mcp-path.ts"
+
 export interface TestToolArgs {
   readonly pattern?: unknown
   readonly timeoutMs?: unknown
@@ -26,9 +29,11 @@ export interface TestToolResult {
 
 const DEFAULT_TIMEOUT_MS = 30_000
 const MAX_TIMEOUT_MS = 300_000
-const MAX_OUTPUT_CHARS = 12_000
+const HEAD_CHARS = 4_000
+const TAIL_CHARS = 8_000
+const MAX_OUTPUT_CHARS = HEAD_CHARS + TAIL_CHARS
 
-function normalizePattern(value: unknown): string | undefined {
+function normalizePattern(value: unknown, root: string): string | undefined {
   if (value === undefined || value === null) return undefined
   if (typeof value !== "string") throw new Error("pattern must be a string")
   const pattern = value.trim()
@@ -39,6 +44,9 @@ function normalizePattern(value: unknown): string | undefined {
   // `pattern` narrows test files; it is not a remote flag injection surface.
   if (pattern.startsWith("-"))
     throw new Error("pattern must be a file/path pattern, not a CLI flag")
+  // `bun test` runs any `./`, `../` or absolute path it is given, so a pattern stays inside the project.
+  if (resolveMcpProjectPath(root, pattern) === null)
+    throw new Error(mcpProjectPathError("pattern", pattern))
   return pattern
 }
 
@@ -52,11 +60,18 @@ function normalizeTimeout(value: unknown): number {
 
 const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, "g")
 
-function clean(text: string): string {
-  const stripped = text.replace(ANSI, "")
+// A UTF-8 character is at most four bytes, so these hold every character the result can show.
+const HEAD_BYTES = HEAD_CHARS * 4
+const TAIL_BYTES = TAIL_CHARS * 4
+
+function clean(output: HeadTailOutput): string {
+  const strip = (text: string): string => text.replace(ANSI, "")
+  if (output.droppedBytes > 0)
+    return `${strip(output.head).slice(0, HEAD_CHARS)}\n…(trimmed more than ${output.droppedBytes} bytes)…\n${strip(output.tail).slice(-TAIL_CHARS)}`
+  const stripped = strip(output.head + output.tail)
   return stripped.length <= MAX_OUTPUT_CHARS
     ? stripped
-    : `${stripped.slice(0, 4_000)}\n…(trimmed ${stripped.length - MAX_OUTPUT_CHARS} chars)…\n${stripped.slice(-8_000)}`
+    : `${stripped.slice(0, HEAD_CHARS)}\n…(trimmed ${stripped.length - MAX_OUTPUT_CHARS} chars)…\n${stripped.slice(-TAIL_CHARS)}`
 }
 
 function firstNumber(pattern: RegExp, text: string): number | undefined {
@@ -89,7 +104,7 @@ export async function collectTestResult(
   let pattern: string | undefined
   let timeoutMs: number
   try {
-    pattern = normalizePattern(args.pattern)
+    pattern = normalizePattern(args.pattern, cwd)
     timeoutMs = normalizeTimeout(args.timeoutMs)
   } catch (err) {
     return {
@@ -124,8 +139,11 @@ export async function collectTestResult(
           : "cancelled",
     }
   }
-  const proc = Bun.spawn(command, {
+  // The running Bun, not the first `bun` on PATH: an MCP client may start the server with no `bun` there.
+  const proc = Bun.spawn([process.execPath, ...command.slice(1)], {
     cwd,
+    // Explicit: without `env`, Bun passes the environment it started with, missing `--env-file` values.
+    env: process.env,
     stdout: "pipe",
     stderr: "pipe",
   })
@@ -140,13 +158,16 @@ export async function collectTestResult(
     timedOut = true
     proc.kill()
   }, timeoutMs)
-  let stdoutRaw = ""
-  let stderrRaw = ""
+  const empty: HeadTailOutput = { head: "", tail: "", droppedBytes: 0 }
+  let stdoutRaw = empty
+  let stderrRaw = empty
   let exitCode: number | null = null
   try {
+    // Drained to the end but held to what the result shows, so a test run that prints without limit
+    // cannot grow the server's memory with it.
     const result = await Promise.all([
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
+      readHeadTail(proc.stdout, HEAD_BYTES, TAIL_BYTES),
+      readHeadTail(proc.stderr, HEAD_BYTES, TAIL_BYTES),
       proc.exited,
     ])
     stdoutRaw = result[0]

package/src/types-search.ts

@@ -9,7 +9,8 @@
  * signature/doc body; no args → a per-package index of the available type names.
  */
 
-import { countBodyHits, queryTermGroups, tokenize, tokenSetHas } from "./search-terms.ts"
+import { codeUnitOrder } from "./internal/code-unit-order.ts"
+import { countBodyHits, queryTermGroups, tokenize, tokenSetScore } from "./search-terms.ts"
 
 export interface TypeEntry {
   readonly name: string
@@ -63,13 +64,19 @@ export function searchTypes(
   for (const prepared of prepareTypes(types)) {
     const t = prepared.type
     let score = 0
+    let nameTermMatches = 0
     for (const term of terms) {
-      if (tokenSetHas(prepared.nameTokens, term)) score += 8
+      const nameScore = tokenSetScore(prepared.nameTokens, term)
+      if (nameScore > 0) {
+        nameTermMatches += 1
+        score += 8 + nameScore * 4
+      }
       score += countBodyHits(prepared.bodyLower, term, 4)
     }
+    score += nameTermMatches * 4
     if (score > 0) scored.push({ ...t, score })
   }
-  return scored.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name)).slice(0, limit)
+  return scored.sort((a, b) => b.score - a.score || codeUnitOrder(a.name, b.name)).slice(0, limit)
 }
 
 function renderEntry(t: TypeEntry): string {
@@ -159,7 +166,7 @@ export function renderTypesResult(
     byPkg.set(t.package, list)
   }
   const index = [...byPkg.entries()]
-    .sort(([a], [b]) => a.localeCompare(b))
+    .sort(([a], [b]) => codeUnitOrder(a, b))
     .map(([pkg, names]) => `- **${pkg}**: ${names.sort().join(", ")}`)
     .join("\n")
   return `# nifra types - index (${types.length} exported symbols; pass \`name\` for the exact declaration, or \`query\` to search)\n\nSignatures are generated from the built \`.d.ts\` - authoritative + complete. Use this instead of reading any \`.d.ts\` file.\n\n${index}`

package/src/upgrade.ts

@@ -10,6 +10,11 @@
  *   3. **import moves** - rewrite exact import specifiers to their updated module paths.
  *   4. **verify** - reuse the existing `nifra check` gate; no new verification surface.
  *
+ * Upgrading across several releases runs every recipe between the installed version (the lowest
+ * fixed-group version the workspace declares) and the target, oldest first, then pins the target. A
+ * target newer than this CLI prints the newer CLI's command instead of guessing at recipes it does not
+ * carry; nothing is downloaded or run on the user's behalf.
+ *
  * Dry-run by default (prints the plan, writes nothing); `--write` applies. Fail-closed on an unknown
  * target version or a missing package.json, and deterministic (same repo + target → same edits).
  *
@@ -35,6 +40,10 @@ export interface UpgradeOptions {
   readonly verify?: boolean
   /** Permit a target BELOW the installed version (a rollback). Default false → fail-closed. */
   readonly allowDowngrade?: boolean
+  /** Pin the exact target (`3.6.0`), dropping the `^`/`~` a spec used. Default false → keep it. */
+  readonly exact?: boolean
+  /** The running CLI's version: the newest target it applies. Default: its newest recipe. */
+  readonly cliVersion?: string
 }
 
 export interface PinChange {
@@ -85,17 +94,28 @@ const SEMVER_SPEC =
   /^([\^~]|>=|<=|>|<|=)?\s*(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/
 
 /**
- * Rewrite a dependency version spec to `toVersion`, preserving the range operator (`^`, `~`, …).
- * Returns null when the spec is not a plain semver spec (→ skip it) or already equals the target.
+ * Rewrite a dependency version spec to `toVersion`, preserving the range operator (`^`, `~`, …), or
+ * dropping it when `exact`. Returns null when the spec is not a plain semver spec (→ skip it) or
+ * already equals the target.
  */
-export function rewriteVersionSpec(spec: string, toVersion: string): string | null {
+export function rewriteVersionSpec(spec: string, toVersion: string, exact = false): string | null {
   const match = SEMVER_SPEC.exec(spec.trim())
   if (!match) return null
-  const operator = match[1] ?? ""
+  const operator = exact ? "" : (match[1] ?? "")
   const next = `${operator}${toVersion}`
   return next === spec ? null : next
 }
 
+/** The version a plain semver spec names (`^2.4.1` → `2.4.1`), or null for any other spec. */
+export function specVersion(spec: string): string | null {
+  const match = SEMVER_SPEC.exec(spec.trim())
+  if (!match) return null
+  return `${match[2]}.${match[3]}.${match[4]}${match[5] === undefined ? "" : `-${match[5]}`}`
+}
+
+// A release target: a bare version, never a range, so it can be pinned and printed in a command.
+const RELEASE_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/
+
 /** 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())
@@ -168,6 +188,7 @@ export function pinSweepText(
   text: string,
   rules: readonly { match: string; to: string }[],
   allowDowngrade = false,
+  exact = false,
 ): {
   text: string
   changes: Array<Omit<PinChange, "file">>
@@ -191,7 +212,7 @@ export function pinSweepText(
         (r) => name === r.match || (r.match.endsWith("/") && name.startsWith(r.match)),
       )
       if (!rule) continue
-      const next = rewriteVersionSpec(rawSpec, rule.to)
+      const next = rewriteVersionSpec(rawSpec, rule.to, exact)
       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.
@@ -270,12 +291,12 @@ function rewriteDependencyEntry(
     let start = match.index
     let end = match.index + match[0].length
     let after = end
-    while (/\\s/.test(body[after] ?? "")) after++
+    while (/\s/.test(body[after] ?? "")) after++
     if (body[after] === ",") {
       end = after + 1
     } else {
       let before = start - 1
-      while (before >= 0 && /\\s/.test(body[before] ?? "")) before--
+      while (before >= 0 && /\s/.test(body[before] ?? "")) before--
       if (body[before] === ",") start = before
     }
     nextBody = body.slice(0, start) + body.slice(end)
@@ -287,6 +308,7 @@ function rewriteDependencyEntry(
 export function moveDependenciesText(
   text: string,
   moves: readonly { from: string; to: string; toVersion: string }[],
+  exact = false,
 ): { text: string; changes: Array<Omit<DependencyMoveChange, "file">> } {
   let out = text
   const changes: Array<Omit<DependencyMoveChange, "file">> = []
@@ -304,7 +326,7 @@ export function moveDependenciesText(
       if (!Object.hasOwn(dependencyMap, move.from)) continue
       const fromVersion = dependencyMap[move.from]
       if (typeof fromVersion !== "string") continue
-      const movedVersion = rewriteVersionSpec(fromVersion, move.toVersion) ?? fromVersion
+      const movedVersion = rewriteVersionSpec(fromVersion, move.toVersion, exact) ?? fromVersion
       // Dependency fields have different install semantics. A devDependency does not satisfy a runtime
       // dependency, so only deduplicate the successor inside the same field.
       const targetExists = Object.hasOwn(dependencyMap, move.to)
@@ -329,6 +351,12 @@ export function moveDependenciesText(
       })
     }
   }
+  // The edit is textual; a result that no longer parses is never written.
+  try {
+    JSON.parse(out)
+  } catch {
+    return { text, changes: [] }
+  }
   return { text: out, changes }
 }
 
@@ -358,10 +386,15 @@ export function applyImportMoves(
 }
 
 const SOURCE_GLOB = "**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"
-const IGNORE_SEGMENTS = ["node_modules/", "/dist/", "/build/", "/.git/", "/coverage/", "/.next/"]
+const IGNORED_DIRECTORIES = new Set(["node_modules", "dist", "build", ".git", "coverage", ".next"])
 
+// Any directory on the path counts, the top-level one included (`dist/index.js`). Bun's glob yields
+// `dist\index.js` on Windows.
 const isIgnored = (path: string): boolean =>
-  path.startsWith("node_modules/") || IGNORE_SEGMENTS.some((seg) => path.includes(seg))
+  path
+    .split(/[\\/]/)
+    .slice(0, -1)
+    .some((segment) => IGNORED_DIRECTORIES.has(segment))
 
 function scan(cwd: string, pattern: string): string[] {
   const glob = new Glob(pattern)
@@ -372,12 +405,89 @@ function scan(cwd: string, pattern: string): string[] {
   return out.sort() // deterministic order
 }
 
+// The fixed version group: every package released together at one version.
+const isFixedGroup = (name: string): boolean =>
+  name.startsWith("@nifrajs/") || name === "nifra" || name === "create-nifra"
+
+const groupPins = (version: string): UpgradeRecipe["pins"] => [
+  { match: "@nifrajs/", to: version },
+  { match: "create-nifra", to: version },
+  { match: "nifra", to: version },
+]
+
+/**
+ * The lowest fixed-group version any package.json under `cwd` declares with a plain semver spec, or
+ * null when none does. Recipes newer than it still have edits to make somewhere in the workspace.
+ */
+export function installedGroupVersion(cwd: string): string | null {
+  let lowest: string | null = null
+  for (const rel of scan(cwd, "**/package.json")) {
+    let parsed: Record<string, unknown>
+    try {
+      parsed = JSON.parse(readFileSync(join(cwd, rel), "utf8")) as Record<string, unknown>
+    } catch {
+      continue
+    }
+    for (const field of DEP_FIELDS) {
+      const deps = parsed[field]
+      if (typeof deps !== "object" || deps === null) continue
+      for (const [name, spec] of Object.entries(deps as Record<string, unknown>)) {
+        if (!isFixedGroup(name) || typeof spec !== "string") continue
+        const version = specVersion(spec)
+        if (version !== null && (lowest === null || compareSemverSpec(version, lowest) < 0)) {
+          lowest = version
+        }
+      }
+    }
+  }
+  return lowest
+}
+
+/** One recipe that applies every release recipe after `installed` up to `target`, oldest first. */
+export interface ChainedRecipe extends UpgradeRecipe {
+  /** The release recipes it applies, oldest first. */
+  readonly steps: readonly string[]
+}
+
+/**
+ * Chain the recipes after `installed` (exclusive) up to `target` (inclusive): their dependency and
+ * import moves in release order, their notes labeled by release, and the fixed group pinned to
+ * `target`. Without a known installed version only the target's own recipe applies.
+ */
+export function chainRecipes(target: string, installed: string | null): ChainedRecipe {
+  const steps =
+    installed === null
+      ? getRecipe(target) === undefined
+        ? []
+        : [target]
+      : listRecipeVersions().filter(
+          (version) =>
+            compareSemverSpec(version, installed) > 0 && compareSemverSpec(version, target) <= 0,
+        )
+  const recipes = steps.flatMap((version) => getRecipe(version) ?? [])
+  // A later rule for the same match replaces an earlier one; the target's pins win last.
+  const pins = new Map<string, string>()
+  for (const recipe of recipes) for (const rule of recipe.pins) pins.set(rule.match, rule.to)
+  for (const rule of getRecipe(target)?.pins ?? groupPins(target)) pins.set(rule.match, rule.to)
+  return {
+    version: target,
+    steps,
+    pins: [...pins].map(([match, to]) => ({ match, to })),
+    dependencyMoves: recipes.flatMap((recipe) => recipe.dependencyMoves ?? []),
+    importMoves: recipes.flatMap((recipe) => recipe.importMoves),
+    notes: recipes.flatMap((recipe) =>
+      (recipe.notes ?? []).map((note) => `${recipe.version}: ${note}`),
+    ),
+  }
+}
+
 /** Compute the plan (and, when `write`, apply it) for a target recipe against `cwd`. */
 export function computeUpgrade(
   cwd: string,
   recipe: UpgradeRecipe,
   write: boolean,
   allowDowngrade = false,
+  exact = false,
 ): UpgradePlan {
   const pins: PinChange[] = []
   const dependencyMoves: DependencyMoveChange[] = []
@@ -388,9 +498,9 @@ export function computeUpgrade(
     for (const rel of scan(cwd, "**/package.json")) {
       const abs = join(cwd, rel)
       const original = readFileSync(abs, "utf8")
-      const moved = moveDependenciesText(original, recipe.dependencyMoves ?? [])
+      const moved = moveDependenciesText(original, recipe.dependencyMoves ?? [], exact)
       for (const change of moved.changes) dependencyMoves.push({ file: rel, ...change })
-      const pinned = pinSweepText(moved.text, recipe.pins, allowDowngrade)
+      const pinned = pinSweepText(moved.text, recipe.pins, allowDowngrade, exact)
       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)
@@ -418,10 +528,22 @@ export function computeUpgrade(
   }
 }
 
-function renderPlan(plan: UpgradePlan, write: boolean): string {
+function renderPlan(
+  plan: UpgradePlan,
+  write: boolean,
+  from: string | null,
+  steps: readonly string[],
+): string {
   const lines: string[] = []
   const verb = write ? "Applied" : "Planned"
   lines.push(`nifra upgrade → ${plan.version}  (${write ? "write" : "dry-run"})`)
+  if (from !== null) {
+    lines.push(
+      steps.length === 0
+        ? `From ${from}; no release recipe in between.`
+        : `From ${from}, applying the ${steps.join(", ")} recipe${steps.length === 1 ? "" : "s"}.`,
+    )
+  }
   lines.push("")
   if (
     plan.pins.length === 0 &&
@@ -471,24 +593,73 @@ function renderDowngradeRefusal(version: string, downgrades: readonly PinChange[
   ].join("\n")
 }
 
+/** The targets this CLI applies: each release recipe up to its own version, and that version. */
+export function upgradeTargets(cliVersion: string): string[] {
+  const versions = listRecipeVersions().filter(
+    (version) => compareSemverSpec(version, cliVersion) <= 0,
+  )
+  if (!versions.includes(cliVersion)) versions.push(cliVersion)
+  return versions.sort(compareSemverSpec)
+}
+
+/** The command that runs `version`'s own CLI with the same flags. `version` is a validated release. */
+function newerCliCommand(version: string, options: UpgradeOptions): string {
+  const flags = [
+    options.write === true ? "--write" : "",
+    options.exact === true ? "--exact" : "",
+    options.allowDowngrade === true ? "--allow-downgrade" : "",
+    options.verify === false ? "--no-verify" : "",
+    options.json === true ? "--json" : "",
+  ].filter((flag) => flag !== "")
+  return ["bunx", `@nifrajs/cli@${version}`, "upgrade", version, ...flags].join(" ")
+}
+
 /** 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> {
+  const cliVersion = options.cliVersion ?? listRecipeVersions().at(-1) ?? "0.0.0"
+  const targets = upgradeTargets(cliVersion)
   if (options.list) {
-    const versions = listRecipeVersions()
-    if (options.json) console.log(JSON.stringify({ versions }, null, 2))
-    else console.log(`available upgrade targets:\n${versions.map((v) => `  ${v}`).join("\n")}`)
+    if (options.json) console.log(JSON.stringify({ versions: targets, cliVersion }, null, 2))
+    else {
+      console.log(
+        `available upgrade targets:\n${targets.map((v) => `  ${v}`).join("\n")}\n\n` +
+          `A newer release upgrades with its own CLI: bunx @nifrajs/cli@<version> upgrade <version>`,
+      )
+    }
     return true
   }
 
   const { version } = options
   if (version === undefined) {
-    console.error("[nifra] upgrade needs a target version, e.g. `nifra upgrade 1.8.0` (or --list)")
+    console.error(
+      `[nifra] upgrade needs a target version, e.g. \`nifra upgrade ${cliVersion}\` (or --list)`,
+    )
+    return false
+  }
+  if (!RELEASE_VERSION.test(version)) {
+    console.error(`[nifra] ${JSON.stringify(version)} is not a release version, e.g. ${cliVersion}`)
+    return false
+  }
+  if (compareSemverSpec(version, cliVersion) > 0) {
+    // Recipes ship with the CLI: only the target release's CLI knows every recipe up to it. Print its
+    // command rather than downloading and running code on the user's behalf.
+    const command = newerCliCommand(version, options)
+    if (options.json) {
+      console.log(
+        JSON.stringify({ version, cliVersion, refused: "newer-than-cli", command }, null, 2),
+      )
+    } else {
+      console.error(
+        `nifra upgrade → ${version}: this CLI is ${cliVersion} and carries the recipes up to it.\n` +
+          `Run the ${version} CLI, which carries every recipe up to ${version}:\n\n  ${command}`,
+      )
+    }
     return false
   }
-  const recipe = getRecipe(version)
-  if (!recipe) {
+  if (!targets.includes(version)) {
     console.error(
-      `[nifra] no upgrade recipe for ${version}. Available: ${listRecipeVersions().join(", ") || "(none)"}`,
+      `[nifra] no upgrade recipe for ${version}. This CLI upgrades to: ${targets.join(", ")}. ` +
+        `For ${version} itself, run: ${newerCliCommand(version, options)}`,
     )
     return false
   }
@@ -505,24 +676,33 @@ export async function runUpgrade(cwd: string, options: UpgradeOptions): Promise<
 
   const write = options.write === true
   const allowDowngrade = options.allowDowngrade === true
+  const exact = options.exact === true
+  const from = installedGroupVersion(cwd)
+  const recipe = chainRecipes(version, from)
 
   // 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)
+  const preview = computeUpgrade(cwd, recipe, false, allowDowngrade, exact)
   if (preview.downgrades.length > 0) {
     if (options.json) {
-      console.log(JSON.stringify({ ...preview, write: false, refused: "downgrade" }, null, 2))
+      console.log(
+        JSON.stringify(
+          { ...preview, from, steps: recipe.steps, 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
+  const plan = write ? computeUpgrade(cwd, recipe, true, allowDowngrade, exact) : preview
 
   if (options.json) {
-    console.log(JSON.stringify({ ...plan, write }, null, 2))
+    console.log(JSON.stringify({ ...plan, from, steps: recipe.steps, write }, null, 2))
   } else {
-    console.log(renderPlan(plan, write))
+    console.log(renderPlan(plan, write, from, recipe.steps))
   }
 
   // Verify only makes sense once edits are on disk. Default on after --write; opt out with --no-verify.