@williamthorsen/nmr 0.53.1 → 0.54.0

package/.meta/changelog.json

@@ -1,4 +1,21 @@
 [
+  {
+    "version": "0.54.0",
+    "date": "2026-10-31",
+    "sections": [
+      {
+        "title": "🎉 Features",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Adds a check of the `nodejs` pin in `.tool-versions` to `nmr upgrade`, which reports the newest release at least 24 hours old in the pin's major line and, under `--write`, rewrites the pin to it. (#1141)",
+            "hash": "d6459b4f867e39162a3e41dd8639993b12ba579f",
+            "entry": 1
+          }
+        ]
+      }
+    ]
+  },
   {
     "version": "0.53.1",
     "date": "2026-10-28",

package/.readyup/kits/default.js

@@ -9190,7 +9190,7 @@ function hasSupportedStrictLintVersion() {
   });
 }
 function getMinVersion() {
-  const pickedFields = { "version": "0.53.1" };
+  const pickedFields = { "version": "0.54.0" };
   if (typeof pickedFields["version"] !== "string") {
     throw new TypeError("nmr/package.json: 'version' must be a string");
   }

package/.readyup/manifest.json

@@ -10,7 +10,7 @@
         "@williamthorsen/toolbelt.objects": "4.4.0",
         "@williamthorsen/toolbelt.packaging": "0.7.0",
         "@williamthorsen/toolbelt.terminal": "0.3.0",
-        "ansi-regex": "6.4.0",
+        "ansi-regex": "6.5.0",
         "ansi-styles": "6.2.3",
         "cli-truncate": "6.1.1",
         "diff": "9.0.0",
@@ -27,7 +27,7 @@
           "checklist": "nmr",
           "checks": [
             "@williamthorsen/nmr in devDependencies",
-            "@williamthorsen/nmr >= 0.53.1",
+            "@williamthorsen/nmr >= 0.54.0",
             "pnpm-workspace.yaml exists",
             "catalogued dependencies use catalog:",
             "package.json has packageManager field",
@@ -209,7 +209,7 @@
           "path": "lib/workspace-build.ts"
         },
         {
-          "hash": "b54c684e",
+          "hash": "79b213aa",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -327,7 +327,7 @@
       "readyupVersion": "0.44.0",
       "source": "kits/default.ts",
       "sourceHash": "9fd61bf4",
-      "targetHash": "6ad36b20"
+      "targetHash": "5689b2d3"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.54.0 — 2026-10-31
+
+### 🎉 Features
+
+- Adds a check of the `nodejs` pin in `.tool-versions` to `nmr upgrade`, which reports the newest release at least 24 hours old in the pin's major line and, under `--write`, rewrites the pin to it. (#1141)
+
 ## 0.53.1 — 2026-10-28
 
 ### ♻️ Refactoring

package/README.md

@@ -4,7 +4,13 @@
 
 Context-aware script runner for pnpm monorepos. Includes an `nmr` (node-monorepo run) binary that provides centralized, consistent script execution across workspace packages and the monorepo root.
 
-<!-- section:release-notes --><!-- /section:release-notes -->
+<!-- section:release-notes -->
+## Release notes — v0.54.0 (2026-10-31)
+
+### 🎉 Features
+
+- Adds a check of the `nodejs` pin in `.tool-versions` to `nmr upgrade`, which reports the newest release at least 24 hours old in the pin's major line and, under `--write`, rewrites the pin to it. (#1141)
+<!-- /section:release-notes -->
 
 ## Installation
 
@@ -234,7 +240,7 @@ export default definePrettierConfig();
 
 ### Dependency upgrades
 
-`nmr upgrade` reports available dependency upgrades. A `taze.config.ts` at the monorepo root, built with the `defineConfig` exported by `@williamthorsen/nmr/taze`, declares the upgrade policy. [Dependency upgrades](docs/upgrades.md) covers what each invocation reaches, the policy and its ceilings, per-package maturity periods, and the request timeout.
+`nmr upgrade` reports available dependency upgrades, and newer releases in the major line of the `.tool-versions` Node pin. A `taze.config.ts` at the monorepo root, built with the `defineConfig` exported by `@williamthorsen/nmr/taze`, declares the upgrade policy. [Dependency upgrades](docs/upgrades.md) covers what each invocation reaches, the policy and its ceilings, per-package maturity periods, the Node version pin, and the request timeout.
 
 ### Workspace introspection
 
@@ -309,7 +315,7 @@ rdy list --from npm:@williamthorsen/nmr  # what nmr publishes
 - [Check-result cache](docs/check-cache.md): What is skipped, what a hit requires, and replaying, reading, and bypassing recorded runs
 - [Machine lock](docs/machine-lock.md): Which commands wait for one another, where the lock lives, and bypassing it
 - [Delegating to another machine](docs/delegate.md): The user config, `--delegate`, `--delegate-to`, `NMR_DELEGATE`, where a command runs, choosing among several hosts, what the host runs, and setting it up
-- [Dependency upgrades](docs/upgrades.md): `nmr upgrade`, the upgrade policy, `report-catalog`, `report-overrides`, and `nmr-taze`
+- [Dependency upgrades](docs/upgrades.md): `nmr upgrade`, the upgrade policy, the Node version pin, `report-catalog`, `report-overrides`, and `nmr-taze`
 - [Standalone utilities](docs/utilities.md): `nmr-actionlint`, `nmr-clean`, `nmr-compile`, `nmr-fmt`, `nmr-vitest`, and `ensure-prepublish-hooks`
 - [Shared Vitest config](docs/vitest.md): Test tiers, test selections, the conventions check, and customization
 - [Shared Prettier config](docs/prettier.md): What it formats and how to customize it

package/dist/esm/cli-taze.js

@@ -2,8 +2,9 @@ import process from 'node:process';
 import { reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { runTaze } from "./commands/taze.js";
+import { resolveBinStyles } from "./resolveBinStyles.js";
 try {
-    process.exitCode = await runTaze(process.argv.slice(2));
+    process.exitCode = await runTaze(process.argv.slice(2), { stderrStyle: resolveBinStyles().stderr });
 }
 catch (error) {
     reportError(describeError(error));

package/dist/esm/commands/node-pin.d.ts

@@ -0,0 +1,30 @@
+import type { Writable } from 'node:stream';
+import { type OutputStyle } from '@williamthorsen/nmr-core';
+/** Node's release index, which lists every release with its version and its UTC release day. */
+export declare const NODE_RELEASE_INDEX_URL = "https://nodejs.org/dist/index.json";
+export interface CheckNodePinOptions {
+    /** Returns the parsed release index. Injected by tests; defaults to fetching `NODE_RELEASE_INDEX_URL`. */
+    fetchReleases?: () => Promise<unknown>;
+    /** Suppresses the report, but not the warnings. */
+    isSilent: boolean;
+    /** The current time, against which the soak is measured. Injected by tests. */
+    now?: Date;
+    shouldWrite: boolean;
+    /** Stream that the report and the warnings are written to. Defaults to `process.stderr`. */
+    stderr?: Writable;
+    style: OutputStyle;
+}
+/**
+ * Reports the newest release in the major line of the `nodejs` pin in `dir`'s `.tool-versions` that is newer than
+ * the pin and at least 24 hours old, and rewrites the pin to it when `shouldWrite` is set.
+ *
+ * Reports nothing when the file or its `nodejs` entry is absent, or when the pin is current. Every failure is a
+ * warning, so that the check never fails the upgrade that runs it.
+ */
+export declare function checkNodePin(dir: string, options: CheckNodePinOptions): Promise<void>;
+/**
+ * Returns the newest plain `X.Y.Z` release in `pin`'s major line that is newer than `pin` and whose UTC release day
+ * began at least two days before `now`, or `undefined` when none is. Ignores an entry that lacks a plain version or
+ * a `YYYY-MM-DD` date.
+ */
+export declare function selectNodeUpgrade(pin: string, releases: readonly unknown[], now: Date): string | undefined;

package/dist/esm/commands/node-pin.js

@@ -0,0 +1,127 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { formatGlyphLine } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { NMR_GLYPHS } from "../glyphs.js";
+import { isObject } from "../helpers/type-guards.js";
+export const NODE_RELEASE_INDEX_URL = 'https://nodejs.org/dist/index.json';
+const TOOL_VERSIONS_FILE = '.tool-versions';
+const SOAK_MS = 2 * 24 * 60 * 60 * 1_000;
+const FETCH_TIMEOUT_MS = 10_000;
+const NODEJS_ENTRY_PATTERN = /^[ \t]*nodejs[ \t]+([^\s#]+)/m;
+const PLAIN_VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
+const RELEASE_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+export async function checkNodePin(dir, options) {
+    const stderr = options.stderr ?? process.stderr;
+    function report(message) {
+        stderr.write(`${formatGlyphLine(NMR_GLYPHS, options.style, 'pin', message)}\n`);
+    }
+    function warn(detail) {
+        report(`WARN: Could not check the nodejs pin: ${detail}`);
+    }
+    const filePath = path.join(dir, TOOL_VERSIONS_FILE);
+    let content;
+    try {
+        content = fs.readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        if (isMissingFileError(error))
+            return;
+        warn(describeError(error));
+        return;
+    }
+    const pin = findNodePin(content);
+    if (pin === undefined)
+        return;
+    if (!PLAIN_VERSION_PATTERN.test(pin.version)) {
+        if (!options.isSilent) {
+            report(`Skipped the nodejs pin '${pin.version}' in ${TOOL_VERSIONS_FILE}: Only an X.Y.Z version is checked.`);
+        }
+        return;
+    }
+    let releases;
+    try {
+        releases = await (options.fetchReleases ?? fetchNodeReleaseIndex)();
+    }
+    catch (error) {
+        warn(`${NODE_RELEASE_INDEX_URL} is unreachable (${describeError(error)})`);
+        return;
+    }
+    if (!Array.isArray(releases)) {
+        warn(`${NODE_RELEASE_INDEX_URL} did not return a list of releases`);
+        return;
+    }
+    const target = selectNodeUpgrade(pin.version, releases, options.now ?? new Date());
+    if (target === undefined)
+        return;
+    if (!options.shouldWrite) {
+        if (!options.isSilent) {
+            report(`nodejs ${pin.version} → ${target} is available. Run with --write to update ${TOOL_VERSIONS_FILE}.`);
+        }
+        return;
+    }
+    const updated = content.slice(0, pin.start) + target + content.slice(pin.start + pin.version.length);
+    try {
+        fs.writeFileSync(filePath, updated);
+    }
+    catch (error) {
+        warn(describeError(error));
+        return;
+    }
+    if (!options.isSilent)
+        report(`Updated nodejs ${pin.version} → ${target} in ${TOOL_VERSIONS_FILE}.`);
+}
+export function selectNodeUpgrade(pin, releases, now) {
+    const pinParts = parseVersion(pin);
+    let best;
+    let bestVersion;
+    for (const release of releases) {
+        if (!isObject(release))
+            continue;
+        const { date, version } = release;
+        if (typeof version !== 'string' || typeof date !== 'string' || !RELEASE_DATE_PATTERN.test(date))
+            continue;
+        const bareVersion = version.replace(/^v/, '');
+        if (!PLAIN_VERSION_PATTERN.test(bareVersion))
+            continue;
+        const parts = parseVersion(bareVersion);
+        if (parts[0] !== pinParts[0] || compareVersions(parts, pinParts) <= 0)
+            continue;
+        if (Date.parse(`${date}T00:00:00Z`) + SOAK_MS > now.getTime())
+            continue;
+        if (best !== undefined && compareVersions(parts, best) <= 0)
+            continue;
+        best = parts;
+        bestVersion = bareVersion;
+    }
+    return bestVersion;
+}
+function compareVersions(a, b) {
+    for (let index = 0; index < 3; index++) {
+        const difference = (a[index] ?? 0) - (b[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+}
+async function fetchNodeReleaseIndex() {
+    const response = await fetch(NODE_RELEASE_INDEX_URL, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    if (!response.ok)
+        throw new Error(`HTTP ${response.status}`);
+    const body = await response.json();
+    return body;
+}
+function findNodePin(content) {
+    const match = NODEJS_ENTRY_PATTERN.exec(content);
+    const version = match?.[1];
+    if (match === null || version === undefined)
+        return undefined;
+    return { start: match.index + match[0].length - version.length, version };
+}
+function isMissingFileError(error) {
+    return isObject(error) && error['code'] === 'ENOENT';
+}
+function parseVersion(version) {
+    return version.split('.').map(Number);
+}

package/dist/esm/commands/taze.d.ts

@@ -1,9 +1,13 @@
 import type { Writable } from 'node:stream';
+import { type OutputStyle } from '@williamthorsen/nmr-core';
+import { type CheckNodePinOptions } from './node-pin.js';
 export interface SpawnOutcome {
     status: number | null;
     error?: Error | undefined;
 }
 export interface RunTazeOptions {
+    /** Checks the `.tool-versions` Node pin in a directory. Injected by tests. */
+    checkNodePin?: (dir: string, options: CheckNodePinOptions) => Promise<void>;
     /** Returns the `packageMaturityPeriod` that the taze config governing a directory declares. Injected by tests. */
     loadConfig?: (cwd: string) => Promise<unknown>;
     /** Resolves the absolute path of taze's CLI entry. Injected by tests. */
@@ -12,6 +16,8 @@ export interface RunTazeOptions {
     spawn?: (nodePath: string, argv: string[]) => SpawnOutcome;
     /** Stream that error output and pass headings are written to. Defaults to `process.stderr`. */
     stderr?: Writable;
+    /** Style of `stderr`, in which the Node pin check reports. Defaults to `'plain'`. */
+    stderrStyle?: OutputStyle;
 }
 /**
  * Runs taze from nmr's own dependency tree, forwarding `args`, and returns its exit code.
@@ -24,6 +30,10 @@ export interface RunTazeOptions {
  * root `node_modules/.bin`. This launcher runs taze without that bin: pnpm links nmr's own bins into the
  * consumer root, and nmr resolves taze from the tree that it does control.
  *
+ * Before the passes, checks the `nodejs` pin in the `.tool-versions` of the directory from which taze resolves its
+ * config, reporting a newer release in the pin's major line and rewriting the pin under `--write`. The check only
+ * warns on failure, so it does not affect the exit code.
+ *
  * Every pass also receives a request timeout, unless `args` sets one. Neither other site can declare it: Because
  * an invocation's trailing arguments are appended to the resolved command string, the same flag in the `upgrade`
  * script would be doubled by `nmr upgrade --request-timeout ...`, and taze's parser collects the pair into an

package/dist/esm/commands/taze.js

@@ -5,12 +5,14 @@ import { fileURLToPath } from 'node:url';
 import { reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { loadPackageMaturityPeriod } from "./load-package-maturity-period.js";
+import { checkNodePin as checkNodePinDefault } from "./node-pin.js";
 import { isSilent, readFlag } from "./taze-args.js";
 import { planTazePasses } from "./taze-passes.js";
 const TAZE_CLI_SPECIFIER = 'taze/cli';
 const REQUEST_TIMEOUT_FLAG = '--request-timeout';
 const REQUEST_TIMEOUT_FLAGS = [REQUEST_TIMEOUT_FLAG, '--requestTimeout'];
 const REQUEST_TIMEOUT_MS = 30_000;
+const NODE_PIN_SKIP_FLAGS = ['--no-node-version', '--help', '-h', '--version', '-v'];
 export async function runTaze(args, options = {}) {
     const stderr = options.stderr ?? process.stderr;
     const resolveCliPath = options.resolveCliPath ?? resolveTazeCliPath;
@@ -33,6 +35,19 @@ export async function runTaze(args, options = {}) {
         reportError(`Could not read the taze config: ${describeError(error)}`, stderr);
         return 1;
     }
+    if (readFlag(args, NODE_PIN_SKIP_FLAGS) === undefined) {
+        try {
+            await (options.checkNodePin ?? checkNodePinDefault)(resolveConfigDir(args), {
+                isSilent: isSilent(args),
+                shouldWrite: readFlag(args, ['--write', '-w']) !== undefined,
+                stderr,
+                style: options.stderrStyle ?? 'plain',
+            });
+        }
+        catch (error) {
+            reportError(`Could not check the nodejs pin: ${describeError(error)}`, stderr);
+        }
+    }
     const showHeadings = !isSilent(args);
     let exitCode = 0;
     for (const pass of passes) {

package/dist/esm/glyphs.d.ts

@@ -5,5 +5,5 @@
  * `noop` is a neutral circle: Nothing ran because the repo asked for nothing to run, which is neither a
  * failure nor a block.
  */
-export declare const NMR_GLYPHS: Readonly<Record<"plain" | "rich", Readonly<Record<"overrides" | "clean" | "host" | "catalog" | "noop" | "package" | "recording", import("@williamthorsen/toolbelt.terminal/candidate").Glyph>>>>;
+export declare const NMR_GLYPHS: Readonly<Record<"plain" | "rich", Readonly<Record<"overrides" | "clean" | "host" | "catalog" | "noop" | "package" | "pin" | "recording", import("@williamthorsen/toolbelt.terminal/candidate").Glyph>>>>;
 export type NmrGlyphName = keyof (typeof NMR_GLYPHS)['rich'];

package/dist/esm/glyphs.js

@@ -6,5 +6,6 @@ export const NMR_GLYPHS = defineGlyphSet({
     noop: { plain: 'NOOP', rich: '\u{26AA}' },
     overrides: { plain: '', rich: '\u{1F512}' },
     package: { plain: '', rich: '\u{1F4E6}' },
+    pin: { plain: '', rich: '\u{1F4CC}' },
     recording: { plain: '', rich: '\u{1F4BE}' },
 });

package/docs/upgrades.md

@@ -1,6 +1,6 @@
 # Dependency upgrades
 
-What `nmr upgrade` covers from each scope, how to declare the upgrade policy and its ceilings, and the subcommands and binary that the upgrade chains run.
+What `nmr upgrade` covers from each scope, how to declare the upgrade policy and its ceilings, how it checks the Node version pin, and the subcommands and binary that the upgrade chains run.
 
 `nmr upgrade` reports the dependency upgrades available to the repo. What it covers depends on where it runs:
 
@@ -81,6 +81,23 @@ nmr upgrade --maturity-period 0
 
 Every other argument reaches every run, and `--include` and `--exclude` narrow each run as they narrow a single one. Because each run reports separately, `--json` prints one document per run, `--interactive` opens one selection per run, and `--install` installs after each run.
 
+## Node version pin
+
+Before taze runs, `nmr upgrade` checks the `nodejs` entry of `.tool-versions` in the directory from which taze reads its config: the monorepo root for `upgrade` and `root:upgrade` run there, and a package's own directory for a package-scoped run, which checks nothing unless the package has its own `.tool-versions`. It compares the pin with [Node's release index](https://nodejs.org/dist/index.json) and reports the newest release in the pin's major line:
+
+```text
+nodejs 24.22.1 → 24.22.3 is available. Run with --write to update .tool-versions.
+```
+
+`--write` rewrites that version and leaves the rest of the file unchanged. A newer major line is never proposed, whatever range mode the invocation passes: Changing majors is left to an edit of `.tool-versions`.
+
+- A release is proposed once it is at least 24 hours old. The index dates a release by UTC day alone, so a release dated D is proposed from the start of D+2, UTC.
+- Only a plain `X.Y.Z` pin is checked, and only the first version on the `nodejs` line. Any other pin, such as `lts`, is skipped with a note.
+- A repo without `.tool-versions`, or without a `nodejs` entry in it, is skipped silently.
+- `--no-node-version`, which turns off taze's own checks of `.node-version` and `.nvmrc`, turns off this check too.
+- An unreachable index, or a file that cannot be read or written, produces a warning and does not fail the upgrade.
+- `--silent` suppresses the report but not the warnings. The report goes to stderr, so `--json` output is unaffected.
+
 ## Request timeout
 
 Every `upgrade` script calls the upgrade tool with a 30-second request timeout, in place of the tool's own 5 seconds.
@@ -131,7 +148,7 @@ nmr report-overrides
 
 ## `nmr-taze`
 
-Run the [taze](https://github.com/antfu-collective/taze) dependency-upgrade tool, forwarding every argument to it and adding a 30-second request timeout, unless the invocation already includes one. When the taze config declares [per-package maturity periods](#per-package-maturity-periods), it runs taze once per period, adding to each run the filters and the period that confine it. Every `upgrade` chain ends with it, `root:upgrade` included; see [dependency upgrades](#dependency-upgrades) for the workflow, and [request timeout](#request-timeout) for why the timeout is set here.
+Run the [taze](https://github.com/antfu-collective/taze) dependency-upgrade tool, forwarding every argument to it and adding a 30-second request timeout, unless the invocation already includes one. When the taze config declares [per-package maturity periods](#per-package-maturity-periods), it runs taze once per period, adding to each run the filters and the period that confine it. Before the first run, it checks the [Node version pin](#node-version-pin). Every `upgrade` chain ends with it, `root:upgrade` included; see [dependency upgrades](#dependency-upgrades) for the workflow, and [request timeout](#request-timeout) for why the timeout is set here.
 
 Under pnpm's isolated `node_modules`, a transitive package's binary is absent from the consuming repo's `node_modules/.bin`, so a repo that depends on nmr cannot run `taze` directly. `nmr-taze` can, because nmr is a direct dependency, and it resolves the tool from the tree that nmr controls.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.53.1",
+  "version": "0.54.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -82,7 +82,7 @@
     "@williamthorsen/nmr-core": "0.14.0",
     "@williamthorsen/toolbelt.errors": "0.9.0",
     "@williamthorsen/toolbelt.filesystem": "0.10.0",
-    "glob": "14.0.2",
+    "glob": "14.0.3",
     "prettier": "3.9.10",
     "prettier-plugin-sh": "0.20.2",
     "taze": "21.3.0",
@@ -90,7 +90,7 @@
   },
   "devDependencies": {
     "@williamthorsen/toolbelt.testing": "0.8.0",
-    "@williamthorsen/toolbelt.vitest": "0.13.0",
+    "@williamthorsen/toolbelt.vitest": "0.13.1",
     "esbuild": "0.28.2",
     "readyup": "0.44.0",
     "tinyglobby": "0.2.17",