@nifrajs/cli 3.3.0 → 4.0.0

package/dist/test-tool.js

@@ -1,7 +1,11 @@
+import { readHeadTail } from "./mcp-io.js";
+import { mcpProjectPathError, resolveMcpProjectPath } from "./mcp-path.js";
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_TIMEOUT_MS = 300_000;
-const MAX_OUTPUT_CHARS = 12_000;
-function normalizePattern(value) {
+const HEAD_CHARS = 4_000;
+const TAIL_CHARS = 8_000;
+const MAX_OUTPUT_CHARS = HEAD_CHARS + TAIL_CHARS;
+function normalizePattern(value, root) {
     if (value === undefined || value === null)
         return undefined;
     if (typeof value !== "string")
@@ -17,6 +21,9 @@ function normalizePattern(value) {
     // `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;
 }
 function normalizeTimeout(value) {
@@ -28,11 +35,17 @@ function normalizeTimeout(value) {
     return Math.min(Math.max(Math.trunc(value), 1_000), MAX_TIMEOUT_MS);
 }
 const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, "g");
-function clean(text) {
-    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) {
+    const strip = (text) => 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, text) {
     const match = pattern.exec(text);
@@ -58,7 +71,7 @@ export async function collectTestResult(cwd, args = {}, opts = {}) {
     let pattern;
     let timeoutMs;
     try {
-        pattern = normalizePattern(args.pattern);
+        pattern = normalizePattern(args.pattern, cwd);
         timeoutMs = normalizeTimeout(args.timeoutMs);
     }
     catch (err) {
@@ -92,8 +105,11 @@ export async function collectTestResult(cwd, args = {}, opts = {}) {
                 : "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",
     });
@@ -108,13 +124,16 @@ export async function collectTestResult(cwd, args = {}, opts = {}) {
         timedOut = true;
         proc.kill();
     }, timeoutMs);
-    let stdoutRaw = "";
-    let stderrRaw = "";
+    const empty = { head: "", tail: "", droppedBytes: 0 };
+    let stdoutRaw = empty;
+    let stderrRaw = empty;
     let exitCode = 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/dist/test-tool.js.map

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

package/dist/types-search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types-search.d.ts","sourceRoot":"","sources":["../src/types-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,CAAA;IAC7E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,4FAA4F;IAC5F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAqBD;6BAC6B;AAC7B,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAGjF;AAED,oGAAoG;AACpG,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,UAAU,EAAE,CAcd;AAuDD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,KAAK,EAAE,MAAM,EACb,IAAI,UAAQ,GACX,MAAM,CA2BR;AAMD,iGAAiG;AACjG,wBAAgB,eAAe,IAAI,OAAO,CAAC,SAAS,EAAE,GAAG,SAAS,CAAC,CAalE"}
+{"version":3,"file":"types-search.d.ts","sourceRoot":"","sources":["../src/types-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,CAAA;IAC7E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,4FAA4F;IAC5F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAqBD;6BAC6B;AAC7B,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAGjF;AAED,oGAAoG;AACpG,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,UAAU,EAAE,CAoBd;AAuDD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,KAAK,EAAE,MAAM,EACb,IAAI,UAAQ,GACX,MAAM,CA2BR;AAMD,iGAAiG;AACjG,wBAAgB,eAAe,IAAI,OAAO,CAAC,SAAS,EAAE,GAAG,SAAS,CAAC,CAalE"}

package/dist/types-search.js

@@ -8,7 +8,8 @@
  * Lookup by `name` is exact (case-insensitive); `query` keyword-scores over the name (heavy) + the
  * signature/doc body; no args → a per-package index of the available type names.
  */
-import { countBodyHits, queryTermGroups, tokenize, tokenSetHas } from "./search-terms.js";
+import { codeUnitOrder } from "./internal/code-unit-order.js";
+import { countBodyHits, queryTermGroups, tokenize, tokenSetScore } from "./search-terms.js";
 const preparedTypesCache = new WeakMap();
 const prepareTypes = (types) => {
     const cached = preparedTypesCache.get(types);
@@ -37,15 +38,20 @@ export function searchTypes(types, query, limit) {
     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) {
     const head = `## ${t.name} - ${t.kind}, \`${t.package}\``;
@@ -124,7 +130,7 @@ export function renderTypesResult(types, name, query, limit, full = false) {
         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/dist/types-search.js.map

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

package/dist/upgrade.d.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).
  *
@@ -30,6 +35,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 {
     readonly file: string;
@@ -63,10 +72,13 @@ export interface UpgradePlan {
     readonly notes: readonly string[];
 }
 /**
- * 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 declare function rewriteVersionSpec(spec: string, toVersion: string): string | null;
+export declare function rewriteVersionSpec(spec: string, toVersion: string, exact?: boolean): string | null;
+/** The version a plain semver spec names (`^2.4.1` → `2.4.1`), or null for any other spec. */
+export declare function specVersion(spec: string): string | null;
 /** Numeric core (major, minor, patch) of a semver spec, ignoring the range operator + prerelease/build. */
 export declare function specVersionTuple(spec: string): readonly [number, number, number] | null;
 /** Compare two semver cores: <0 when a<b, 0 equal, >0 when a>b. */
@@ -81,7 +93,7 @@ export declare function compareSemverSpec(a: string, b: string): number;
 export declare function pinSweepText(text: string, rules: readonly {
     match: string;
     to: string;
-}[], allowDowngrade?: boolean): {
+}[], allowDowngrade?: boolean, exact?: boolean): {
     text: string;
     changes: Array<Omit<PinChange, "file">>;
     downgrades: Array<Omit<PinChange, "file">>;
@@ -91,7 +103,7 @@ export declare function moveDependenciesText(text: string, moves: readonly {
     from: string;
     to: string;
     toVersion: string;
-}[]): {
+}[], exact?: boolean): {
     text: string;
     changes: Array<Omit<DependencyMoveChange, "file">>;
 };
@@ -107,8 +119,26 @@ export declare function applyImportMoves(text: string, moves: readonly {
         count: number;
     }>;
 };
+/**
+ * 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 declare function installedGroupVersion(cwd: string): string | null;
+/** 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 declare function chainRecipes(target: string, installed: string | null): ChainedRecipe;
 /** Compute the plan (and, when `write`, apply it) for a target recipe against `cwd`. */
-export declare function computeUpgrade(cwd: string, recipe: UpgradeRecipe, write: boolean, allowDowngrade?: boolean): UpgradePlan;
+export declare function computeUpgrade(cwd: string, recipe: UpgradeRecipe, write: boolean, allowDowngrade?: boolean, exact?: boolean): UpgradePlan;
+/** The targets this CLI applies: each release recipe up to its own version, and that version. */
+export declare function upgradeTargets(cliVersion: string): string[];
 /** CLI entry. Returns false (→ non-zero exit) on an unknown version, no project, or a failed verify. */
 export declare function runUpgrade(cwd: string, options: UpgradeOptions): Promise<boolean>;
 //# sourceMappingURL=upgrade.d.ts.map

package/dist/upgrade.d.ts.map

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

package/dist/upgrade.js

@@ -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).
  *
@@ -30,17 +35,27 @@ const DEP_FIELDS = [
 // 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.-]+)?$/;
 /**
- * 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, toVersion) {
+export function rewriteVersionSpec(spec, toVersion, exact = false) {
     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) {
+    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) {
     const match = SEMVER_SPEC.exec(spec.trim());
@@ -105,7 +120,7 @@ const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
  * JSON re-serialize that would reorder keys or drop comments-as-formatting). Returns the new text and
  * the changes made.
  */
-export function pinSweepText(text, rules, allowDowngrade = false) {
+export function pinSweepText(text, rules, allowDowngrade = false, exact = false) {
     let parsed;
     try {
         parsed = JSON.parse(text);
@@ -126,7 +141,7 @@ export function pinSweepText(text, rules, allowDowngrade = false) {
             const rule = rules.find((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
@@ -201,14 +216,14 @@ function rewriteDependencyEntry(text, field, from, fromVersion, to, toVersion) {
         let start = match.index;
         let end = match.index + match[0].length;
         let after = end;
-        while (/\\s/.test(body[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] ?? ""))
+            while (before >= 0 && /\s/.test(body[before] ?? ""))
                 before--;
             if (body[before] === ",")
                 start = before;
@@ -218,7 +233,7 @@ function rewriteDependencyEntry(text, field, from, fromVersion, to, toVersion) {
     return text.slice(0, range.start) + nextBody + text.slice(range.end);
 }
 /** Move removed package dependencies without reserializing or reordering package.json. */
-export function moveDependenciesText(text, moves) {
+export function moveDependenciesText(text, moves, exact = false) {
     let out = text;
     const changes = [];
     for (const move of moves) {
@@ -239,7 +254,7 @@ export function moveDependenciesText(text, moves) {
             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);
@@ -258,6 +273,13 @@ export function moveDependenciesText(text, moves) {
             });
         }
     }
+    // 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 };
 }
 const IMPORT_SPEC = (from) => new RegExp(`(\\bfrom\\s*|\\bimport\\s*\\(\\s*|\\brequire\\s*\\(\\s*|\\bimport\\s+)(['"])${escapeRegExp(from)}(['"])`, "g");
@@ -279,8 +301,13 @@ export function applyImportMoves(text, moves) {
     return { text: out, changes };
 }
 const SOURCE_GLOB = "**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}";
-const IGNORE_SEGMENTS = ["node_modules/", "/dist/", "/build/", "/.git/", "/coverage/", "/.next/"];
-const isIgnored = (path) => path.startsWith("node_modules/") || IGNORE_SEGMENTS.some((seg) => path.includes(seg));
+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) => path
+    .split(/[\\/]/)
+    .slice(0, -1)
+    .some((segment) => IGNORED_DIRECTORIES.has(segment));
 function scan(cwd, pattern) {
     const glob = new Glob(pattern);
     const out = [];
@@ -290,8 +317,73 @@ function scan(cwd, pattern) {
     }
     return out.sort(); // deterministic order
 }
+// The fixed version group: every package released together at one version.
+const isFixedGroup = (name) => name.startsWith("@nifrajs/") || name === "nifra" || name === "create-nifra";
+const groupPins = (version) => [
+    { 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) {
+    let lowest = null;
+    for (const rel of scan(cwd, "**/package.json")) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(join(cwd, rel), "utf8"));
+        }
+        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)) {
+                if (!isFixedGroup(name) || typeof spec !== "string")
+                    continue;
+                const version = specVersion(spec);
+                if (version !== null && (lowest === null || compareSemverSpec(version, lowest) < 0)) {
+                    lowest = version;
+                }
+            }
+        }
+    }
+    return lowest;
+}
+/**
+ * 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, installed) {
+    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();
+    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, recipe, write, allowDowngrade = false) {
+export function computeUpgrade(cwd, recipe, write, allowDowngrade = false, exact = false) {
     const pins = [];
     const dependencyMoves = [];
     const importMoves = [];
@@ -300,10 +392,10 @@ export function computeUpgrade(cwd, recipe, write, allowDowngrade = false) {
         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)
@@ -334,10 +426,15 @@ export function computeUpgrade(cwd, recipe, write, allowDowngrade = false) {
         notes: recipe.notes ?? [],
     };
 }
-function renderPlan(plan, write) {
+function renderPlan(plan, write, from, steps) {
     const lines = [];
     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 &&
         plan.dependencyMoves.length === 0 &&
@@ -386,24 +483,62 @@ function renderDowngradeRefusal(version, downgrades) {
         "installed one, or pass --allow-downgrade if the rollback is intended.",
     ].join("\n");
 }
+/** The targets this CLI applies: each release recipe up to its own version, and that version. */
+export function upgradeTargets(cliVersion) {
+    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, options) {
+    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, options) {
+    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")}`);
+            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) {
-        console.error(`[nifra] no upgrade recipe for ${version}. Available: ${listRecipeVersions().join(", ") || "(none)"}`);
+    if (!targets.includes(version)) {
+        console.error(`[nifra] no upgrade recipe for ${version}. This CLI upgrades to: ${targets.join(", ")}. ` +
+            `For ${version} itself, run: ${newerCliCommand(version, options)}`);
         return false;
     }
     // Detect: the cwd must be a project (or workspace) root.
@@ -416,23 +551,26 @@ export async function runUpgrade(cwd, options) {
     }
     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.
     if (write && options.verify !== false) {