@williamthorsen/nmr 0.19.0 → 0.21.0

package/README.md

@@ -1,27 +1,44 @@
 # @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.19.0 (2026-07-22)
+## Release notes — v0.21.0 (2026-07-30)
 
 ### 🎉 Features
 
-- 🚨 **Breaking:** Replace the dependency commands with nmr upgrade (#491)
+- Add a shared Vitest config export (#526)
 
-  Adds `nmr upgrade` as an ergonomic wrapper for displaying and applying available dependency upgrades. Taze is used under the hood to set a soaking period (customizable, defaulting to 7 days) before recently published dependencies will be accepted.
+  Adds a shared Vitest configuration that can be used by repos that use `nmr`. Tests are now sorted into three named categories (unit, integration, and app), so that a run can target or skip a single category. A second variant excludes all tests in workspace packages, allowing the monorepo's own root-level tests to be run separately.
 
-  Removes the four dependency commands it replaces: `outdated`, `outdated:latest`, `update`, and `update:latest`.
+- 🚨 **Breaking:** Retire the Vitest config-file variants from nmr's defaults (#533)
+
+  Packages no longer need extra Vitest config files to keep integration tests out of the default test run. Integration tests are now recognized by an `*.int.test.ts` suffix, and every package gets the same five commands: `test`, `test:all`, `test:coverage`, `test:integration`, and `test:watch`. The same five commands work from the monorepo root. A Vitest run that collects no test files now passes instead of failing. Consumers should migrate the Vitest config when upgrading.
+
+### 🐛 Bug fixes
+
+- Apply ignore rules from any working directory when formatting (#535)
+
+  Fixes an issue where `nmr fmt` and `nmr fmt:check` did not apply a pattern from a package's `.gitignore` or `.prettierignore` when the run started at the monorepo root, so files a package excluded could fail a root-level format gate while passing a package-scoped one. Untracked files that git does not ignore are now formatted alongside tracked ones, and a run started outside a git repository now fails instead of reporting a clean pass over nothing. Trailing arguments to `nmr fmt` are git pathspecs rather than Prettier flags; one that matches no formattable file now fails instead of exiting silently.
 <!-- /section:release-notes -->
 
 ## Installation
 
-Requires Node.js 24 or later.
+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.
@@ -39,7 +56,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.
@@ -48,19 +65,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 --project '!integration'` (that package only) |
+| Anywhere, with `--workspace-root` | Root scripts      | Monorepo root     | Root tests + `pnpm --recursive exec nmr test`                   |
+
+Relative paths in a script resolve against that working directory, not the invocation directory.
 
-Use `-w` to escape package context:
+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:
@@ -92,6 +116,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:
@@ -137,6 +163,44 @@ 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:
@@ -148,6 +212,8 @@ For example, if a workspace script resolves to `my-cli --verbose`, nmr rewrites
 | `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
@@ -156,8 +222,6 @@ nmr upgrade major    # major upgrades, still inside the ceilings
 nmr upgrade --write  # apply the proposals to package.json
 ```
 
-> **Note:** `-w` means different things on either side of the command. `nmr upgrade -w` passes `--write` to the upgrade tool; `nmr -w upgrade` is nmr's own `--workspace-root` flag and applies no write. Prefer the long forms to keep them apart. Run the root-context commands from the monorepo root: like nmr's other `root:` scripts, they take the current directory as their starting point.
-
 ### Configuring upgrades
 
 Declare version ceilings in a `taze.config.ts` at the monorepo root:
@@ -185,38 +249,48 @@ These scripts are available out of the box. Repo-wide config (tier 2) and per-pa
 
 ### Workspace scripts
 
-| Command         | Runs                                                     |
-| --------------- | -------------------------------------------------------- |
-| `build`         | `compile`                                                |
-| `check`         | `typecheck`, `fmt:check`, `lint:check`, `test`           |
-| `check:strict`  | `typecheck`, `fmt:check`, `lint:strict`, `test:coverage` |
-| `clean`         | `nmr-clean`                                              |
-| `compile`       | `nmr-compile`                                            |
-| `fix`           | `lint`, `fmt`                                            |
-| `fix:check`     | `fmt:check`, `lint:check`                                |
-| `fmt`           | `prettier --list-different --write .`                    |
-| `fmt:check`     | `prettier --check .`                                     |
-| `lint`          | `eslint --fix .`                                         |
-| `lint:check`    | `eslint .`                                               |
-| `lint:strict`   | `strict-lint`                                            |
-| `test`          | `pnpm exec vitest`                                       |
-| `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
-
-A package gets this variant automatically when it contains a `vitest.integration.config.ts` file: `test` and `test:coverage` run the standalone (non-integration) suite, and integration tests run only when invoked explicitly. Activation is detected per package, so it applies under the recursive `nmr ci` fan-out. Opting in requires **both** `vitest.integration.config.ts` and `vitest.standalone.config.ts`, since the standalone scripts reference the latter.
-
-| Command            | Runs                                                               |
-| ------------------ | ------------------------------------------------------------------ |
-| `test`             | `pnpm exec vitest --config=vitest.standalone.config.ts`            |
-| `test:all`         | `pnpm exec vitest`                                                 |
-| `test:coverage`    | `pnpm exec vitest --config=vitest.standalone.config.ts --coverage` |
-| `test:integration` | `pnpm exec vitest --config=vitest.integration.config.ts`           |
-| `test:watch`       | `pnpm exec vitest --config=vitest.standalone.config.ts --watch`    |
+| Command            | Runs                                                     |
+| ------------------ | -------------------------------------------------------- |
+| `build`            | `compile`                                                |
+| `check`            | `typecheck`, `fmt:check`, `lint:check`, `test`           |
+| `check:strict`     | `typecheck`, `fmt:check`, `lint:strict`, `test:coverage` |
+| `clean`            | `nmr-clean`                                              |
+| `compile`          | `nmr-compile`                                            |
+| `fix`              | `lint`, `fmt`                                            |
+| `fix:check`        | `fmt:check`, `lint:check`                                |
+| `fmt`              | `nmr-fmt --write`                                        |
+| `fmt:check`        | `nmr-fmt --check`                                        |
+| `lint`             | `eslint --fix .`                                         |
+| `lint:check`       | `eslint .`                                               |
+| `lint:strict`      | `strict-lint`                                            |
+| `test`             | `pnpm exec vitest --project '!integration'`              |
+| `test:all`         | `pnpm exec vitest`                                       |
+| `test:coverage`    | `pnpm exec vitest --project '!integration' --coverage`   |
+| `test:integration` | `pnpm exec vitest --project integration`                 |
+| `test:watch`       | `pnpm exec vitest --project '!integration' --watch`      |
+| `typecheck`        | `tsgo --noEmit`                                          |
+| `upgrade`          | `nmr-taze --include-locked`                              |
+| `view-coverage`    | `open coverage/index.html`                               |
+
+`fmt` and `fmt:check` select their files through git rather than by walking the directory, which is what makes a package-level run and a root-level run apply the same ignore rules — see [file selection](#file-selection).
+
+#### Test selections
+
+Every package resolves the same five test commands. Nothing is detected on disk: the commands select [Vitest projects](#shared-vitest-config), so a package separates its integration tests by naming them `*.int.test.ts`, not by carrying extra config files.
+
+| To run                              | Command            |
+| ----------------------------------- | ------------------ |
+| Everything except integration tests | `test`             |
+| Integration tests alone             | `test:integration` |
+| Every project                       | `test:all`         |
+
+`test` negates `integration` rather than naming the code-only projects, so a category added later joins the default run instead of being dropped from it.
+
+`test:coverage` and `test:watch` are the same selection as `test` in a different mode. There are no `test:integration --coverage` equivalents because none are needed: everything after a command name is forwarded untouched, so `nmr test:integration --coverage` already works.
+
+To narrow to a single project, go through `test:all`: `nmr test:all --project app`. Narrowing through `test` does not work, because a second `--project` widens the filter rather than restricting it.
+
+A run that collects no test files passes. That is what lets `nmr test:integration` fan out across a monorepo in which most packages have no integration tests, and it means a package with no tests at all needs no `"test": ""` override.
 
 ### Root scripts
 
@@ -225,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
@@ -244,11 +318,19 @@ A package gets this variant automatically when it contains a `vitest.integration
 
 #### Test
 
-| Command         | Runs                                                       |
-| --------------- | ---------------------------------------------------------- |
-| `test`          | `nmr root:test && pnpm --recursive exec nmr test`          |
-| `test:coverage` | `nmr root:test && pnpm --recursive exec nmr test:coverage` |
-| `test:watch`    | `vitest --watch`                                           |
+The same five names the workspace registry carries, so a command means the same thing from the monorepo root as from inside a package. Each fans out to root-level files and every workspace package.
+
+| Command            | Runs                                                                      |
+| ------------------ | ------------------------------------------------------------------------- |
+| `test`             | `nmr root:test && pnpm --recursive exec nmr test`                         |
+| `test:all`         | `nmr root:test:all && pnpm --recursive exec nmr test:all`                 |
+| `test:coverage`    | `nmr root:test && pnpm --recursive exec nmr test:coverage`                |
+| `test:integration` | `nmr root:test:integration && pnpm --recursive exec nmr test:integration` |
+| `test:watch`       | `vitest --project '!integration' --watch`                                 |
+
+`test:coverage` chains `root:test` rather than a `root:test:coverage`, because the root config reports no coverage of its own; packages cover their own sources.
+
+`test:watch` is the exception to the fan-out shape, and deliberately omits `--config`: bare `vitest` at the monorepo root resolves the root `vitest.config.ts`, whose projects then cover the whole tree in one process. A chain like the others would never advance past its first watcher. To watch root-level files alone, run `nmr root:test --watch`.
 
 #### Typecheck
 
@@ -266,12 +348,18 @@ A package gets this variant automatically when it contains a `vitest.integration
 
 #### Format
 
-| Command     | Runs                                  |
-| ----------- | ------------------------------------- |
-| `fmt`       | `prettier --list-different --write .` |
-| `fmt:all`   | `fmt`, `fmt:sh`                       |
-| `fmt:check` | `prettier --check .`                  |
-| `fmt:sh`    | `shfmt --write **/*.sh`               |
+| Command     | Runs                    |
+| ----------- | ----------------------- |
+| `fmt`       | `nmr-fmt --write`       |
+| `fmt:all`   | `fmt`, `fmt:sh`         |
+| `fmt:check` | `nmr-fmt --check`       |
+| `fmt:sh`    | `shfmt --write **/*.sh` |
+
+#### File selection
+
+`fmt` and `fmt:check` format the files git reports: tracked files, plus untracked files git does not ignore. Prettier reads `.gitignore` and `.prettierignore` from the working directory alone, so a pattern in `packages/<pkg>/.gitignore` never reaches a run started at the monorepo root. git knows the whole hierarchy, including `.git/info/exclude` and `core.excludesFile`, and every `.prettierignore` in the tree is discovered from the repository root, so package-level exclusions apply from any directory as well.
+
+A file git ignores is never formatted, even when named directly. Trailing arguments are git pathspecs rather than Prettier flags, so `nmr fmt:check packages/nmr` narrows the run, while an unrecognized option and a pathspec matching no formattable file both fail it. Running outside a git repository fails rather than reporting a clean run.
 
 #### Audit
 
@@ -283,9 +371,9 @@ A package gets this variant automatically when it contains a `vitest.integration
 
 #### Dependencies
 
-| Command   | Runs                                    |
-| --------- | --------------------------------------- |
-| `upgrade` | `nmr-taze --include-locked --recursive` |
+| Command   | Runs                                                            |
+| --------- | --------------------------------------------------------------- |
+| `upgrade` | `nmr-report-overrides && nmr-taze --include-locked --recursive` |
 
 See [dependency upgrades](#dependency-upgrades) for the workflow and its configuration.
 
@@ -293,23 +381,24 @@ See [dependency upgrades](#dependency-upgrades) for the workflow and its configu
 
 These scripts operate on root-level code only (not workspace packages):
 
-| Command            | Runs                                                          |
-| ------------------ | ------------------------------------------------------------- |
-| `root:check`       | `root:typecheck`, `fmt:check`, `root:lint:check`, `root:test` |
-| `root:lint`        | `eslint --fix --ignore-pattern 'packages/**' .`               |
-| `root:lint:check`  | `eslint --ignore-pattern '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`                                   |
+| Command                 | Runs                                                               |
+| ----------------------- | ------------------------------------------------------------------ |
+| `root:check`            | `root:typecheck`, `fmt:check`, `root:lint:check`, `root:test`      |
+| `root:lint`             | `eslint --fix --ignore-pattern 'packages/**' .`                    |
+| `root:lint:check`       | `eslint --ignore-pattern 'packages/**' .`                          |
+| `root:lint:strict`      | `strict-lint --ignore-pattern 'packages/**' .`                     |
+| `root:test`             | `vitest --config ./vitest.root.config.ts --project '!integration'` |
+| `root:test:all`         | `vitest --config ./vitest.root.config.ts`                          |
+| `root:test:integration` | `vitest --config ./vitest.root.config.ts --project integration`    |
+| `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
 
@@ -319,11 +408,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                                 | —       |
@@ -337,14 +428,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
@@ -353,7 +444,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
@@ -378,13 +469,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
 
@@ -406,9 +500,26 @@ Compile a single package's `src` tree to `dist/esm` with the TypeScript compiler
 nmr-compile
 ```
 
+### `nmr-fmt`
+
+Format, or check the formatting of, the files git reports for the working directory. Exactly one of `--check` and `--write` is required; a bare invocation prints usage and exits non-zero rather than defaulting to a mutation. `--write` also lists the files it rewrote. This is what `fmt` and `fmt:check` resolve to, in both registries.
+
+The selection is tracked files plus untracked files git does not ignore, scoped to the working directory, with every `.prettierignore` in the tree discovered from the repository root and passed to Prettier explicitly — see [file selection](#file-selection) for what that buys. Paths the index names but the filesystem does not have (a file deleted but not yet staged) and submodule gitlinks are both dropped, so neither reaches Prettier.
+
+Trailing arguments are git pathspecs, not Prettier flags: they narrow the selection, an unrecognized option is rejected rather than forwarded, and pathspecs that match no formattable file fail rather than passing quietly.
+
+`prettier` is an optional peer dependency (`>=3.9.5 <4`); the consuming repo provides it, and it is resolved through the module graph rather than from `PATH`, so the copy that runs is the one the repo declares and not whichever `prettier` happens to come first. A repository's formatter has to be the one its editor and pre-commit hook also run, which is why nmr takes it from the consumer instead of bundling a copy. It is optional because a repo can use nmr purely as a script runner; one that formats without a resolvable Prettier gets a message naming the package and the range.
+
+The floor is a currency policy, not a capability boundary. What the design requires is `--ignore-path` honouring every flag rather than only the last, so a repository-root ignore file passed alongside a package-level one is not silently dropped — Prettier has done that since 3.0.0, while 2.x honoured only the final flag. The floor sits at the current release because every consuming repo tracks it; lowering it to `>=3.0.0` would cost correctness nothing.
+
+```bash
+nmr-fmt --check
+nmr-fmt --write packages/nmr
+```
+
 ### `nmr-taze`
 
-Run the [taze](https://github.com/antfu-collective/taze) dependency-upgrade tool, forwarding every argument to it untouched. This is what the `upgrade` and `root:upgrade` scripts resolve to — see [dependency upgrades](#dependency-upgrades) for the workflow.
+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.
 
@@ -436,25 +547,118 @@ 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';
+
+const monorepoRoot = findMonorepoRoot();
+
+for (const packageDir of getWorkspacePackageDirs(monorepoRoot)) {
+  // assert something about every workspace package
+}
+```
+
+`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`.
+
+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.
 
-runConsistencyChecks();
+## Shared Vitest config
+
+Every repo consuming nmr otherwise writes and maintains its own Vitest config. The `@williamthorsen/nmr/vitest` subpath publishes that config as a factory, so a repo declares only what it customizes:
+
+```ts
+// vitest.config.ts
+import { defineVitestConfig } from '@williamthorsen/nmr/vitest';
+
+export default defineVitestConfig();
+```
+
+`vitest` is a peer dependency (`>=4.0.0 <5`), declared optional — the consuming repo provides it, and repos that never import this subpath are unaffected.
+
+### Test categories
+
+The config declares three projects, named for what the tests cover:
+
+| Project       | Matches                                | Covers                                   |
+| ------------- | -------------------------------------- | ---------------------------------------- |
+| `unit`        | every test file the others don't claim | source code                              |
+| `integration` | `*.int.test.{ts,tsx}`                  | behavior beyond source code              |
+| `app`         | `*.app.test.{ts,tsx}`                  | the app's own tooling, e.g. drift checks |
+
+All three match only under a `__tests__` directory. Select them at run time with `--project`, which accepts negation:
+
+```bash
+vitest --project '!integration'   # everything except integration tests
+vitest --project integration      # integration tests alone
+vitest                            # every project
 ```
 
-This verifies:
+`unit` is defined by subtracting the other categories rather than by an allow-list of suffixes, so a file such as `parser.smoke.test.ts` runs under `unit` instead of being silently dropped.
+
+### Customizing by scope
+
+Vitest applies some options at the root of a `projects` config and others per project, and placing one at the wrong level is silent rather than loud. The factory therefore takes two separate override surfaces instead of one merged config:
+
+```ts
+export default defineVitestConfig({
+  // Vite-level options, plus the test options Vitest honours only at the root.
+  root: { resolve: { conditions: ['development'] } },
+  // Applied to every project.
+  project: { setupFiles: ['./vitest.setup.ts'] },
+});
+```
+
+`root` is typed to accept only the options that work at the root, so writing a per-project option there is a compile error rather than a setting that never runs. Both surfaces merge into the generated config rather than replacing it, so overriding one coverage field leaves the rest intact.
+
+Arrays concatenate rather than replace. `exclude` and `setupFiles` therefore add to what the config already declares, and neither seam can narrow `include` or drop a default exclusion. Adding an `include` pattern through `project` widens all three projects at once, so a file matching it is collected by each and runs three times.
+
+### Root-scoped tests
+
+A monorepo's own root-level tests need a second config, because the package config is found by walking up from a package directory:
+
+```ts
+// vitest.root.config.ts
+import { defineRootVitestConfig } from '@williamthorsen/nmr/vitest';
+
+export default defineRootVitestConfig();
+```
+
+This variant reads `pnpm-workspace.yaml` and excludes every workspace package from all three projects, so a root run covers only root-level files. It reports no coverage of its own — packages cover their own sources.
+
+The monorepo root is located by walking up from the working directory, and every project is pinned to it, so the exclusions hold wherever the run is invoked from. Pass `startDir` to locate it from somewhere else:
+
+```ts
+export default defineRootVitestConfig({ startDir: import.meta.dirname });
+```
+
+### Migrating from the config-file variants
+
+nmr once selected a package's test scripts by looking for a `vitest.integration.config.ts` on disk, which meant three config files per package that separated its integration tests. Those files are no longer consulted. **Migrate the config and the scripts together**: one without the other leaves the repo in one of the two states below.
+
+1. Replace the repo's root `vitest.config.ts` with `defineVitestConfig()`, and its root-scoped config with `defineRootVitestConfig()`.
+2. Delete every `vitest.integration.config.ts` and `vitest.standalone.config.ts`, plus any per-package `vitest.config.ts` that only re-exports an ancestor. Vitest resolves config by walking up from the run root, so those are redundant.
+3. Rename integration tests to `*.int.test.ts` and tooling or drift tests to `*.app.test.ts`.
+4. Drop any hand-copied `test*` entries from `package.json`, which now shadow the defaults.
+
+Until step 1 is done, an upgraded nmr behaves as follows against a config that declares no projects:
+
+| Command                      | Result                                                                                                                                             |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `nmr test` / `test:coverage` | **Succeeds, and runs integration tests too.** The separation is lost with no error, because `--project '!integration'` matches nothing to exclude. |
+| `nmr test:integration`       | **Fails** with `No projects matched the filter "integration"`.                                                                                     |
 
-- pnpm version matches between `package.json` and GitHub workflow
-- Node.js version matches between `.tool-versions` and GitHub workflow
+The second is the reliable signal that migration is incomplete. The first is silent, so do not treat a green `nmr test` as evidence that the move succeeded.

package/bin/nmr-fmt.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+try {
+  await import('../dist/esm/cli-fmt.js');
+} catch (error) {
+  if (error.code === 'ERR_MODULE_NOT_FOUND') {
+    process.stderr.write('nmr-fmt: build output not found — run `pnpm run build` first\n');
+  } else {
+    process.stderr.write(`nmr-fmt: 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-fmt.js

@@ -0,0 +1,3 @@
+import process from 'node:process';
+import { runFmt } from "./commands/fmt.js";
+process.exitCode = runFmt(process.argv.slice(2), process.cwd());

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' },
 };