@williamthorsen/nmr 0.45.0 → 0.46.1

package/.meta/changelog.json

@@ -1,4 +1,48 @@
 [
+  {
+    "version": "0.46.1",
+    "date": "2026-10-13",
+    "sections": [
+      {
+        "title": "🐛 Bug fixes",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Fixes the issue that a script run by bare `nmr` inside a package failed with `command not found` on a binary installed only in that package, and found the root's binaries, such as `eslint` and `tsgo`, only when the shell's `PATH` already contained the root's `node_modules/.bin`. (#1039)",
+            "hash": "64cde10b969329630577e2f9011d0a6cd480e009",
+            "entry": 1
+          }
+        ]
+      }
+    ]
+  },
+  {
+    "version": "0.46.0",
+    "date": "2026-10-13",
+    "sections": [
+      {
+        "title": "🎉 Features",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Adds a `packageMaturityPeriod` option to the config built with `defineConfig` from `@williamthorsen/nmr/taze`, which sets, for packages whose names match a `*` pattern, how many days after a release `nmr upgrade` waits before proposing it, in place of the shared `maturityPeriod`. (#1036)",
+            "hash": "ed3d16ce494c8162e0598ec9ed1004f34a158efd",
+            "entry": 1
+          },
+          {
+            "description": "Defines an embedded test, which runs an engine installed by the package, such as PGlite (Postgres compiled to WebAssembly), inside the test process, and places it in the `tool` tier rather than `unit` in `docs/vitest.md` and the `nmr` rulebook. (#1037)",
+            "hash": "15c5d922fb5a05aa2d57d18a46a957909ad0f006",
+            "entry": 1
+          },
+          {
+            "description": "Redefines a package's `peerDependencies` in `docs/vitest.md` as candidate tools rather than as the `tool` boundary, so a test is `tool` only when it makes a peer do work, and a test that imports a peer only for its constants, such as `AST_NODE_TYPES`, stays `unit`. (#1037)",
+            "hash": "15c5d922fb5a05aa2d57d18a46a957909ad0f006",
+            "entry": 2
+          }
+        ]
+      }
+    ]
+  },
   {
     "version": "0.45.0",
     "date": "2026-10-12",

package/.readyup/kits/default.js

@@ -8939,7 +8939,7 @@ function formatPaths(paths) {
 ${paths.map((path7) => `      ${path7}`).join("\n")}`;
 }
 function getMinVersion() {
-  const pickedFields = { "version": "0.45.0" };
+  const pickedFields = { "version": "0.46.1" };
   if (typeof pickedFields["version"] !== "string") {
     throw new TypeError("nmr/package.json: 'version' must be a string");
   }

package/.readyup/manifest.json

@@ -86,7 +86,7 @@
           "path": "kits/default.ts"
         },
         {
-          "hash": "22efcac6",
+          "hash": "e03b7529",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -159,7 +159,7 @@
           "path": "../src/steps.ts"
         },
         {
-          "hash": "d1e8e302",
+          "hash": "d8368f1a",
           "kind": "module",
           "path": "../src/tiers.ts"
         },
@@ -189,7 +189,7 @@
       "readyupVersion": "0.40.0",
       "source": "kits/default.ts",
       "sourceHash": "aaeb1a84",
-      "targetHash": "a8b07f51"
+      "targetHash": "dbfec446"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.46.1 — 2026-10-13
+
+### 🐛 Bug fixes
+
+- Fixes the issue that a script run by bare `nmr` inside a package failed with `command not found` on a binary installed only in that package, and found the root's binaries, such as `eslint` and `tsgo`, only when the shell's `PATH` already contained the root's `node_modules/.bin`. (#1039)
+
+## 0.46.0 — 2026-10-13
+
+### 🎉 Features
+
+- Adds a `packageMaturityPeriod` option to the config built with `defineConfig` from `@williamthorsen/nmr/taze`, which sets, for packages whose names match a `*` pattern, how many days after a release `nmr upgrade` waits before proposing it, in place of the shared `maturityPeriod`. (#1036)
+- Defines an embedded test, which runs an engine installed by the package, such as PGlite (Postgres compiled to WebAssembly), inside the test process, and places it in the `tool` tier rather than `unit` in `docs/vitest.md` and the `nmr` rulebook. (#1037)
+- Redefines a package's `peerDependencies` in `docs/vitest.md` as candidate tools rather than as the `tool` boundary, so a test is `tool` only when it makes a peer do work, and a test that imports a peer only for its constants, such as `AST_NODE_TYPES`, stays `unit`. (#1037)
+
 ## 0.45.0 — 2026-10-12
 
 ### 🎉 Features

package/README.md

@@ -5,21 +5,11 @@
 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 -->
-## Release notes — v0.45.0 (2026-10-12)
-
-### 🎉 Features
-
-- Adds `maintenance.auto=false` to the git config that the Vitest git-isolation setup file injects, so that a git command run by a test does not start a detached `git maintenance` process that can still be writing under `.git` when the test removes the repository. (#1033)
+## Release notes — v0.46.1 (2026-10-13)
 
 ### 🐛 Bug fixes
 
-- Fixes the issue that `nmr-fmt` failed a run in which every path matched by the pathspecs was one that it skips, such as a symlink, a submodule gitlink, or an unreadable file, and makes such a run exit 0 and name the skipped paths on stderr. (#1010)
-- Fixes the issue that a `rootScripts` or `workspaceScripts` entry in `.config/nmr.config.ts` that names its own key, as a shell segment or as a step-list element, re-entered nmr without bound, by rejecting the entry when the config loads with an error that names the file, the field, the key, and the edit that resolves it. (#1011)
-- Fixes the issue that a package's own `package.json` entry running `nmr -R <same command>` re-entered that package without bound instead of being discarded or rejected as a self-reference. (#1011)
-- Fixes the issue that nmr treated a root entry such as `pnpm --recursive exec nmr build` as a re-invocation of its own command, because it ignored the `-r`, `--filter`, and `-w` flags that pnpm applies to the nmr that it launches. (#1011)
-- Fixes the issue that `nmr` hung when a script entry re-entered its own command in the same directory without nmr recognizing the self-reference, as `nmr -F own-pkg build` in `own-pkg`'s own `build` or a cycle through two entries does, by failing the run with an error that names the command and the directory and lists the commands that the run had entered, outermost first. (#1012)
-- Fixes the issue that the test-tier definitions in `vitest.md` gave a test that starts its own loopback server three defensible tiers: `tool` is now a process that the test starts or a program that the environment supplies, `localhost` a service already running on this machine, and an in-process server from the package's own dependency closure `unit`. (#1023)
-- Fixes the issue that `nmr`'s warning about a `package.json` script that runs `nmr` through a shell sent an entry whose whole value is `nmr <name>` to `.config/nmr.config.ts`, when the accurate edit is to replace that value with the command of the `<name>` script in the same file. (#1030)
+- Fixes the issue that a script run by bare `nmr` inside a package failed with `command not found` on a binary installed only in that package, and found the root's binaries, such as `eslint` and `tsgo`, only when the shell's `PATH` already contained the root's `node_modules/.bin`. (#1039)
 <!-- /section:release-notes -->
 
 ## Installation
@@ -220,7 +210,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, and the request timeout.
+`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.
 
 ### Workspace introspection
 

package/agents/guidance/rulebooks/nmr.md

@@ -13,5 +13,5 @@ delivery: ambient
 - A check that already passed on the current working tree skips, printing `SKIP <scope>: <command>: passed …` and, when the recalled run left one, `— replayed: <excerpt>` of what that run concluded. Any edit, addition, or deletion re-runs it. Read the replayed excerpt rather than running the check again: Never pass `--no-cache` to get a "real" run, which takes the command's full runtime to reach the same answer. Its one use is a file rather than an exit status -- a skipped command writes none, so a fresh `coverage/` needs `nmr --no-cache test:coverage`. A composite replays its constituents' excerpts, each attributed as `<scope>: <command>: <excerpt>` and cut at the line's ceiling when there are too many to fit. A skip without an excerpt is one whose run wrote to a terminal, or one whose constituents recorded none.
 - `nmr --log <command>` prints the whole run behind that excerpt -- up to 256 KiB, led by when it was recorded, how long it ran, and the command string that produced it. Output that you need in full is a recording to read rather than a command to run again. It runs nothing, and it is held to the tree rather than to the terminal: A recording made by a piped run prints for a reader at one. A composite prints its constituents' excerpts, not their transcripts, so the transcript of one of them is `nmr -F <pkg> --log <command>` or that constituent's own name. When there is nothing to show, `--log` says so on one line, names which case it is, and exits non-zero.
 - Every command that nmr runs reports one line -- `PASS <scope>: <command>: passed in 12.4s`, `FAIL … failed in 1.2s (exit 1)`, `SKIP … passed 4m ago on this tree`, or `NOOP … skipped, the override is empty` -- and a composite reports alongside every command into which it expands. Those are the words that a pipe and a CI log get; a terminal gets ✅, ❌, ⏩, and ⚪ in their place, and `--output-style rich` or `NMR_OUTPUT_STYLE=rich` forces the emoji on any stream. The lines print in every verbosity, so `nmr -q <command>` is the low-noise way to run rather than a silent one: It withholds the output of the commands that nmr runs and keeps nmr's own verdicts, which is how a pass, a cached skip, and a `""`/`":"` override stay distinguishable. nmr reads its own flags only before the command name and passes everything after the name to the commands that run: `nmr ci -q` hands `-q` to `nmr-fmt`, which rejects it. Expect a run to be quiet already without the flag: nmr recognizes a known agent harness in the environment and takes quiet from that, as it does from `NMR_COMMAND_VERBOSITY` or the repo's `output.commandVerbosity`. A command whose output you need in full is one to run with `NMR_COMMAND_VERBOSITY=full`, which outranks both.
-- Every test file lives under a `__tests__` directory and names its isolation tier last: `<subject>[.<aspect>].<tier>.test.ts`, where any earlier segment is free-form documentation. A tier is the furthest thing that the test reaches -- `tool` (a process that the test starts, or a program that the environment supplies), `localhost` (a service already running on this machine), `remote` (a machine that isn't this one), or `unit`, the residual claiming everything else. A file outside `__tests__`, or one whose tier segment is missing or misspelt, fails the test run in a repo that declares nmr's exported conventions check, which reports both. In a repo that has not, neither fails anything -- the first is collected by nothing and the second runs under `unit` -- and `rdy run --sources` reports both and warns that the check is missing.
+- Every test file lives under a `__tests__` directory and names its isolation tier last: `<subject>[.<aspect>].<tier>.test.ts`, where any earlier segment is free-form documentation. A tier is the furthest thing that the test reaches -- `tool` (a process that the test starts, or a program other than the package's own code that the test makes do its work, including an embedded engine, which the package installs and the test runs in-process, such as PGlite), `localhost` (a service already running on this machine), `remote` (a machine that isn't this one), or `unit`, the residual claiming everything else. A file outside `__tests__`, or one whose tier segment is missing or misspelt, fails the test run in a repo that declares nmr's exported conventions check, which reports both. In a repo that has not, neither fails anything -- the first is collected by nothing and the second runs under `unit` -- and `rdy run --sources` reports both and warns that the check is missing.
 - The rest is in `node_modules/@williamthorsen/nmr/docs/`: `scripts.md` for pre/post hooks (every `nmr X` auto-wraps as `nmr X:pre && nmr X && nmr X:post`) and script overrides and their `""`/`":"` skip values; `upgrades.md` for `nmr upgrade` ceilings (report-only until `nmr upgrade --write`); `utilities.md` for the `nmr-compile` build (the repo does not define a build script of its own); `vitest.md` for the test tiers' timeout budgets, the `tiers` seam that raises one, and which script reaches which tier; and `check-cache.md` for the check-result cache's key, the retention key to which a replayed excerpt is additionally held, the retention ceiling within which `--log` prints, its `checkCache` config, and every condition that disables it.

package/dist/esm/bin-path.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns the environment in which a scope's commands run: Its `PATH` leads with the anchor's `node_modules/.bin`
+ * and then the monorepo root's, as under `pnpm run`, followed by the inherited `PATH`.
+ *
+ * A directory that the inherited `PATH` already contains is left where it is, so that an nmr run nested in another
+ * does not lengthen `PATH`.
+ */
+export declare function prependBinDirs(options: {
+    anchorDir: string;
+    env: NodeJS.ProcessEnv;
+    monorepoRoot: string;
+}): NodeJS.ProcessEnv;

package/dist/esm/bin-path.js

@@ -0,0 +1,21 @@
+import path from 'node:path';
+export function prependBinDirs(options) {
+    const { anchorDir, env, monorepoRoot } = options;
+    const inherited = env['PATH'] ?? '';
+    const seen = new Set(inherited
+        .split(path.delimiter)
+        .filter((entry) => entry !== '')
+        .map((entry) => path.resolve(entry)));
+    const additions = [];
+    for (const dir of [anchorDir, monorepoRoot]) {
+        const binDir = path.resolve(dir, 'node_modules', '.bin');
+        if (!seen.has(binDir)) {
+            seen.add(binDir);
+            additions.push(binDir);
+        }
+    }
+    if (additions.length === 0) {
+        return env;
+    }
+    return { ...env, PATH: [...additions, ...(inherited === '' ? [] : [inherited])].join(path.delimiter) };
+}

package/dist/esm/cli-taze.js

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

package/dist/esm/commands/load-package-maturity-period.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns the `packageMaturityPeriod` that the taze config governing `cwd` declares, unvalidated, or `undefined`
+ * when no config file is found.
+ *
+ * The sources, the upward search, and the `default` unwrapping mirror `resolveConfig` and `normalizeConfig` in
+ * taze 21.3.0, so that this reads the same file that taze reads. Throws when the file fails to load.
+ */
+export declare function loadPackageMaturityPeriod(cwd: string): Promise<unknown>;

package/dist/esm/commands/load-package-maturity-period.js

@@ -0,0 +1,15 @@
+import { createConfigLoader } from 'unconfig';
+export async function loadPackageMaturityPeriod(cwd) {
+    const { config, sources } = await createConfigLoader({
+        sources: [{ files: ['taze.config'] }, { files: ['.tazerc'], extensions: ['json', ''] }],
+        cwd,
+        merge: false,
+    }).load();
+    if (sources.length === 0)
+        return undefined;
+    const options = isRecord(config) && 'default' in config ? config['default'] : config;
+    return isRecord(options) ? options['packageMaturityPeriod'] : undefined;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}

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

@@ -0,0 +1,17 @@
+/** Ends the arguments that taze reads: Everything past it is collected for a downstream tool. */
+export declare const ARGUMENT_TERMINATOR = "--";
+/** A flag found among the arguments that taze reads, with the value given to it, if any. */
+export interface FlagReading {
+    value: string | undefined;
+}
+/**
+ * Inserts `inserted` after the arguments that taze reads, ahead of a bare `--` so that taze still reads them.
+ */
+export declare function insertBeforeTerminator(args: readonly string[], inserted: readonly string[]): string[];
+/** Reports whether the invocation silences taze's output, in any spelling that taze's CLI accepts. */
+export declare function isSilent(args: readonly string[]): boolean;
+/**
+ * Finds the first of `spellings` among the arguments that taze reads, returning the value given in its `=value`
+ * form or as the next argument. A next argument that starts with `-` is another flag, not a value.
+ */
+export declare function readFlag(args: readonly string[], spellings: readonly string[]): FlagReading | undefined;

package/dist/esm/commands/taze-args.js

@@ -0,0 +1,25 @@
+export const ARGUMENT_TERMINATOR = '--';
+export function insertBeforeTerminator(args, inserted) {
+    const terminatorIndex = args.indexOf(ARGUMENT_TERMINATOR);
+    if (terminatorIndex === -1)
+        return [...args, ...inserted];
+    return [...args.slice(0, terminatorIndex), ...inserted, ...args.slice(terminatorIndex)];
+}
+export function isSilent(args) {
+    return readFlag(args, ['--silent', '-s']) !== undefined || readFlag(args, ['--loglevel'])?.value === 'silent';
+}
+export function readFlag(args, spellings) {
+    for (const [index, arg] of args.entries()) {
+        if (arg === ARGUMENT_TERMINATOR)
+            return undefined;
+        for (const spelling of spellings) {
+            if (arg.startsWith(`${spelling}=`))
+                return { value: arg.slice(spelling.length + 1) };
+            if (arg === spelling) {
+                const next = args[index + 1];
+                return { value: next === undefined || next.startsWith('-') ? undefined : next };
+            }
+        }
+    }
+    return undefined;
+}

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

@@ -0,0 +1,18 @@
+/** One run of taze: the arguments that it receives and, in a split run, the heading printed before it. */
+export interface TazePass {
+    args: string[];
+    heading?: string;
+}
+/**
+ * Splits a taze invocation into one pass per `packageMaturityPeriod` entry and one for every other dependency.
+ *
+ * Each pass is confined by `--exclude` alone: taze subtracts every `--exclude` value from the dependencies that it
+ * checks, so the invocation's own `--include` and `--exclude` narrow each pass as they narrow a single run. An
+ * entry pass excludes every package that its key does not match or that an earlier key matches, so that the first
+ * matching key decides a package's period. A maturity period given on the command line applies to every
+ * dependency, so it returns the invocation as a single pass.
+ *
+ * Throws when `packageMaturityPeriod` is not a record of glob keys to non-negative periods. A key cannot be a regex,
+ * contain a comma, or name a version (`name@range`), each of which taze reads as something other than a name glob.
+ */
+export declare function planTazePasses(args: readonly string[], packageMaturityPeriod: unknown): TazePass[];

package/dist/esm/commands/taze-passes.js

@@ -0,0 +1,59 @@
+import { insertBeforeTerminator, readFlag } from "./taze-args.js";
+const MATURITY_PERIOD_FLAGS = ['--maturity-period', '--maturityPeriod'];
+export function planTazePasses(args, packageMaturityPeriod) {
+    const entries = validatePackageMaturityPeriod(packageMaturityPeriod);
+    if (entries.length === 0 || readFlag(args, MATURITY_PERIOD_FLAGS) !== undefined)
+        return [{ args: [...args] }];
+    const keys = entries.map(([key]) => key);
+    const entryPasses = entries.map(([key, days], index) => ({
+        args: insertBeforeTerminator(args, [
+            '--maturity-period',
+            String(days),
+            '--exclude',
+            composeComplementFilter(key, keys.slice(0, index)),
+        ]),
+        heading: `Packages matching ${key}: ${days}-day maturity period`,
+    }));
+    const remainderPass = {
+        args: insertBeforeTerminator(args, ['--exclude', keys.join(',')]),
+        heading: 'All other packages: configured maturity period',
+    };
+    return [...entryPasses, remainderPass];
+}
+function composeComplementFilter(key, earlierKeys) {
+    const outsideKey = `^(?!${convertGlobToRegexBody(key)}$)`;
+    if (earlierKeys.length === 0)
+        return `/${outsideKey}/`;
+    return `/${outsideKey}|^(?:${earlierKeys.map(convertGlobToRegexBody).join('|')})$/`;
+}
+function convertGlobToRegexBody(glob) {
+    return glob.replaceAll(/[.+?^${}()|[\]\\]/g, String.raw `\$&`).replaceAll(/\*+/g, '.*?');
+}
+function validatePackageMaturityPeriod(value) {
+    if (value === undefined)
+        return [];
+    if (!isPlainObject(value)) {
+        throw new Error('packageMaturityPeriod must be an object mapping package patterns to periods in days');
+    }
+    return Object.entries(value).map(([key, days]) => {
+        if (key.startsWith('/')) {
+            throw new Error(`packageMaturityPeriod entry '${key}': keys are package names with * wildcards, not regexes`);
+        }
+        if (key.includes(',')) {
+            throw new Error(`packageMaturityPeriod entry '${key}': a key cannot contain a comma`);
+        }
+        if (key.lastIndexOf('@') > 0) {
+            throw new Error(`packageMaturityPeriod entry '${key}': a key names packages, not a version selector`);
+        }
+        if (typeof days !== 'number' || !Number.isFinite(days) || days < 0) {
+            throw new Error(`packageMaturityPeriod entry '${key}': the period must be a non-negative number of days`);
+        }
+        return [key, days];
+    });
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}

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

@@ -4,28 +4,34 @@ export interface SpawnOutcome {
     error?: Error | undefined;
 }
 export interface RunTazeOptions {
+    /** 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. */
     resolveCliPath?: () => string;
     /** Runs the CLI and reports how it exited. Injected by tests. */
     spawn?: (nodePath: string, argv: string[]) => SpawnOutcome;
-    /** Stream that error output is written to. Defaults to `process.stderr`. */
+    /** Stream that error output and pass headings are written to. Defaults to `process.stderr`. */
     stderr?: Writable;
 }
 /**
  * Runs taze from nmr's own dependency tree, forwarding `args`, and returns its exit code.
  *
+ * When the repo's taze config declares `packageMaturityPeriod`, runs taze once per entry and once for every other
+ * dependency, each with `args` and the filters and period that `planTazePasses` adds, and returns the first non-zero
+ * exit code among them. Every pass runs; a heading on `stderr` names each pass unless `args` silence taze.
+ *
  * Consumers depend on nmr, not on taze, so taze is transitive and its bin is absent from the consumer's
  * 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.
  *
- * A request timeout is the one argument added, and only when `args` does not set 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 array that it reads as a near-zero deadline; a `taze.config.ts` setting goes into
- * the object that taze's own CLI defaults overwrite. Because every other argument is forwarded untouched,
- * invocation policy (`--recursive`) stays in the script registry, visible in `nmr` help output and overridable
- * per repo, and upgrade policy stays in `taze.ts`.
+ * 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
+ * array that it reads as a near-zero deadline; a `taze.config.ts` setting goes into the object that taze's own CLI
+ * defaults overwrite. Because every argument of the invocation reaches taze, invocation policy (`--recursive`)
+ * stays in the script registry, visible in `nmr` help output and overridable per repo, and upgrade policy stays in
+ * `taze.ts`.
  */
-export declare function runTaze(args: string[], options?: RunTazeOptions): number;
+export declare function runTaze(args: string[], options?: RunTazeOptions): Promise<number>;
 /** Resolves the absolute path of taze's CLI entry from nmr's own dependency tree. */
 export declare function resolveTazeCliPath(): string;

package/dist/esm/commands/taze.js

@@ -1,17 +1,21 @@
 import { spawnSync } from 'node:child_process';
+import path from 'node:path';
 import process from 'node:process';
 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 { 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 ARGUMENT_TERMINATOR = '--';
-export function runTaze(args, options = {}) {
+export async function runTaze(args, options = {}) {
     const stderr = options.stderr ?? process.stderr;
     const resolveCliPath = options.resolveCliPath ?? resolveTazeCliPath;
     const spawn = options.spawn ?? spawnNode;
+    const loadConfig = options.loadConfig ?? loadPackageMaturityPeriod;
     let cliPath;
     try {
         cliPath = resolveCliPath();
@@ -21,27 +25,38 @@ export function runTaze(args, options = {}) {
         reportError(`Could not resolve '${TAZE_CLI_SPECIFIER}' from nmr's dependencies. Reinstall the workspace to restore it. (${detail})`, stderr);
         return 1;
     }
-    const outcome = spawn(process.execPath, [cliPath, ...composeRequestTimeoutArgs(args), ...args]);
-    if (outcome.error) {
-        reportError(`Failed to run taze: ${outcome.error.message}`, stderr);
+    let passes;
+    try {
+        passes = planTazePasses(args, await loadConfig(resolveConfigDir(args)));
+    }
+    catch (error) {
+        reportError(`Could not read the taze config: ${describeError(error)}`, stderr);
         return 1;
     }
-    return outcome.status ?? 1;
+    const showHeadings = !isSilent(args);
+    let exitCode = 0;
+    for (const pass of passes) {
+        if (pass.heading !== undefined && showHeadings)
+            stderr.write(`${pass.heading}\n`);
+        const outcome = spawn(process.execPath, [cliPath, ...composeRequestTimeoutArgs(pass.args), ...pass.args]);
+        if (outcome.error) {
+            reportError(`Failed to run taze: ${outcome.error.message}`, stderr);
+            return 1;
+        }
+        const status = outcome.status ?? 1;
+        if (exitCode === 0)
+            exitCode = status;
+    }
+    return exitCode;
 }
 export function resolveTazeCliPath() {
     return fileURLToPath(import.meta.resolve(TAZE_CLI_SPECIFIER));
 }
-function carriesRequestTimeout(args) {
-    for (const arg of args) {
-        if (arg === ARGUMENT_TERMINATOR)
-            return false;
-        if (REQUEST_TIMEOUT_FLAGS.some((flag) => arg === flag || arg.startsWith(`${flag}=`)))
-            return true;
-    }
-    return false;
-}
 function composeRequestTimeoutArgs(args) {
-    return carriesRequestTimeout(args) ? [] : [REQUEST_TIMEOUT_FLAG, String(REQUEST_TIMEOUT_MS)];
+    return readFlag(args, REQUEST_TIMEOUT_FLAGS) === undefined ? [REQUEST_TIMEOUT_FLAG, String(REQUEST_TIMEOUT_MS)] : [];
+}
+function resolveConfigDir(args) {
+    return path.resolve(readFlag(args, ['--cwd', '-C'])?.value ?? '.');
 }
 function spawnNode(nodePath, argv) {
     const result = spawnSync(nodePath, argv, { stdio: 'inherit' });

package/dist/esm/runCli.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { describeInvalidOutputStyle, formatGlyphLine, reportError, resolveSelfVersion, STATUS_GLYPHS, } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
+import { prependBinDirs } from "./bin-path.js";
 import { certifyRetention, computeCacheKey, computeRetentionKey, CURRENT_RUNTIME, encodeTreeSnapshot, findStaleBuildOutput, formatMisplacedNoCacheWarning, isCacheableCommand, NO_CACHE_ENV_VAR, readBuildOutputState, readCheckCacheEntry, recordTranscript, resolveRunId, resolveTreeSnapshot, RUN_ID_ENV_VAR, TREE_SNAPSHOT_ENV_VAR, writeCheckCacheEntry, writeDebugNote, } from "./check-cache.js";
 import { resolveContext } from "./context.js";
 import { enterChain } from "./entry-chain.js";
@@ -163,7 +164,12 @@ async function planRun(invocation) {
         ? runOptions
         : {
             ...runOptions,
-            env: enterChain({ anchorDir, command, env: childEnv, monorepoRoot: context.monorepoRoot }),
+            env: enterChain({
+                anchorDir,
+                command,
+                env: prependBinDirs({ anchorDir, env: childEnv, monorepoRoot: context.monorepoRoot }),
+                monorepoRoot: context.monorepoRoot,
+            }),
         };
     const chain = assembleChain({ invocation, registry, resolvedScript, snapshot });
     if (chain.settled) {

package/dist/esm/taze.d.ts

@@ -8,6 +8,13 @@ import type { CheckOptions } from 'taze';
  */
 export type TazeConfig = {
     [K in keyof CheckOptions]?: CheckOptions[K] | undefined;
+} & {
+    /**
+     * Maturity period in days for each package pattern, read by `nmr-taze` rather than by taze. A key is a package
+     * name in which `*` matches any run of characters, and the first key that matches a package decides its period.
+     * Every other dependency keeps `maturityPeriod`.
+     */
+    packageMaturityPeriod?: Record<string, number> | undefined;
 };
 /**
  * Builds a taze configuration from nmr's shared upgrade policy and a repo's own settings.

package/dist/esm/tiers.d.ts

@@ -56,11 +56,12 @@ export interface TestFileScanOptions {
     excludedBasenames?: readonly string[];
 }
 /**
- * The isolation ladder, ordered by the furthest thing that a test reaches, which decides what the environment must
- * supply for the test to run. A tier names what a test reaches, never how it invokes it: A test driving a compiler
- * through its JavaScript API is `tool`, exactly as one spawning `tsc` would be, and a spawned process is itself
- * something reached. Each named tier's name is also its filename infix, so `parse.tool.test.ts` is collected by the
- * `tool` project.
+ * The isolation ladder, ordered by the furthest thing that a test reaches: `unit` runs only the package's own code
+ * and the libraries that it calls, and `tool` starts a process or makes another program do its work. A tier names
+ * what a test reaches, never how it invokes it: A test driving a compiler through its JavaScript API is `tool`,
+ * exactly as one spawning `tsc` would be, and so is an embedded test, which runs in-process an engine that the
+ * package installs, such as PGlite. Each named tier's name is also its filename infix, so `parse.tool.test.ts` is
+ * collected by the `tool` project.
  */
 export declare const TIER_NAMES: readonly ["unit", "tool", "localhost", "remote"];
 /** One of the four isolation tiers. */

package/docs/scripts.md

@@ -1,6 +1,6 @@
 # Scripts and configuration
 
-How nmr resolves a command through its three tiers, how script values compose, how hooks wrap a command, how to configure scripts and builds, and what the default commands do beyond what `nmr --help` prints.
+How nmr resolves a command through its three tiers, how script values compose, which binaries a command finds on `PATH`, how hooks wrap a command, how to configure scripts and builds, and what the default commands do beyond what `nmr --help` prints.
 
 ## Three-tier override system
 
@@ -83,6 +83,10 @@ nmr recognizes `nmr` in command position: at the start of a step, after an unquo
 
 A [self-referential entry](#three-tier-override-system), in `package.json` or in `.config/nmr.config.ts`, is the shape that nmr cannot run as written, and it is rejected rather than reported. The same recognition finds it, so the same residuals apply: What goes unrecognized there re-enters nmr once, and the run then fails with an error naming the command and the directory that it re-entered.
 
+### Binaries on `PATH`
+
+Every command that nmr runs, whatever its tier, finds the binaries that `pnpm run` would find. Inside a package, its `PATH` leads with the package's `node_modules/.bin` and then the root's, followed by the `PATH` from which nmr was started; at the root, it leads with the root's `node_modules/.bin`. A script can therefore invoke a binary installed only in its own package by bare name, however nmr was started: bare `nmr` through direnv, `pnpm exec nmr`, or `nmr -F <pkg>` from the root. A directory that `PATH` already contains is not added again, so a nested nmr run does not lengthen it.
+
 ## Pre and post hooks
 
 The wrap rule and a repo-wide example are in the [README](../README.md#pre-and-post-hooks).

package/docs/upgrades.md

@@ -51,6 +51,34 @@ Two consequences of the `minor` range mode declared by the policy:
 - A `packageMode` entry is honored only by the pass whose mode matches it, or by a `default` pass; every other pass drops that dependency rather than narrowing it. Under the policy's `minor` mode, a `patch` ceiling hides its dependency until a developer runs `nmr upgrade patch`, and a `minor` ceiling hides it from `nmr upgrade major`.
 - A `~` range is searched as `^`, so minor upgrades are proposed for it and `--write` applies them under the original `~`. To hold one dependency to patches, give it a `packageMode` entry of `patch` and read it from `nmr upgrade patch`; to hold the whole repo there, declare `mode: 'patch'`.
 
+### Per-package maturity periods
+
+`packageMaturityPeriod` gives the packages that match a pattern a quarantine of their own, in days. Every other dependency keeps `maturityPeriod`. taze applies one maturity period to a whole run, so `nmr upgrade` runs it once for each entry and once more for every other dependency, each run headed on stderr by the patterns and the period that it covers. The command exits with the first non-zero exit code among the runs.
+
+```ts
+import { defineConfig } from '@williamthorsen/nmr/taze';
+
+export default defineConfig({
+  // Propose first-party releases after one day, and third-party ones after the policy's seven.
+  packageMaturityPeriod: {
+    '@williamthorsen/*': 1,
+    readyup: 1,
+  },
+});
+```
+
+A key is a package name in which `*` matches any run of characters; a regex key, a key containing a comma, or a version selector such as `typescript@7` fails the command before taze runs. When several keys match a package, the first one decides its period. A period of `0` removes the quarantine for those packages.
+
+A package listed in `maturityPeriodExclude`, or in the `minimumReleaseAgeExclude` of `pnpm-workspace.yaml`, which taze inherits into it, skips the quarantine in every run. Remove it from that list before giving it a period here.
+
+`--maturity-period <days>` on the command line applies one period to every dependency for that call, in a single run:
+
+```bash
+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.
+
 ## Request timeout
 
 Every `upgrade` script calls the upgrade tool with a 30-second request timeout, in place of the tool's own 5 seconds.
@@ -101,7 +129,7 @@ nmr report-overrides
 
 ## `nmr-taze`
 
-Run the [taze](https://github.com/antfu-collective/taze) dependency-upgrade tool, forwarding every argument to it untouched and adding one of its own: a 30-second request timeout, unless the invocation already includes one. 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. 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/docs/vitest.md

@@ -10,22 +10,24 @@ The [README](../README.md#shared-vitest-config) shows the one-line config file.
 
 The config declares four projects, an ordered ladder named for the furthest thing that a test reaches:
 
-| Project     | Matches                                     | Reaches                                                                    |
-| ----------- | ------------------------------------------- | -------------------------------------------------------------------------- |
-| `unit`      | every test file that the others don't claim | nothing outside the package's own dependency closure                       |
-| `tool`      | `*.tool.test.{ts,tsx}`                      | a process that the test starts, or a program that the environment supplies |
-| `localhost` | `*.localhost.test.{ts,tsx}`                 | a service already running on this machine                                  |
-| `remote`    | `*.remote.test.{ts,tsx}`                    | a machine that isn't this one                                              |
+| Project     | Matches                                     | Reaches                                                                                                        |
+| ----------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `unit`      | every test file that the others don't claim | only the package's own code and the libraries that it calls                                                    |
+| `tool`      | `*.tool.test.{ts,tsx}`                      | a process that the test starts, or a program other than the package's own code that the test makes do its work |
+| `localhost` | `*.localhost.test.{ts,tsx}`                 | a service already running on this machine                                                                      |
+| `remote`    | `*.remote.test.{ts,tsx}`                    | a machine that isn't this one                                                                                  |
 
 All four match only under a `__tests__` directory.
 
-**A tier names what the environment must supply for a test to run.** A test is `tool` when it reaches a process that it starts, or a program that the environment supplies. A spawned process is itself something that the test reaches, even when it runs the package's own code, because the machine sets how long the process takes to start and to run.
+**A tier names the furthest program that a test makes do its work.** A test is `unit` while everything that it runs is the package's own code or a library that the code calls for a result. It is `tool` when it starts a process, or when it makes a program other than the package's own code do its work, whether the environment supplies that program or the package installs it. The machine sets how long such a program takes to start and to run, which is why a spawned process counts even when it runs the package's own code.
 
-**A tier names what a test reaches, never how it invokes it.** A test driving a compiler through its JavaScript API is `tool`, exactly as one spawning the compiler binary is; whether a program ships as a library or an executable is an accident of packaging, not a property of the test. What decides is who supplies the program, and a package declares that in its `peerDependencies`. Those, plus whatever binaries it spawns, mark where its `tool` boundary lies: A bundled dependency is inside the package's own closure and is always present, so reaching one in-process is `unit`.
+**A tier names what a test reaches, never how it invokes it.** A test driving a compiler through its JavaScript API is `tool`, exactly as one spawning the compiler binary is; whether a program ships as a library or an executable is an accident of packaging, not a property of the test. The same holds for an **embedded** test, which runs, inside the test process, an engine that the package installs as a dependency and that is not the package's own code. An engine does a job of its own, such as a database, a compiler, or a bundler; a library is a set of functions that the code calls for a result. Embedded tests are `tool`: A test that starts PGlite (Postgres compiled to WebAssembly) is `tool`, and a test that calls a parsing library is `unit`.
 
-**A service that the test starts itself takes the tier of the code that runs it.** A test that calls `net.Server.listen(0)` on a server from its own dependency closure and reaches it with `fetch` is `unit`: Both ends of the loopback connection are inside the test process, and the connection is how the test invokes that code. The same server started as a child process is `tool`, as is a service whose program the environment supplies, such as a `postgres` binary. `localhost` is for a service that is already running when the test starts, such as a separately started backend or a seeded database.
+**A service that the test starts itself takes the tier of the code that runs it.** A test that calls `net.Server.listen(0)` on a server implemented by the package's own code and reaches it with `fetch` is `unit`: Both ends of the loopback connection are inside the test process, and the connection is how the test invokes that code. The same server started as a child process is `tool`, as is a service whose program the environment supplies, such as a `postgres` binary, or one that the package installs, such as PGlite. `localhost` is for a service that is already running when the test starts, such as a separately started backend or a seeded database.
 
-**A tier is not a statement about preconditions.** A `unit` test may still need something set up before it runs: a build, a generated fixture, a seeded file. It is `unit` because it reaches nothing beyond the test process _while running_. The filesystem belongs to `unit` for the same reason the tiers exist: They gate on what must be available, and the filesystem always is.
+**`peerDependencies` name candidate tools; they do not classify a test.** A package's peers, with the binaries that it spawns and the engines that it installs, are the programs that its tests might make do their work, and a test is `tool` only when it does. A test that imports `AST_NODE_TYPES` from `@typescript-eslint/utils` for its constants, or calls a helper that ships beside a tool and does none of the tool's work, stays `unit`; a test that runs ESLint over a fixture is `tool`. That the peer must be installed for the import to succeed is a precondition, not a tier argument, as the next paragraph states.
+
+**A tier is not a statement about preconditions.** A `unit` test may still need something set up before it runs: a build, a generated fixture, a seeded file, an installed peer. It is `unit` because it does not make any program beyond its own code do work _while running_. The filesystem belongs to `unit` for the same reason: Reaching it does not run another program, and it is always available.
 
 **Every test file names its tier**, in the form `<subject>[.<aspect>].<tier>.test.ts`. Only the segment immediately before `.test.` selects a project, so an earlier one is free for documentation: `resolveConfig.packaged.unit.test.ts` reads as a companion to `resolveConfig.unit.test.ts` and still names `unit`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.45.0",
+  "version": "0.46.1",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -83,7 +83,8 @@
     "glob": "13.0.6",
     "prettier": "3.9.9",
     "prettier-plugin-sh": "0.20.2",
-    "taze": "21.3.0"
+    "taze": "21.3.0",
+    "unconfig": "7.5.0"
   },
   "devDependencies": {
     "@williamthorsen/toolbelt.testing": "0.6.3",
@@ -92,7 +93,7 @@
     "readyup": "0.40.0",
     "tinyglobby": "0.2.17",
     "typescript": "6.0.3",
-    "vite": "8.3.2",
+    "vite": "8.3.3",
     "vitest": "4.1.11",
     "yaml": "2.9.1"
   },