@williamthorsen/nmr 0.18.2 → 0.20.0

package/AGENTS.md

@@ -2,88 +2,9 @@
 source: '@williamthorsen/nmr@0.0.0-source'
 ---
 
-# nmr: agent guidance
+# nmr: agent guidance (generated; do not edit)
 
-This file is managed by `@williamthorsen/nmr`. Do not edit; run `nmr sync-agent-files` to refresh it after an nmr upgrade that changes this guidance.
-
-## Discover scripts by running nmr
-
-Run `nmr` with no command (from the monorepo root or any workspace package) to list every available script, including composite expansions and resolved shell commands. Check this before guessing a script name from another repo: The registry is authoritative.
-
-## Invocation rules
-
-- Use `nmr <command>` for anything nmr provides. Do not use `pnpm run <command>`.
-- You can invoke nmr from the monorepo root or any workspace package.
-
-### How to make `nmr` resolvable
-
-`nmr` ships as a workspace bin. The bare `nmr` command works only when your shell can find `<root>/node_modules/.bin/nmr`. Choose one:
-
-- **direnv** (recommended for contributors). With [direnv](https://direnv.net/) installed, the repo's `.envrc` adds `node_modules/.bin` to your `PATH` automatically. From any subdirectory, bare `nmr` works.
-- **`pnpm exec nmr <command>`**: Works without setup. pnpm resolves the bin from the workspace root.
-
-Avoid `npx nmr`. Inside git worktrees, `npx` can resolve a different nmr binary from outside the working tree.
-
-## Root vs. workspace context
-
-nmr walks up to find `pnpm-workspace.yaml`, then decides which registry to use based on whether your cwd is inside a workspace package. The same command name (e.g. `build`, `test`, `check:strict`) often exists in both registries with different behavior; the root version typically delegates across all workspaces. Use `-w` to force the root registry from inside a package dir, and `-F <pkg>` to run a single package's script from anywhere.
-
-## Composite scripts
-
-A script value shown in `nmr` output as `[a, b, c]` is a composite: it runs `nmr a && nmr b && nmr c`, stopping at the first failure. Composites can reference other composites.
-
-## `root:*` siblings
-
-Some root scripts (e.g. `lint`, `typecheck`, `test`) expand to `nmr root:X && pnpm --recursive exec nmr X`. The `root:X` variant runs only against root-level files; the plain name runs everywhere. Use `root:X` directly when you want to isolate a failure to the root code.
-
-## Managed build
-
-The default `compile` script runs `nmr-compile`, a standalone bin that uses the TypeScript compiler API to emit a package's `src` to `dist/esm` as `.js` and `.d.ts` in one pass, rewriting relative `.ts`→`.js` specifiers and tsconfig `paths` aliases in both outputs, and skipping work when inputs are unchanged. `typescript` is a peer dependency (`>=5.7.0`). There is no repo-local build script to maintain, and no separate typings step; `nmr build` runs `compile` alone. To find or debug the build, look to `nmr-compile`, not a `config/build.ts` in the consuming repo.
-
-## Override behaviors
-
-In `.config/nmr.config.ts` or a package's `package.json`, override values have special semantics:
-
-- `""` (empty string): Skip the script with a "Skipping" message; exit 0.
-- `":"`: No-op; exit 0. Prefer this over `""` if your repo enforces non-empty script values.
-- Any other string: Runs in place of the default.
-
-## Pre and post hooks
-
-Every `nmr X` invocation auto-wraps as the equivalent of `nmr X:pre && nmr X && nmr X:post`. Hooks are first-class scripts that resolve through the same 3-tier registry (built-in defaults → `.config/nmr.config.ts` → per-package `package.json`). Wrapping is uniform; nested invocations from composite expansion get their own hook treatment. Hook failure short-circuits the chain via shell `&&` semantics, propagating the failing exit code.
-
-Behaviors worth knowing:
-
-- **Silent when absent**: Missing hooks produce no error and no output.
-- **Skip overrides apply to hooks**: A hook value of `""` or `":"` is treated the same as not defining the hook. No console message.
-- **Skipping the main command skips its hooks**: When `X` is overridden to `""` or `":"`, neither `X:pre` nor `X:post` fires.
-- **Recursion guard**: Direct invocation of a hook (e.g., `nmr build:pre`) is treated as a leaf operation. It does NOT itself attempt to resolve `build:pre:pre` or `build:pre:post`.
-- **Passthrough args attach only to the main command**: `nmr X --flag value` runs hooks without `--flag value`.
-
-Worked examples:
-
-```ts
-// .config/nmr.config.ts — extend `nmr build` with a pre-build compile step
-import { defineConfig } from '@williamthorsen/nmr';
-
-export default defineConfig({
-  workspaceScripts: {
-    'build:pre': 'npx rdy compile',
-  },
-});
-```
-
-```jsonc
-// packages/nmr/package.json — re-stamp .agents/nmr/AGENTS.md after every build
-{
-  "scripts": {
-    "build:post": "nmr-sync-agent-files",
-  },
-}
-```
-
-The second example calls the bin directly to sidestep the workspace-vs-root registry distinction.
-
-## Agent-file sync
-
-The presence and version stamp of `.agents/nmr/AGENTS.md` is verified by `check:agent-files`, which is part of the default root `check:strict` composite. If it fails, run `nmr sync-agent-files`.
+- Use `nmr <command>`, not `pnpm run <command>`, for anything nmr provides. Run bare `nmr` to list every command and the shell command it resolves to; a wrong guess reports only `Unknown command`, with no list.
+- Scope follows cwd, and bare `nmr` lists both registries: from the repo root a command covers root files and every workspace; from inside a package, that package alone. `nmr -F <pkg> <command>` targets one package from anywhere; `nmr root:<command>` targets root files alone, which isolates a failure to root code.
+- Never `npx nmr`: inside a git worktree it can resolve a different nmr from outside the tree. Fall back to `pnpm exec nmr`.
+- The rest is in `node_modules/@williamthorsen/nmr/README.md`: pre/post hooks (every `nmr X` auto-wraps as `nmr X:pre && nmr X && nmr X:post`), script overrides and their `""`/`":"` skip values, `nmr upgrade` ceilings (report-only until `nmr upgrade --write`), and the `nmr-compile` build (there is no repo-local build script).

package/README.md

@@ -1,23 +1,54 @@
 # @williamthorsen/nmr
 
-Context-aware script runner for PNPM monorepos. Ships an `nmr` (node-monorepo run) binary that provides centralized, consistent script execution across workspace packages and the monorepo root.
+Context-aware script runner for pnpm monorepos. Ships 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.18.2 (2026-07-18)
+## Release notes — v0.20.0 (2026-07-28)
+
+### 🎉 Features
+
+- 🚨 **Breaking:** Migrate to code-quality workflow v7 and retire the version-restatement apparatus (#503)
+
+  Migrates the code-quality workflow from `@v6` to `@v7`, which no longer requires the Node version to be specified in two places, and removes the test that previously checked for drift. Also removed are the `nmr sync-pnpm-version` command and drift-related exported functions.
+
+  Taking this upgrade requires migrating the repo's code-quality workflow to `@v7` and deleting its version-alignment test in the same change.
+
+- 🚨 **Breaking:** Resolve workspace packages with pnpm's pattern semantics (#509)
+
+  nmr now excludes packages matched by a `!`-prefixed pattern in `pnpm-workspace.yaml` from the packages it operates on. Deep globs such as `packages/**` now match nested packages, and running a command from inside a nested package targets that package rather than an enclosing ancestor. Exclusion patterns must be quoted to take effect. nmr now requires Node.js 24.16 or later.
+
+- Report pnpm overrides when reviewing dependencies (#514)
+
+  From the monorepo root, `nmr upgrade` now reports the repo's active pnpm dependency overrides alongside the upgrade report, making clear when a pin is the reason an expected upgrade is absent. Repos that wired up this override report themselves with an install-time hook can now remove that hook.
+
+- Trim the bundled agent guidance to a cheatsheet (#516)
+
+  Trims the agent guidance nmr installs into consuming repos from 100 lines to 10. Only the bare essentials are now injected into context. Agents are instructed to consult the package's README for details.
 
 ### 🐛 Bug fixes
 
-- Fail the build on aliased imports that escape the package source (#475)
+- Anchor script execution to the resolved registry's directory (#517)
 
-  Fixes an issue where an aliased import that resolved to a target outside the package's own source (one Node could not reach at runtime) passed the build but produced published output that crashed with a module-not-found error. `nmr-compile` now fails the build and reports the unresolvable import and where it pointed, so the problem surfaces before publish instead of in production. Aliased imports that resolve outside the source but remain genuinely external and runnable continue to build and ship unchanged.
+  Fixes an issue where `nmr --workspace-root`, run from inside a workspace package, either failed outright or silently acted on the wrong directory. Commands now behave the same regardless of the directory they are invoked from: root commands act on the monorepo root, and package commands on their own package. Two changes for existing users: `nmr --workspace-root clean` now sweeps every workspace package instead of cleaning only the current one, and relative paths passed to a script now resolve against the directory the script runs in.
 <!-- /section:release-notes -->
 
 ## Installation
 
+Requires Node.js 24.16 or later.
+
 ```bash
 pnpm add -D @williamthorsen/nmr
 ```
 
+### Making `nmr` resolvable
+
+nmr installs as a workspace bin, so the bare `nmr` command works only when your shell can find `<root>/node_modules/.bin/nmr`. Choose one:
+
+- **[direnv](https://direnv.net/)** (recommended for contributors). Add `PATH_add node_modules/.bin` to the repo's `.envrc`, and bare `nmr` works from any subdirectory.
+- **`pnpm exec nmr <command>`**. Works with no setup: pnpm resolves the bin from the workspace root.
+
+> **Note:** Avoid `npx nmr`. Inside a git worktree, `npx` can resolve a different nmr binary from outside the working tree, so the command succeeds while running the wrong code.
+
 ## Quick start
 
 nmr works out of the box with no configuration. It ships with built-in scripts for common monorepo tasks.
@@ -35,7 +66,7 @@ From the monorepo root:
 ```bash
 nmr test          # Run root tests + recursive workspace tests
 nmr build         # Build all packages
-nmr ci            # Run check:strict && build (full CI pipeline)
+nmr ci            # Run build && check:strict && audit (full CI pipeline)
 ```
 
 nmr detects where you are and selects the right scripts automatically — see [context-aware resolution](#context-aware-resolution) below.
@@ -44,19 +75,26 @@ nmr detects where you are and selects the right scripts automatically — see [c
 
 nmr's key feature is that the same command runs different scripts depending on where you invoke it. It walks up from your current directory to find `pnpm-workspace.yaml`, then checks whether your CWD is inside a workspace package directory.
 
-| Where you run `nmr`        | Registry used     | `nmr test` runs                               |
-| -------------------------- | ----------------- | --------------------------------------------- |
-| Monorepo root              | Root scripts      | Root tests + `pnpm --recursive exec nmr test` |
-| Inside a workspace package | Workspace scripts | `pnpm exec vitest` (for that package only)    |
-| Anywhere, with `-w` flag   | Root scripts      | Forces root registry regardless of location   |
+| Where you run `nmr`               | Registry used     | Working directory | `nmr test` runs                               |
+| --------------------------------- | ----------------- | ----------------- | --------------------------------------------- |
+| Monorepo root                     | Root scripts      | Monorepo root     | Root tests + `pnpm --recursive exec nmr test` |
+| Inside a workspace package        | Workspace scripts | The package root  | `pnpm exec vitest` (for that package only)    |
+| Anywhere, with `--workspace-root` | Root scripts      | Monorepo root     | Root tests + `pnpm --recursive exec nmr test` |
 
-Use `-w` to escape package context:
+Relative paths in a script resolve against that working directory, not the invocation directory.
+
+Use `--workspace-root` to escape package context:
 
 ```bash
 # From inside packages/nmr-core, run the root check suite
-nmr -w check
+nmr --workspace-root check
 ```
 
+Two consequences:
+
+- `nmr --workspace-root clean` sweeps every workspace package, as `nmr clean` does from the root.
+- Passthrough paths resolve against the working directory: from `packages/nmr/src/`, `nmr --workspace-root fmt pnpm-workspace.yaml` formats the file at the monorepo root.
+
 ## Three-tier override system
 
 Scripts resolve through three tiers. Higher tiers override lower ones:
@@ -88,6 +126,8 @@ Script values can be `string` or `string[]`. Arrays expand to chained `nmr` sub-
 // expands to: nmr lint && nmr fmt
 ```
 
+Passthrough arguments attach to the final step alone, because the expansion is a single shell chain: `nmr fix --dry-run` runs `nmr lint && nmr fmt --dry-run`.
+
 ## Configuration
 
 Create `.config/nmr.config.ts` in the monorepo root to add or override scripts:
@@ -133,6 +173,86 @@ For example, if a workspace script resolves to `my-cli --verbose`, nmr rewrites
 
 > **Note:** Path resolution uses a heuristic: any non-flag token containing `/` is treated as a relative path. This works well for typical dev-tool commands but may incorrectly resolve URL-like values or glob patterns. Flags using `--flag=value` syntax are not resolved; use the spaced form `--flag value` for paths that need resolution.
 
+## Pre and post hooks
+
+Every `nmr X` invocation auto-wraps as the equivalent of `nmr X:pre && nmr X && nmr X:post`. Hooks are first-class scripts that resolve through the same three tiers as any other script (built-in defaults, then `.config/nmr.config.ts`, then per-package `package.json`). Wrapping is uniform: nested invocations from composite expansion get their own hook treatment. Hook failure short-circuits the chain via shell `&&` semantics, propagating the failing exit code.
+
+Behaviors worth knowing:
+
+- **Silent when absent**: Missing hooks produce no error and no output.
+- **Skip overrides apply to hooks**: A hook value of `""` or `":"` is treated the same as not defining the hook, with no console message.
+- **Skipping the main command skips its hooks**: When `X` is overridden to `""` or `":"`, neither `X:pre` nor `X:post` fires.
+- **Recursion guard**: Direct invocation of a hook (e.g. `nmr build:pre`) is treated as a leaf operation. It does not itself attempt to resolve `build:pre:pre` or `build:pre:post`.
+- **Passthrough args attach only to the main command**: `nmr X --flag value` runs hooks without `--flag value`.
+
+Extend `nmr build` with a pre-build step for every workspace package:
+
+```ts
+// .config/nmr.config.ts
+import { defineConfig } from '@williamthorsen/nmr';
+
+export default defineConfig({
+  workspaceScripts: {
+    'build:pre': 'npx rdy compile',
+  },
+});
+```
+
+Attach a post-build step to one package:
+
+```jsonc
+// packages/nmr/package.json
+{
+  "scripts": {
+    "build:post": "nmr-sync-agent-files",
+  },
+}
+```
+
+The second example calls the bin directly, which sidesteps the workspace-versus-root registry distinction.
+
+## Dependency upgrades
+
+`nmr upgrade` reports the dependency upgrades available to your repo. What it covers depends on where you run it:
+
+| Invocation                   | Covers                                      |
+| ---------------------------- | ------------------------------------------- |
+| `nmr upgrade` (from root)    | the root `package.json` and every workspace |
+| `nmr upgrade` (in a package) | that package                                |
+| `nmr -F <package> upgrade`   | that package, from anywhere                 |
+| `nmr root:upgrade`           | the root `package.json` alone               |
+
+`nmr upgrade` from the root precedes its report with any active `pnpm.overrides` declared in the root `package.json`; `nmr root:upgrade` does not. An override pins a transitive dependency, so an upgrade masked by one never appears in the report.
+
+The upgrade tool ([taze](https://github.com/antfu-collective/taze)) arrives with nmr, so your repo declares no dependency on it. Everything after the command name is passed through, including the range mode:
+
+```bash
+nmr upgrade          # upgrades available within each package's version ceilings
+nmr upgrade major    # major upgrades, still inside the ceilings
+nmr upgrade --write  # apply the proposals to package.json
+```
+
+### Configuring upgrades
+
+Declare version ceilings in a `taze.config.ts` at the monorepo root:
+
+```ts
+import { defineConfig } from '@williamthorsen/nmr/taze';
+
+export default defineConfig({
+  packageMode: {
+    // Hold @types/node at the Node major your `engines` floor requires.
+    '@types/node': 'minor',
+  },
+});
+```
+
+`defineConfig` supplies nmr's shared upgrade policy — currently a seven-day quarantine on brand-new releases — so your config carries only what is specific to your repo. Any setting you declare wins over nmr's default. Passing `undefined` clears a default rather than falling back to it, which is how you hand the quarantine policy back to `pnpm-workspace.yaml`'s `minimumReleaseAge`.
+
+Everything the [taze configuration](https://github.com/antfu-collective/taze#config-file) accepts is accepted here.
+
+> **Note:** `--include-locked` is part of both registry entries because a repo that pins dependencies to exact versions (pnpm's `savePrefix: ''`) has no dependency the tool would otherwise consider — without it, an upgrade pass reports nothing at all. Drop it via `.config/nmr.config.ts` if your repo declares version ranges instead.
+
 ## Default script registries
 
 These scripts are available out of the box. Repo-wide config (tier 2) and per-package overrides (tier 3) can add to or replace any of them.
@@ -157,6 +277,7 @@ These scripts are available out of the box. Repo-wide config (tier 2) and per-pa
 | `test:coverage` | `pnpm exec vitest --coverage`                            |
 | `test:watch`    | `pnpm exec vitest --watch`                               |
 | `typecheck`     | `tsgo --noEmit`                                          |
+| `upgrade`       | `nmr-taze --include-locked`                              |
 | `view-coverage` | `open coverage/index.html`                               |
 
 #### Integration test variant
@@ -178,7 +299,7 @@ A package gets this variant automatically when it contains a `vitest.integration
 | Command | Runs                              |
 | ------- | --------------------------------- |
 | `build` | `pnpm --recursive exec nmr build` |
-| `ci`    | `build`, `check:strict`           |
+| `ci`    | `build`, `check:strict`, `audit`  |
 | `clean` | `nmr-clean`                       |
 
 #### Check and quality
@@ -236,12 +357,11 @@ A package gets this variant automatically when it contains a `vitest.integration
 
 #### Dependencies
 
-| Command           | Runs                                     |
-| ----------------- | ---------------------------------------- |
-| `outdated`        | `pnpm outdated --compatible --recursive` |
-| `outdated:latest` | `pnpm outdated --recursive`              |
-| `update`          | `pnpm update --recursive`                |
-| `update:latest`   | `pnpm update --latest --recursive`       |
+| Command   | Runs                                                            |
+| --------- | --------------------------------------------------------------- |
+| `upgrade` | `nmr-report-overrides && nmr-taze --include-locked --recursive` |
+
+See [dependency upgrades](#dependency-upgrades) for the workflow and its configuration.
 
 #### Root-only
 
@@ -255,14 +375,14 @@ These scripts operate on root-level code only (not workspace packages):
 | `root:lint:strict` | `strict-lint --ignore-pattern 'packages/**' .`                |
 | `root:test`        | `vitest --config ./vitest.root.config.ts`                     |
 | `root:typecheck`   | `tsgo --noEmit`                                               |
+| `root:upgrade`     | `nmr-taze --include-locked`                                   |
 
 #### Utilities
 
-| Command             | Runs                    |
-| ------------------- | ----------------------- |
-| `report-overrides`  | `nmr-report-overrides`  |
-| `sync-agent-files`  | `nmr-sync-agent-files`  |
-| `sync-pnpm-version` | `nmr-sync-pnpm-version` |
+| Command            | Runs                   |
+| ------------------ | ---------------------- |
+| `report-overrides` | `nmr-report-overrides` |
+| `sync-agent-files` | `nmr-sync-agent-files` |
 
 ## CLI reference
 
@@ -272,11 +392,13 @@ These scripts operate on root-level code only (not workspace packages):
 nmr [flags] <command> [args...]
 ```
 
+Position determines ownership: flags before the command name are nmr's own, and everything after the command name is forwarded untouched to the resolved command.
+
 | Flag                     | Description                                         | Default |
 | ------------------------ | --------------------------------------------------- | ------- |
 | `-F, --filter <pattern>` | Run command in matching packages                    | —       |
 | `-R, --recursive`        | Run command in all packages                         | —       |
-| `-w, --workspace-root`   | Force root script registry                          | —       |
+| `-w, --workspace-root`   | Use root scripts, running at the monorepo root      | —       |
 | `-q, --quiet`            | Suppress info messages; show full output on failure | —       |
 | `-?, --help`             | Show available commands                             | —       |
 | `-V, --version`          | Show version number                                 | —       |
@@ -290,14 +412,14 @@ nmr build                   # Compile to .js and .d.ts in one pass
 
 # From the monorepo root
 nmr test                    # Root tests + recursive workspace tests
-nmr ci                      # check:strict + build
+nmr ci                      # build + check:strict + audit
 
 # Target specific packages
-nmr -F core test            # Test only the core package
-nmr -R lint                 # Lint all workspace packages
+nmr --filter core test      # Test only the core package
+nmr --recursive lint        # Lint all workspace packages
 
 # Force root context from anywhere
-nmr -w check                # Run root check from a package dir
+nmr --workspace-root check  # Run root check from a package dir
 ```
 
 ## Additional subcommands
@@ -306,7 +428,7 @@ These commands are available as `nmr` subcommands and as standalone `nmr-`-prefi
 
 ### `report-overrides`
 
-Report any active `pnpm.overrides` in the root `package.json`. Useful as a `postinstall` hook to remind developers of active overrides that may need cleanup.
+Report any active `pnpm.overrides` in the root `package.json`, reminding developers of overrides that may need cleanup. The root `upgrade` script runs it automatically, so no per-repo wiring is needed. Invoking it directly is useful for a one-off report.
 
 ```bash
 nmr report-overrides
@@ -331,13 +453,16 @@ To expose the synced guidance to Claude Code sessions, add this include to the c
 @nmr/AGENTS.md
 ```
 
-### `sync-pnpm-version`
+#### What belongs in the synced file
 
-Synchronize the pnpm version from the root `package.json` `packageManager` field into the GitHub `code-quality.yaml` workflow file.
+The synced file is injected at launch in every consuming repo, so every line is paid for on every task whether or not it is relevant. It is a cheatsheet, not a manual.
 
-```bash
-nmr sync-pnpm-version
-```
+A line earns a place in `AGENTS.md` only if both hold:
+
+1. It is absent from nmr's own output. Bare `nmr` already prints the flags, every command, and the shell command each resolves to; failing checks already name their own fix. Repeating any of that costs launch tokens to say something the agent will be told anyway, at the moment it matters.
+2. The obvious action goes wrong without it. Guidance that prevents a silent mistake earns its place; guidance that prevents a mistake the next error message would diagnose does not.
+
+Everything else belongs in this README, reachable on demand at `node_modules/@williamthorsen/nmr/README.md`, with a pointer from `AGENTS.md` naming the topic so an agent knows to look. When adding a feature, document it here and extend that pointer rather than the cheatsheet.
 
 ## Standalone utilities
 
@@ -353,12 +478,22 @@ nmr-clean
 
 Compile a single package's `src` tree to `dist/esm` with the TypeScript compiler API, emitting `.js` and `.d.ts` in one pass. Because the compiler parses each source file, every relative import form — static, re-export, dynamic `import()`, and bare side-effect — is rewritten from `.ts` to `.js` in both outputs, and `.ts` occurrences inside strings and comments are left intact. tsconfig `paths` aliases are resolved to runnable relative `.js` specifiers in both outputs, sourced from the package's tsconfig. An aliased import whose target resolves outside the package's `src/` and is not resolvable without the alias mapping fails the build with a diagnostic, rather than being emitted verbatim to produce output that fails at runtime. The build is skipped when no input has changed and the previous output is still on disk (a content-and-path hash is cached under `node_modules/.cache/nmr-compile/`, outside the published output). Deleting the output by any means — `nmr clean`, `rm -rf dist`, `git clean` — therefore forces a rebuild rather than a skip. This is the default `compile` script — run it from a package directory.
 
-`typescript` is a peer dependency (`>=5.7.0`, required for `rewriteRelativeImportExtensions`); the consuming repo provides it. Relative imports in source must carry explicit `.ts` extensions for them to be rewritten.
+`typescript` is a peer dependency (`>=5.7.0 <7`); the consuming repo provides it. The floor is what `rewriteRelativeImportExtensions` requires; the ceiling is because TypeScript 7 ships no compiler API — its root export is a version constant, so `nmr-compile` cannot run on it. Relative imports in source must carry explicit `.ts` extensions for them to be rewritten.
 
 ```bash
 nmr-compile
 ```
 
+### `nmr-taze`
+
+Run the [taze](https://github.com/antfu-collective/taze) dependency-upgrade tool, forwarding every argument to it untouched. This is what `root:upgrade` resolves to, and what the root `upgrade` script ends with — see [dependency upgrades](#dependency-upgrades) for the workflow.
+
+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 nmr controls.
+
+```bash
+nmr-taze --include-locked --recursive
+```
+
 ### `ensure-prepublish-hooks`
 
 Verify that all publishable workspace packages have a `prepublishOnly` script. Exits non-zero if any are missing.
@@ -379,25 +514,31 @@ After installing, a consuming repo's root `package.json` scripts shrink to lifec
 
 ```json
 {
-  "prepare": "lefthook install",
-  "postinstall": "nmr report-overrides"
+  "prepare": "lefthook install"
 }
 ```
 
 Per-package `package.json` files no longer need script entries. Run `nmr <command>` directly.
 
-## Consistency tests
+## Workspace introspection
 
-Export structural consistency checks for use in your test suite:
+Repo-wide tests and scripts often need to know where the monorepo root is, or which directories its workspace packages live in. The `@williamthorsen/nmr/workspace` subpath publishes the two pnpm-workspace lookups nmr uses internally:
 
 ```ts
-// __tests__/consistency.test.ts
-import { runConsistencyChecks } from '@williamthorsen/nmr/tests';
+// __tests__/packages.test.ts
+import { findMonorepoRoot, getWorkspacePackageDirs } from '@williamthorsen/nmr/workspace';
 
-runConsistencyChecks();
+const monorepoRoot = findMonorepoRoot();
+
+for (const packageDir of getWorkspacePackageDirs(monorepoRoot)) {
+  // assert something about every workspace package
+}
 ```
 
-This verifies:
+`findMonorepoRoot(startDir?)` walks up from `startDir`, defaulting to `process.cwd()`, until it reaches a directory containing `pnpm-workspace.yaml`. It throws if it runs out of parent directories without finding one.
+
+`getWorkspacePackageDirs(monorepoRoot)` reads the workspace patterns from that repo's `pnpm-workspace.yaml` and resolves them to absolute package directories, sorted and free of duplicates. Patterns carry pnpm's own semantics: `packages/*`, deeper globs such as `packages/**`, exact paths such as `tools/cli`, and `!`-prefixed exclusions such as `!packages/legacy` or `!**/test/**`, which filter every directory the positive patterns matched regardless of where they appear in the list. Nothing under `node_modules` is ever returned.
+
+One divergence from pnpm: a directory counts as a package only if it holds a `package.json`, not a `package.yaml` or `package.json5`.
 
-- pnpm version matches between `package.json` and GitHub workflow
-- Node.js version matches between `.tool-versions` and GitHub workflow
+Quote exclusion patterns in the manifest — `- '!packages/legacy'`. An unquoted `!` opens a YAML tag rather than a string, so the entry never reaches nmr (or pnpm) as a pattern.

package/bin/nmr-taze.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+try {
+  await import('../dist/esm/cli-taze.js');
+} catch (error) {
+  if (error.code === 'ERR_MODULE_NOT_FOUND') {
+    process.stderr.write('nmr-taze: build output not found — run `pnpm run build` first\n');
+  } else {
+    process.stderr.write(`nmr-taze: failed to load: ${error.message}\n`);
+  }
+  process.exit(1);
+}

package/dist/esm/cli-ensure-prepublish-hooks.js

@@ -1,6 +1,6 @@
 import { parseArgsOrExit, reportError } from '@williamthorsen/nmr-core';
 import { DEFAULT_HOOK, ensurePrepublishHooks } from "./commands/ensure-prepublish-hooks.js";
-import { findMonorepoRoot } from "./context.js";
+import { findMonorepoRoot } from "./workspace.js";
 const flagSchema = {
     fix: { long: '--fix', type: 'boolean' },
     dryRun: { long: '--dry-run', type: 'boolean' },

package/dist/esm/cli-report-overrides.js

@@ -1,6 +1,6 @@
 import { reportError } from '@williamthorsen/nmr-core';
 import { reportOverrides } from "./commands/report-overrides.js";
-import { findMonorepoRoot } from "./context.js";
+import { findMonorepoRoot } from "./workspace.js";
 try {
     const monorepoRoot = findMonorepoRoot();
     reportOverrides(monorepoRoot);

package/dist/esm/cli-sync-agent-files.js

@@ -1,6 +1,6 @@
 import { parseArgsOrExit, reportError } from '@williamthorsen/nmr-core';
 import { check, sync } from "./commands/sync-agent-files.js";
-import { findMonorepoRoot } from "./context.js";
+import { findMonorepoRoot } from "./workspace.js";
 const flagSchema = {
     check: { long: '--check', type: 'boolean' },
 };

package/dist/esm/cli-taze.js

@@ -0,0 +1,10 @@
+import process from 'node:process';
+import { reportError } from '@williamthorsen/nmr-core';
+import { runTaze } from "./commands/taze.js";
+try {
+    process.exitCode = runTaze(process.argv.slice(2));
+}
+catch (error) {
+    reportError(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}

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

@@ -4,6 +4,6 @@ export interface BuildOptions {
     outdir?: string;
 }
 export declare function buildPackage(packageDir: string, options?: BuildOptions): Promise<void>;
-export declare function computeBuildHash(packageDir: string, files: string[], emitConfig: object): Promise<string>;
+export declare function computeBuildHash(packageDir: string, files: string[], emitConfig: object, compilerVersion: string): Promise<string>;
 export declare function resolveTsconfigChain(packageDir: string, configFileName?: string): string[];
 export declare function resolveBuildCachePath(packageDir: string): string;

package/dist/esm/commands/build.js

@@ -24,14 +24,14 @@ export async function buildPackage(packageDir, options = {}) {
         ignore: options.ignore ?? DEFAULT_IGNORE,
     });
     const dependencies = ['package.json', ...resolveTsconfigChain(packageDir)];
-    const { changed, currentHash } = await detectBuildChanges(packageDir, [...entryPoints, ...dependencies], emitConfig, cachePath, hasExpectedBuildOutput(packageDir, outdir, entryPoints));
+    const { changed, currentHash } = await detectBuildChanges(packageDir, [...entryPoints, ...dependencies], emitConfig, ts.version, cachePath, hasExpectedBuildOutput(packageDir, outdir, entryPoints));
     if (!changed) {
         return;
     }
     emitPackage(packageDir, entryPoints, outdir);
     await writeBuildCache(cachePath, currentHash);
 }
-export async function computeBuildHash(packageDir, files, emitConfig) {
+export async function computeBuildHash(packageDir, files, emitConfig, compilerVersion) {
     const hash = createHash('sha256');
     for (const file of [...files].sort()) {
         hash.update(file);
@@ -39,6 +39,8 @@ export async function computeBuildHash(packageDir, files, emitConfig) {
         hash.update(await readFile(path.join(packageDir, file)));
     }
     hash.update(JSON.stringify(emitConfig));
+    hash.update('\0');
+    hash.update(compilerVersion);
     return hash.digest('hex');
 }
 export function resolveTsconfigChain(packageDir, configFileName = 'tsconfig.json') {
@@ -140,7 +142,7 @@ function resolveSpecifierReplacement(specifier, sourceContainingFile, compilerOp
         const rewritten = swapTypeScriptExtension(specifier);
         return rewritten === specifier ? undefined : rewritten;
     }
-    if (!aliasPrefixes.some((prefix) => specifier === prefix || specifier.startsWith(prefix))) {
+    if (aliasPrefixes.every((prefix) => !(specifier === prefix || specifier.startsWith(prefix)))) {
         return undefined;
     }
     const resolved = ts.resolveModuleName(specifier, sourceContainingFile, compilerOptions, ts.sys).resolvedModule;
@@ -207,10 +209,10 @@ function findNearestNodeModulesHost(startDir) {
     }
     return current;
 }
-async function detectBuildChanges(packageDir, files, emitConfig, cachePath, outputPresent) {
+async function detectBuildChanges(packageDir, files, emitConfig, compilerVersion, cachePath, outputPresent) {
     const packageName = path.basename(packageDir);
     const previousHash = existsSync(cachePath) ? readFileSync(cachePath, 'utf8') : undefined;
-    const currentHash = await computeBuildHash(packageDir, files, emitConfig);
+    const currentHash = await computeBuildHash(packageDir, files, emitConfig, compilerVersion);
     if (previousHash === currentHash) {
         if (outputPresent) {
             console.info(`${SKIPPED_ICON} ${packageName}: No changes detected. Skipping build.`);
@@ -235,7 +237,7 @@ async function writeBuildCache(cachePath, hash) {
     await writeFile(cachePath, hash);
 }
 function assertSupportedTypeScript() {
-    const [majorPart, minorPart] = ts.versionMajorMinor.split('.');
+    const [majorPart, minorPart] = ts.versionMajorMinor.split('.', 2);
     const major = majorPart === undefined ? 0 : Number(majorPart);
     const minor = minorPart === undefined ? 0 : Number(minorPart);
     const tooOld = major < MINIMUM_TYPESCRIPT_MAJOR || (major === MINIMUM_TYPESCRIPT_MAJOR && minor < MINIMUM_TYPESCRIPT_MINOR);

package/dist/esm/commands/clean.js

@@ -1,9 +1,10 @@
 import { rm } from 'node:fs/promises';
 import path from 'node:path';
 import { loadConfig } from "../config.js";
-import { findContainingPackageDir, findMonorepoRoot, getWorkspacePackageDirs } from "../context.js";
+import { findContainingPackageDir } from "../context.js";
 import { applyDevBin, buildWorkspaceRegistry, hasIntegrationTestConfig, resolveScript } from "../resolver.js";
 import { runCommand } from "../runner.js";
+import { findMonorepoRoot, getWorkspacePackageDirs } from "../workspace.js";
 import { resolveBuildCachePath } from "./build.js";
 const CLEAN_ICON = '🧹';
 const CLEAN_COMMAND = 'clean';

package/dist/esm/commands/ensure-prepublish-hooks.js

@@ -1,8 +1,8 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
-import { getWorkspacePackageDirs } from "../context.js";
 import { readPackageJson } from "../helpers/package-json.js";
 import { isObject } from "../helpers/type-guards.js";
+import { getWorkspacePackageDirs } from "../workspace.js";
 export const DEFAULT_HOOK = 'npm run build';
 export function ensurePrepublishHooks(monorepoRoot, options) {
     const hookCommand = options.command ?? DEFAULT_HOOK;

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

@@ -0,0 +1,12 @@
+import type { Writable } from 'node:stream';
+export interface SpawnOutcome {
+    status: number | null;
+    error?: Error | undefined;
+}
+export interface RunTazeOptions {
+    resolveCliPath?: () => string;
+    spawn?: (nodePath: string, argv: string[]) => SpawnOutcome;
+    stderr?: Writable;
+}
+export declare function runTaze(args: string[], options?: RunTazeOptions): number;
+export declare function resolveTazeCliPath(): string;