@bensandee/tooling 0.63.0 → 0.64.0

package/dist/bin.mjs

@@ -7,7 +7,7 @@ import path from "node:path";
 import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { execFileSync, execSync } from "node:child_process";
 import JSON5 from "json5";
-import { parse } from "jsonc-parser";
+import { applyEdits, modify, parse } from "jsonc-parser";
 import { z } from "zod";
 import { FatalError, TransientError, UnexpectedError } from "@bensandee/common";
 import { isMap, isScalar, isSeq, parse as parse$1, parseDocument, stringify, visit } from "yaml";
@@ -2006,23 +2006,149 @@ function diagnoseCheckScriptForwardingAt(targetDir) {
 //#endregion
 //#region src/generators/package-json.ts
 /**
-* Node major pinned for the dev/CI runtime via `devEngines.runtime`.
+* Single source of truth for the supported Node floor. `engines.node` is the
+* honest minimum (`>=<floor>`); `devEngines.runtime.version` is the caret form
+* (`^<floor>` = `>=floor <nextmajor>`), which serves two masters at once:
 *
-* `actions/setup-node` reads `devEngines.runtime` (for `name: "node"`) before
-* `engines.node`, and a bounded `<major>.x` resolves to the latest patch of that
-* one major. Without it, a `>=`-range `engines.node` makes setup-node install the
-* newest available major (e.g. Node 26), silently drifting CI off the LTS line.
-* `engines.node` stays the honest minimum-supported floor; this is the version CI
-* actually runs. `onFail: "warn"` keeps a local Node mismatch non-fatal.
+*  - `actions/setup-node` reads `devEngines.runtime` (for `name: "node"`) before
+*    `engines.node`. The `<nextmajor>` upper bound keeps it on the pinned LTS
+*    major (resolving to the latest patch within it) instead of floating to the
+*    newest released major (e.g. Node 26) the way a bare `>=` range would.
+*  - pnpm resolves `devEngines.runtime.version` to its floor and checks it
+*    against `engines.node`. The caret's floor equals the engines floor, so the
+*    two never contradict — a `<major>.x` floor of `<major>.0.0` sits below
+*    `>=<floor>` and makes `pnpm install` emit a spurious "Unsupported engine"
+*    warning. The floor MUST track `engines.node`, so it is derived from it
+*    rather than hard-coded.
+*
+* `onFail: "warn"` keeps a local Node mismatch non-fatal.
 */
-const DEV_NODE_VERSION = "24.x";
+const NODE_ENGINES_FLOOR = "24.13.0";
+const ENGINES_NODE = `>=${NODE_ENGINES_FLOOR}`;
+/** The `^<floor>` runtime range whose floor satisfies a `>=<floor>` engines range. */
+function caretRange(floor) {
+	return `^${floor}`;
+}
 function devEnginesRuntime() {
 	return { runtime: {
 		name: "node",
-		version: DEV_NODE_VERSION,
+		version: caretRange(NODE_ENGINES_FLOOR),
 		onFail: "warn"
 	} };
 }
+function versionPart(s) {
+	return s && s !== "x" && s !== "*" ? Number(s) : 0;
+}
+function compareTuples(a, b) {
+	for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] - b[i];
+	return 0;
+}
+/**
+* Effective lower bound of a single conjunction (space-separated comparators like
+* `>=24.14.0 <25.0.0`). Upper bounds (`<`, `<=`) don't raise the floor and are
+* ignored; the floor is the **max** of the remaining lower-bound tokens (`>=`,
+* `>`, `^`, `~`, `=`, bare, `<major>.x`). Missing/wildcard positions read as 0.
+* `undefined` when no token carries a numeric lower bound.
+*/
+function conjunctionFloor(conjunction) {
+	let floor;
+	for (const token of conjunction.trim().split(/\s+/)) {
+		if (!token || token.startsWith("<")) continue;
+		const match = /(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?/.exec(token);
+		if (!match) continue;
+		const candidate = [
+			Number(match[1]),
+			versionPart(match[2]),
+			versionPart(match[3])
+		];
+		if (!floor || compareTuples(candidate, floor) > 0) floor = candidate;
+	}
+	return floor;
+}
+/**
+* Lowest version a semver range permits, as a `[major, minor, patch]` tuple —
+* what pnpm resolves a `devEngines.runtime.version` to when cross-checking
+* `engines.node`. Handles floor-first forms (`>=24.14.0`, `^24.13.0`, `24.x`,
+* `24`), compound ranges in any order (`>=24.14.0 <25.0.0`, `<25 >=24.14.0` →
+* `24.14.0`), and `||` alternation (the minimum across alternatives).
+*
+* Returns `undefined` when no floor can be determined (e.g. `*`, `latest`, an
+* alternative with only an upper bound) — callers must warn rather than guess.
+*/
+function minVersionTuple(range) {
+	let min;
+	for (const alternative of range.split("||")) {
+		const floor = conjunctionFloor(alternative);
+		if (!floor) return void 0;
+		if (!min || compareTuples(floor, min) < 0) min = floor;
+	}
+	return min;
+}
+/** True when `range`'s floor is >= `enginesNode`'s floor (i.e. pnpm won't warn). */
+function runtimeFloorSatisfies(range, enginesNode) {
+	const dev = minVersionTuple(range);
+	const eng = minVersionTuple(enginesNode);
+	if (!dev || !eng) return true;
+	return compareTuples(dev, eng) >= 0;
+}
+/**
+* Decide how to reconcile a package's `devEngines.runtime` (node entries) with
+* its `engines.node` floor, without mutating anything. The caret form `^<floor>`
+* keeps pnpm quiet (its floor equals the engines floor) while staying bounded to
+* the same major for `setup-node`.
+*
+*  - `noop`  — no node runtime declared, or every node runtime already satisfies
+*    the engines floor (a deliberate higher pin is left alone). Never adds a
+*    `devEngines.runtime` that isn't already there.
+*  - `warn`  — a node runtime is declared but `engines.node` has no determinable
+*    floor; leave it unchanged rather than guess.
+*  - `fix`   — `staleIndices` index the node runtimes (in array order, or `[0]`
+*    for the single-object form) whose `version` must become `desired`.
+*/
+function planDevEnginesFix(pkg, enginesNode) {
+	const runtimeField = pkg["devEngines"]?.runtime;
+	if (!runtimeField) return { kind: "noop" };
+	const nodeEntries = (Array.isArray(runtimeField) ? runtimeField : [runtimeField]).map((runtime, index) => ({
+		runtime,
+		index
+	})).filter(({ runtime }) => runtime.name === "node" && typeof runtime.version === "string");
+	if (nodeEntries.length === 0) return { kind: "noop" };
+	const floor = minVersionTuple(enginesNode);
+	if (!floor) return {
+		kind: "warn",
+		message: `could not determine a floor from engines.node "${enginesNode}"`
+	};
+	const desired = caretRange(`${floor[0]}.${floor[1]}.${floor[2]}`);
+	const staleIndices = nodeEntries.filter(({ runtime }) => !runtimeFloorSatisfies(runtime.version ?? "", enginesNode)).map(({ index }) => index);
+	if (staleIndices.length === 0) return { kind: "noop" };
+	return {
+		kind: "fix",
+		desired,
+		staleIndices
+	};
+}
+/**
+* Correct an existing `devEngines.runtime` (node) in place so its floor matches
+* `engines.node` — only the `version` changes; `name` and `onFail` are
+* preserved. Never adds `devEngines.runtime` to a package that lacks it.
+*/
+function ensureDevEnginesConsistent(pkg, enginesNode, changes) {
+	const plan = planDevEnginesFix(pkg, enginesNode);
+	if (plan.kind === "warn") {
+		log.warn(`package.json: ${plan.message}; leaving devEngines.runtime unchanged`);
+		return;
+	}
+	if (plan.kind !== "fix") return;
+	const runtimeField = pkg["devEngines"]?.runtime;
+	const runtimes = Array.isArray(runtimeField) ? runtimeField : runtimeField ? [runtimeField] : [];
+	for (const index of plan.staleIndices) {
+		const runtime = runtimes[index];
+		if (!runtime) continue;
+		const previous = runtime.version;
+		runtime.version = plan.desired;
+		changes.push(`bumped devEngines.runtime node ${previous} → ${plan.desired}`);
+	}
+}
 const STANDARD_SCRIPTS_SINGLE = {
 	build: "tsdown",
 	dev: "tsdown --watch",
@@ -2332,13 +2458,11 @@ function applyMetadataDefaults(pkg, ctx, changes) {
 		}
 	}
 	if (!pkg["engines"]) {
-		pkg["engines"] = { node: ">=24.13.0" };
-		changes.push("set engines.node >= 24.13.0");
-	}
-	if (!pkg["devEngines"]) {
-		pkg["devEngines"] = devEnginesRuntime();
-		changes.push(`set devEngines.runtime node ${DEV_NODE_VERSION}`);
+		pkg["engines"] = { node: ENGINES_NODE };
+		changes.push(`set engines.node ${ENGINES_NODE}`);
 	}
+	const enginesNode = pkg["engines"]?.["node"];
+	if (typeof enginesNode === "string") ensureDevEnginesConsistent(pkg, enginesNode, changes);
 	const pinnedPnpm = {
 		"@changesets/cli": "2.31.0",
 		"@release-it/bumper": "7.0.6",
@@ -2392,7 +2516,7 @@ function buildManagedDevDeps(ctx) {
 	const devDeps = { ...ROOT_DEV_DEPS };
 	if (!isMonorepo) Object.assign(devDeps, PER_PACKAGE_DEV_DEPS);
 	devDeps["@bensandee/config"] = isWorkspacePackage(ctx, "@bensandee/config") ? "workspace:*" : "0.12.0";
-	if (!isWorkspacePackage(ctx, "@bensandee/tooling")) devDeps["@bensandee/tooling"] = "0.63.0";
+	if (!isWorkspacePackage(ctx, "@bensandee/tooling")) devDeps["@bensandee/tooling"] = "0.64.0";
 	if (ctx.config.useEslintPlugin) devDeps["@bensandee/eslint-plugin"] = isWorkspacePackage(ctx, "@bensandee/eslint-plugin") ? "workspace:*" : "0.13.1";
 	if (ctx.config.formatter === "oxfmt") devDeps["oxfmt"] = {
 		"@changesets/cli": "2.31.0",
@@ -2472,7 +2596,7 @@ async function generatePackageJson(ctx) {
 		type: "module",
 		scripts: allScripts,
 		devDependencies: devDeps,
-		engines: { node: ">=24.13.0" },
+		engines: { node: ENGINES_NODE },
 		devEngines: devEnginesRuntime(),
 		packageManager: `pnpm@${{
 			"@changesets/cli": "2.31.0",
@@ -2498,6 +2622,63 @@ async function generatePackageJson(ctx) {
 		description: "Generated package.json"
 	};
 }
+/**
+* Reconcile `devEngines.runtime` against `engines.node` in nested workspace
+* packages — pnpm's "Unsupported engine" warning fires per-package, so a
+* subpackage that declares both fields can warn even when the root is clean.
+*
+* Unlike the root `package.json` (a fully managed file), a subpackage's
+* `package.json` is otherwise owned by the user, so this edits *only* the stale
+* `version` string via `jsonc-parser` rather than reserialising the whole file
+* (which would reorder keys and produce a large surprising diff). It never adds
+* `engines.node` or `devEngines.runtime` — it touches a package only when both
+* already exist and a node runtime's floor is below the engines floor.
+*
+* Scans `packages/*` (the same convention as the rest of the tool); other
+* workspace layouts (`apps/*`, custom globs) are out of scope.
+*/
+async function generateWorkspaceEngines(ctx) {
+	if (ctx.config.structure !== "monorepo") return [];
+	const results = [];
+	for (const member of getMonorepoPackages(ctx.targetDir)) {
+		const result = reconcileWorkspaceDevEngines(ctx, path.join(path.relative(ctx.targetDir, member.dir), "package.json"));
+		if (result) results.push(result);
+	}
+	return results;
+}
+/** Surgically fix a single nested package.json's devEngines, preserving its formatting. */
+function reconcileWorkspaceDevEngines(ctx, relPath) {
+	const raw = ctx.read(relPath);
+	if (!raw) return void 0;
+	const pkg = parsePackageJson(raw);
+	if (!pkg) return void 0;
+	const enginesNode = pkg["engines"]?.["node"];
+	if (typeof enginesNode !== "string") return void 0;
+	const plan = planDevEnginesFix(pkg, enginesNode);
+	if (plan.kind === "warn") {
+		log.warn(`${relPath}: ${plan.message}; leaving devEngines.runtime unchanged`);
+		return;
+	}
+	if (plan.kind !== "fix") return void 0;
+	const isArray = Array.isArray(pkg["devEngines"]?.runtime);
+	let text = raw;
+	for (const index of plan.staleIndices) text = applyEdits(text, modify(text, isArray ? [
+		"devEngines",
+		"runtime",
+		index,
+		"version"
+	] : [
+		"devEngines",
+		"runtime",
+		"version"
+	], plan.desired, {}));
+	ctx.write(relPath, text);
+	return {
+		filePath: relPath,
+		action: "updated",
+		description: `bumped devEngines.runtime node → ${plan.desired}`
+	};
+}
 //#endregion
 //#region src/generators/tsconfig.ts
 async function generateTsconfig(ctx) {
@@ -5701,6 +5882,7 @@ async function generateVersionrc(ctx) {
 async function runGenerators(ctx) {
 	const results = [];
 	results.push(await generatePackageJson(ctx));
+	results.push(...await generateWorkspaceEngines(ctx));
 	results.push(await generatePnpmWorkspace(ctx));
 	results.push(...await generateTsconfig(ctx));
 	results.push(await generateTsdown(ctx));
@@ -5734,7 +5916,7 @@ async function runGenerators(ctx) {
 function generateMigratePrompt(results, config, detected) {
 	const sections = [];
 	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
-	sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.63.0 repo:sync\` on ${timestamp}_\n`);
+	sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.64.0 repo:sync\` on ${timestamp}_\n`);
 	const changed = results.filter((r) => r.action === "created" || r.action === "updated" || r.action === "archived");
 	if (changed.length > 0) {
 		const items = changed.map((r) => {
@@ -10214,7 +10396,7 @@ const out = (msg) => console.log(msg);
 const main = defineCommand({
 	meta: {
 		name: "bst",
-		version: "0.63.0",
+		version: "0.64.0",
 		description: "Bootstrap and maintain standardized TypeScript project tooling"
 	},
 	subCommands: {
@@ -10286,7 +10468,7 @@ const main = defineCommand({
 		})
 	}
 });
-console.log(`@bensandee/tooling v0.63.0`);
+console.log(`@bensandee/tooling v0.64.0`);
 async function run() {
 	await runMain(main);
 	process.exit(process.exitCode ?? 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bensandee/tooling",
-  "version": "0.63.0",
+  "version": "0.64.0",
   "description": "CLI tool to bootstrap and maintain standardized TypeScript project tooling",
   "license": "MIT",
   "repository": {