@williamthorsen/nmr 0.41.0 → 0.42.0

package/.readyup/manifest.json

@@ -3,7 +3,8 @@
   "kits": [
     {
       "bundledDependencies": {
-        "@williamthorsen/toolbelt.errors": "0.8.1"
+        "@williamthorsen/toolbelt.errors": "0.8.2",
+        "yaml": "2.9.1"
       },
       "checklists": [
         "nmr"
@@ -11,12 +12,12 @@
       "esbuildVersion": "0.28.2",
       "inputs": [
         {
-          "hash": "5f7bd316",
+          "hash": "50b5aac3",
           "kind": "module",
           "path": "kits/default.ts"
         },
         {
-          "hash": "00e9a998",
+          "hash": "fa3a837f",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -46,10 +47,10 @@
       ],
       "name": "default",
       "path": "kits/default.js",
-      "readyupVersion": "0.38.0",
+      "readyupVersion": "0.40.0",
       "source": "kits/default.ts",
-      "sourceHash": "5f7bd316",
-      "targetHash": "69936c4f"
+      "sourceHash": "50b5aac3",
+      "targetHash": "3bc734de"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.42.0 — 2026-10-08
+
+### 🎉 Features
+
+- Adds the kit check `catalogued dependencies use catalog:`, which warns about every manifest, the root's included, that declares a literal version or range for a package listed by the default `catalog` or a named `catalogs` entry in `pnpm-workspace.yaml`, and exempts `peerDependencies` and specifiers that name a protocol, such as `workspace:` or `npm:`. (#958)
+- Adds the kit check `no package.json declares a workspaces field`, which warns about every `package.json` in the tree that declares `workspaces`, a field that pnpm ignores because it reads workspace globs only from `pnpm-workspace.yaml`. (#958)
+- Adds a `Package scripts:` section to the `nmr` listing, which shows each script declared by the current scope's `package.json` under a name that the active registry does not contain, hooks such as `build:pre` included and npm and pnpm lifecycle scripts excluded. (#960)
+- Makes Prettier a dependency of `@williamthorsen/nmr`, so that `pnpm dlx --package @williamthorsen/nmr nmr-fmt --check` (or `--write`) formats a git repository that has nothing installed, while a repository that installs its own Prettier keeps formatting with that copy. (#961)
+- Makes `nmr-fmt` apply the house config from `@williamthorsen/nmr/prettier`, shell plugin included, when Prettier does not find a config searching from the working directory, which also gives the house config to a repository whose only Prettier configs are in subdirectories below that directory. (#961)
+- Makes `typescript` an optional peer of `@williamthorsen/nmr`, so that installing nmr no longer requires it, and makes `nmr-compile` report a missing `typescript` together with the version range that it supports. (#961)
+
+### 🐛 Bug fixes
+
+- Fixes the issue that `nmr fmt` and `nmr fmt:check` aborted with a load failure when a file listed by git could not be stat'ed because of `EACCES` or `EPERM`, such as a tracked `.envrc` under a sandbox that denies reads of `.env*` files; `nmr-fmt` now skips each such file and names it on stderr. (#959)
+- Fixes the issue that `nmr-fmt` reported any other stat failure on a listed file, such as `ELOOP` from a symlink loop, as a load failure; the run now fails with an error that names the path. (#959)
+- Fixes the issue that `nmr-compile` failed with a `TypeError` under TypeScript 7, which it now rejects with an error naming the supported range, `>=5.7 <7`. (#961)
+- Fixes the issue that `nmr fmt` and `nmr fmt:check` failed in a repository that commits a symlink, because `nmr-fmt` passed the symlink to Prettier, which rejects an explicitly named symlink even when `.prettierignore` lists it. (#968)
+
+### ♻️ Refactoring
+
+- Replaces the hand-written atomic cache write and directory walks in `nmr-core` and `nmr` with `writeAtomic` and `findDirectoryChainMatch` from `@williamthorsen/toolbelt.filesystem`, which both packages now declare in `dependencies`. (#966)
+
+### 📚 Documentation
+
+- Updates the readyup examples in the `nmr`, `release-kit`, and `v11y-check` READMEs and the `nmr` rulebook to use the `sources` key and `rdy run --sources`, and states that `--sources` needs readyup 0.40 or later. (#977)
+
 ## 0.41.0 — 2026-10-02
 
 ### 🎉 Features

package/README.md

@@ -5,11 +5,23 @@
 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.41.0 (2026-10-02)
+## Release notes — v0.42.0 (2026-10-08)
 
 ### 🎉 Features
 
-- Adds a hint to `nmr` that, when a command fails, names any of nmr's own flags written after the command name and shows the corrected invocation, such as `nmr -q check`. (#956)
+- Adds the kit check `catalogued dependencies use catalog:`, which warns about every manifest, the root's included, that declares a literal version or range for a package listed by the default `catalog` or a named `catalogs` entry in `pnpm-workspace.yaml`, and exempts `peerDependencies` and specifiers that name a protocol, such as `workspace:` or `npm:`. (#958)
+- Adds the kit check `no package.json declares a workspaces field`, which warns about every `package.json` in the tree that declares `workspaces`, a field that pnpm ignores because it reads workspace globs only from `pnpm-workspace.yaml`. (#958)
+- Adds a `Package scripts:` section to the `nmr` listing, which shows each script declared by the current scope's `package.json` under a name that the active registry does not contain, hooks such as `build:pre` included and npm and pnpm lifecycle scripts excluded. (#960)
+- Makes Prettier a dependency of `@williamthorsen/nmr`, so that `pnpm dlx --package @williamthorsen/nmr nmr-fmt --check` (or `--write`) formats a git repository that has nothing installed, while a repository that installs its own Prettier keeps formatting with that copy. (#961)
+- Makes `nmr-fmt` apply the house config from `@williamthorsen/nmr/prettier`, shell plugin included, when Prettier does not find a config searching from the working directory, which also gives the house config to a repository whose only Prettier configs are in subdirectories below that directory. (#961)
+- Makes `typescript` an optional peer of `@williamthorsen/nmr`, so that installing nmr no longer requires it, and makes `nmr-compile` report a missing `typescript` together with the version range that it supports. (#961)
+
+### 🐛 Bug fixes
+
+- Fixes the issue that `nmr fmt` and `nmr fmt:check` aborted with a load failure when a file listed by git could not be stat'ed because of `EACCES` or `EPERM`, such as a tracked `.envrc` under a sandbox that denies reads of `.env*` files; `nmr-fmt` now skips each such file and names it on stderr. (#959)
+- Fixes the issue that `nmr-fmt` reported any other stat failure on a listed file, such as `ELOOP` from a symlink loop, as a load failure; the run now fails with an error that names the path. (#959)
+- Fixes the issue that `nmr-compile` failed with a `TypeError` under TypeScript 7, which it now rejects with an error naming the supported range, `>=5.7 <7`. (#961)
+- Fixes the issue that `nmr fmt` and `nmr fmt:check` failed in a repository that commits a symlink, because `nmr-fmt` passed the symlink to Prettier, which rejects an explicitly named symlink even when `.prettierignore` lists it. (#968)
 <!-- /section:release-notes -->
 
 ## Installation
@@ -29,6 +41,16 @@ nmr installs as a workspace bin, so the bare `nmr` command works only when the s
 
 > **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.
 
+### Formatting without installing
+
+A git repository that does not install nmr, or that has no `package.json` at all, can still format its files:
+
+```bash
+pnpm dlx --package @williamthorsen/nmr nmr-fmt --check # or --write
+```
+
+When the repository doesn't have a Prettier config, the [house config](docs/prettier.md) applies, shell scripts included.
+
 ## Quick start
 
 nmr works without any configuration. It includes built-in scripts for common monorepo tasks.
@@ -243,7 +265,7 @@ Wiring the sync to `postinstall` keeps it current without a hand-run command:
 
 ## Conformance checks
 
-nmr publishes a `readyup` kit that checks a consuming repo against the current release: the shared Vitest and Prettier configs, the workspace layout, the root script registry, the test-file conventions ([tier names](docs/vitest.md#test-tiers) and `__tests__` placement), that the repo's own suite gates them, that every `bin` target is a committed wrapper rather than build output that pnpm cannot link at install time, that `files` covers the output that each wrapper loads, that the root install scripts do not run `lefthook install` without `lefthook check-install`, and that the `package.json` files in the tree do not declare a `pnpm` field, from which pnpm 11 does not read any key. Those settings belong in `pnpm-workspace.yaml`, and `pnpx codemod run pnpm-v10-to-v11` moves them. The kit is included in the package, so it checks against the nmr version installed rather than whatever a repository ref happens to point at, and a tier added or renamed in nmr takes effect in the repo when it upgrades nmr. A repo that declares the [conventions check](docs/vitest.md#gating-the-test-file-conventions) gates both conventions in its own test run, and the kit then leaves the test files to that check.
+nmr publishes a `readyup` kit that checks a consuming repo against the current release: the shared Vitest and Prettier configs, the workspace layout, the root script registry, the test-file conventions ([tier names](docs/vitest.md#test-tiers) and `__tests__` placement), that the repo's own suite gates them, that every `bin` target is a committed wrapper rather than build output that pnpm cannot link at install time, that `files` covers the output that each wrapper loads, that the root install scripts do not run `lefthook install` without `lefthook check-install`, and that the `package.json` files in the tree declare neither a `pnpm` field, from which pnpm 11 does not read any key, nor a `workspaces` field, which pnpm ignores. Those settings belong in `pnpm-workspace.yaml`, and `pnpx codemod run pnpm-v10-to-v11` moves the `pnpm` field's. It also checks that every manifest declares a package listed by a `pnpm-workspace.yaml` catalog as `catalog:` rather than as a literal version. A peer range is exempt, and a version that must differ belongs in a named catalog, referenced as `catalog:<name>`. The kit is included in the package, so it checks against the nmr version installed rather than whatever a repository ref happens to point at, and a tier added or renamed in nmr takes effect in the repo when it upgrades nmr. A repo that declares the [conventions check](docs/vitest.md#gating-the-test-file-conventions) gates both conventions in its own test run, and the kit then leaves the test files to that check.
 
 Add `readyup` as a devDependency, then name nmr in its config:
 
@@ -252,17 +274,17 @@ Add `readyup` as a devDependency, then name nmr in its config:
 import { defineRdyConfig } from 'readyup';
 
 export default defineRdyConfig({
-  packages: ['@williamthorsen/nmr'],
+  sources: ['npm:@williamthorsen/nmr'],
 });
 ```
 
 ```bash
-rdy run --packages                       # every kit that each listed package publishes
+rdy run --sources                        # every kit that each listed package publishes
 rdy run --from npm:@williamthorsen/nmr   # nmr's kit alone, without the config entry
 rdy list --from npm:@williamthorsen/nmr  # what nmr publishes
 ```
 
-`--packages` is the form that survives nmr publishing further kits. Both need `readyup` 0.23 or later, and `@williamthorsen/nmr` as a _direct_ devDependency: A strict pnpm layout links nothing else into the project, so a transitive copy is unreachable.
+`--sources` is the form that survives nmr publishing further kits. `--sources` needs `readyup` 0.40 or later and `--from` needs 0.23 or later, and both need `@williamthorsen/nmr` as a _direct_ devDependency: A strict pnpm layout links nothing else into the project, so a transitive copy is unreachable.
 
 ## Documentation
 

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 program supplied by the environment), `localhost` (a service 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 --packages` 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 program supplied by the environment), `localhost` (a service 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/cli-fmt.js

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

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

@@ -1,4 +1,5 @@
 import { type OutputStyle } from '@williamthorsen/nmr-core';
+import type * as TypeScript from 'typescript';
 import { type BuildOptions } from './build-output.js';
 /**
  * The toolchain from which a build's emit comes: the resolved compiler and the nmr running it. `computeBuildHash`
@@ -12,6 +13,12 @@ export interface BuildToolchain {
 /** What a build needs beyond its sources: the options shaping the emit, and the style in which it reports. */
 export interface BuildPackageOptions extends BuildOptions {
     style: OutputStyle;
+    /**
+     * Overridable so that a missing `typescript` peer is reachable without uninstalling it.
+     *
+     * @internal
+     */
+    loadTypeScript?: () => Promise<typeof TypeScript>;
 }
 /**
  * Compiles a package's `src` tree to `dist/esm` with the TypeScript compiler API, emitting `.js` and
@@ -30,6 +37,14 @@ export declare function buildPackage(packageDir: string, options: BuildPackageOp
  * detected.
  */
 export declare function computeBuildHash(packageDir: string, files: string[], emitConfig: object, toolchain: BuildToolchain): Promise<string>;
+/**
+ * Loads the compiler API on which every other function in this module relies, reporting a missing `typescript` peer
+ * with the version that `nmr-compile` requires. `buildPackage` calls it first; a caller of another export calls it
+ * beforehand.
+ *
+ * @internal
+ */
+export declare function loadCompiler(loadTypeScript?: () => Promise<typeof TypeScript>): Promise<void>;
 /**
  * Resolves a package's full tsconfig `extends` chain, returning every config file in it (the leaf `tsconfig.json` and
  * each base that it transitively extends, up to the repo root) as paths relative to `packageDir`.

package/dist/esm/commands/build.js

@@ -2,18 +2,22 @@ import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { readFile, rename, rm } from 'node:fs/promises';
 import path from 'node:path';
-import { formatGlyphLine, readCacheEntry, STATUS_GLYPHS, writeCacheEntry, } from '@williamthorsen/nmr-core';
+import { formatGlyphLine, hasErrnoCode, readCacheEntry, STATUS_GLYPHS, writeCacheEntry, } from '@williamthorsen/nmr-core';
 import { glob } from 'glob';
-import * as ts from 'typescript';
 import { NMR_GLYPHS } from "../glyphs.js";
 import { resolveConfigPath } from "../helpers/config-path.js";
 import { DEFAULT_ENTRY_GLOBS, DEFAULT_IGNORE_PATTERNS, DEFAULT_OUTDIR, hasExpectedBuildOutput, resolveBuildCachePath, resolveScratchDirs, resolveToolchainFingerprint, } from "./build-output.js";
 const SOURCE_ROOT = 'src';
 const MINIMUM_TYPESCRIPT_MAJOR = 5;
 const MINIMUM_TYPESCRIPT_MINOR = 7;
+const UNSUPPORTED_TYPESCRIPT_MAJOR = 7;
+const SUPPORTED_TYPESCRIPT_RANGE = `>=${MINIMUM_TYPESCRIPT_MAJOR}.${MINIMUM_TYPESCRIPT_MINOR} <${UNSUPPORTED_TYPESCRIPT_MAJOR}`;
+const INSTALL_TYPESCRIPT_GUIDANCE = "Install a version in that range as the 'typescript' peer dependency.";
 const TS_EXTENSION = '.ts';
 const JS_EXTENSION = '.js';
+let ts;
 export async function buildPackage(packageDir, options) {
+    await loadCompiler(options.loadTypeScript);
     assertSupportedTypeScript();
     const cachePath = resolveBuildCachePath(packageDir);
     const outdir = options.outdir ?? DEFAULT_OUTDIR;
@@ -56,6 +60,18 @@ export async function computeBuildHash(packageDir, files, emitConfig, toolchain)
     hash.update(toolchain.fingerprint);
     return hash.digest('hex');
 }
+export async function loadCompiler(loadTypeScript = importTypeScript) {
+    try {
+        ts = await loadTypeScript();
+    }
+    catch (error) {
+        if (hasErrnoCode(error, 'ERR_MODULE_NOT_FOUND') && error.message.includes("'typescript'")) {
+            throw new Error(`nmr-compile requires TypeScript ${SUPPORTED_TYPESCRIPT_RANGE}, but 'typescript' could not be resolved. ` +
+                INSTALL_TYPESCRIPT_GUIDANCE, { cause: error });
+        }
+        throw error;
+    }
+}
 export function resolveTsconfigChain(packageDir, configFileName = 'tsconfig.json') {
     const resolvedChain = [];
     const seen = new Set();
@@ -291,14 +307,19 @@ async function detectBuildChanges(packageDir, files, emitConfig, toolchain, cach
     console.info(formatGlyphLine(NMR_GLYPHS, style, 'package', `${packageName}: Changes detected.`));
     return { changed: true, currentHash };
 }
+async function importTypeScript() {
+    return await import('typescript');
+}
 function assertSupportedTypeScript() {
-    const [majorPart, minorPart] = ts.versionMajorMinor.split('.', 2);
+    const versionMajorMinor = ts.versionMajorMinor;
+    const version = ts.version;
+    const [majorPart, minorPart] = typeof versionMajorMinor === 'string' ? 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);
-    if (tooOld) {
-        throw new Error(`nmr-compile requires TypeScript >=${MINIMUM_TYPESCRIPT_MAJOR}.${MINIMUM_TYPESCRIPT_MINOR} for ` +
-            `rewriteRelativeImportExtensions, but found ${ts.version}. Upgrade the 'typescript' peer dependency.`);
+    if (tooOld || major >= UNSUPPORTED_TYPESCRIPT_MAJOR) {
+        throw new Error(`nmr-compile requires TypeScript ${SUPPORTED_TYPESCRIPT_RANGE}, but found ` +
+            `${typeof version === 'string' ? version : 'a version without the compiler API'}. ${INSTALL_TYPESCRIPT_GUIDANCE}`);
     }
 }
 function collectAliasPrefixes(compilerOptions) {

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

@@ -4,6 +4,12 @@ export interface FormatTargets {
     files: string[];
     /** Absolute paths to every `.prettierignore` governing the repository, root-most first. */
     ignorePaths: string[];
+    /** Listed paths that this process is denied access to, each with the errno code that its stat raised. */
+    unreadableFiles: UnreadableFile[];
+}
+export interface UnreadableFile {
+    file: string;
+    code: string;
 }
 export type ResolveTargetsResult = {
     ok: true;
@@ -13,13 +19,14 @@ export type ResolveTargetsResult = {
     error: string;
 };
 /**
- * Formats or checks the files that git reports for `cwd`, and returns the exit code to report.
+ * Formats or checks the files that git reports for `cwd`, and returns the exit code to report. A repository
+ * without a Prettier config of its own is formatted with the house config.
  *
  * Trailing arguments are git pathspecs, not Prettier flags; an unrecognized option is rejected rather
  * than passed along, since git would read it as a pathspec matching nothing and the run would report
  * success over an empty selection.
  */
-export declare function runFmt(argv: string[], cwd?: string): number;
+export declare function runFmt(argv: string[], cwd?: string): Promise<number>;
 /**
  * Resolves what Prettier should format and which ignore files govern it, using git rather than Prettier's
  * own discovery. Prettier reads `.gitignore` and `.prettierignore` from the working directory only, so a
@@ -31,11 +38,16 @@ export declare function runFmt(argv: string[], cwd?: string): number;
  *
  * `pathspecs` narrow the selection and are passed to git verbatim: They have git pathspec semantics rather
  * than shell glob semantics.
+ *
+ * A listed path that this process is denied access to is set aside in `unreadableFiles`; any other stat failure
+ * fails the resolution.
  */
 export declare function resolveFormatTargets(cwd: string, pathspecs?: string[]): ResolveTargetsResult;
 /** @internal */
 export interface RunPrettierOptions {
     cliPath: string;
+    /** Passed as `--config`, which replaces Prettier's own config discovery. */
+    configPath?: string | undefined;
     mode: FormatMode;
     files: string[];
     ignorePaths: string[];

package/dist/esm/commands/fmt.js

@@ -1,23 +1,26 @@
 import { Buffer } from 'node:buffer';
 import { spawnSync } from 'node:child_process';
-import { readFileSync, statSync } from 'node:fs';
+import { lstatSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import process from 'node:process';
-import { reportError } from '@williamthorsen/nmr-core';
+import { fileURLToPath } from 'node:url';
+import { hasErrnoCode, reportError } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { isObject } from "../helpers/type-guards.js";
 const IGNORE_FILENAME = '.prettierignore';
 const LIST_FILES_ARGS = ['ls-files', '-z', '--cached', '--others', '--exclude-standard'];
 const IGNORE_FILE_PATHSPEC = `*${IGNORE_FILENAME}`;
+const UNREADABLE_CODES = ['EACCES', 'EPERM'];
 const PRETTIER_PACKAGE = 'prettier';
-const PRETTIER_RANGE = '>=3.9.5 <4';
+const DEFAULT_CONFIG_PATH = fileURLToPath(new URL(`../prettier-default-config${path.extname(fileURLToPath(import.meta.url))}`, import.meta.url));
 const ARGUMENT_BUDGET_BYTES = 100_000;
 const USAGE = 'Usage: nmr-fmt (--check | --write) [pathspec...]';
 const MODE_ARGS = {
     check: ['--check'],
     write: ['--list-different', '--write'],
 };
-export function runFmt(argv, cwd = process.cwd()) {
+export async function runFmt(argv, cwd = process.cwd()) {
     const parsedArgs = parseFmtArgs(argv);
     if (!parsedArgs.ok) {
         reportError(`nmr-fmt: ${parsedArgs.error}`);
@@ -29,7 +32,10 @@ export function runFmt(argv, cwd = process.cwd()) {
         reportError(`nmr-fmt: ${resolvedTargets.error}`);
         return 1;
     }
-    const { files, ignorePaths } = resolvedTargets.targets;
+    const { files, ignorePaths, unreadableFiles } = resolvedTargets.targets;
+    for (const { file, code } of unreadableFiles) {
+        process.stderr.write(`nmr-fmt: skipped ${file}, which cannot be read (${code})\n`);
+    }
     if (files.length === 0) {
         if (parsedArgs.pathspecs.length > 0) {
             reportError(`nmr-fmt: the pathspecs did not match any formattable file: ${parsedArgs.pathspecs.join(', ')}`);
@@ -37,12 +43,24 @@ export function runFmt(argv, cwd = process.cwd()) {
         }
         return 0;
     }
-    const cli = resolvePrettierCli();
+    const cli = resolvePrettierCli(cwd);
     if (!cli.ok) {
         reportError(`nmr-fmt: ${cli.error}`);
         return 1;
     }
-    return runPrettier({ cliPath: cli.cliPath, mode: parsedArgs.mode, files, ignorePaths, cwd });
+    const repositoryConfig = await findRepositoryConfig(cli.manifestPath, cwd);
+    if (!repositoryConfig.ok) {
+        reportError(`nmr-fmt: ${repositoryConfig.error}`);
+        return 1;
+    }
+    return runPrettier({
+        cliPath: cli.cliPath,
+        configPath: repositoryConfig.found ? undefined : DEFAULT_CONFIG_PATH,
+        mode: parsedArgs.mode,
+        files,
+        ignorePaths,
+        cwd,
+    });
 }
 export function resolveFormatTargets(cwd, pathspecs = []) {
     const toplevel = runGit(['rev-parse', '--show-toplevel'], cwd);
@@ -55,21 +73,47 @@ export function resolveFormatTargets(cwd, pathspecs = []) {
     const ignoreFiles = runGit([...LIST_FILES_ARGS, '--', IGNORE_FILE_PATHSPEC], repositoryRoot);
     if (!ignoreFiles.ok)
         return ignoreFiles;
+    const files = [];
+    const unreadableFiles = [];
+    const listedPaths = dedupe(splitNulSeparated(listedFiles.stdout));
+    for (const file of listedPaths) {
+        const status = classifyListedFile(cwd, file);
+        switch (status.kind) {
+            case 'excluded':
+                break;
+            case 'failed':
+                return { ok: false, error: status.error };
+            case 'formattable':
+                files.push(file);
+                break;
+            case 'unreadable':
+                unreadableFiles.push({ file, code: status.code });
+                break;
+        }
+    }
     const discoveredIgnorePaths = splitNulSeparated(ignoreFiles.stdout)
         .filter((file) => path.basename(file) === IGNORE_FILENAME)
         .map((file) => path.resolve(repositoryRoot, file));
     return {
         ok: true,
         targets: {
-            files: dedupe(splitNulSeparated(listedFiles.stdout))
-                .filter((file) => isFormattableFile(cwd, file))
-                .toSorted(),
+            files: files.toSorted(),
             ignorePaths: dedupe([path.join(repositoryRoot, IGNORE_FILENAME), ...discoveredIgnorePaths]),
+            unreadableFiles,
         },
     };
 }
-function isFormattableFile(cwd, file) {
-    return statSync(path.resolve(cwd, file), { throwIfNoEntry: false })?.isFile() === true;
+function classifyListedFile(cwd, file) {
+    try {
+        const stats = lstatSync(path.resolve(cwd, file), { throwIfNoEntry: false });
+        return stats?.isFile() === true ? { kind: 'formattable' } : { kind: 'excluded' };
+    }
+    catch (error) {
+        const code = UNREADABLE_CODES.find((candidate) => hasErrnoCode(error, candidate));
+        if (code !== undefined)
+            return { kind: 'unreadable', code };
+        return { kind: 'failed', error: `could not stat ${file}: ${describeError(error)}` };
+    }
 }
 function parseFmtArgs(argv) {
     let mode;
@@ -93,30 +137,45 @@ function parseFmtArgs(argv) {
     }
     return { ok: true, mode, pathspecs };
 }
-function resolvePrettierCli() {
+function resolvePrettierCli(cwd) {
     const missingResult = {
         ok: false,
-        error: `\`${PRETTIER_PACKAGE}\` (${PRETTIER_RANGE}) could not be resolved. Install it in this repository.`,
+        error: `\`${PRETTIER_PACKAGE}\` could not be resolved from this repository or from nmr's own installation, which declares it as a dependency. Reinstall \`@williamthorsen/nmr\`.`,
     };
-    let manifestPath;
-    try {
-        manifestPath = createRequire(import.meta.url).resolve(`${PRETTIER_PACKAGE}/package.json`);
-    }
-    catch {
+    const manifestPath = resolveFrom(path.join(cwd, 'package.json'), `${PRETTIER_PACKAGE}/package.json`) ??
+        resolveFrom(import.meta.url, `${PRETTIER_PACKAGE}/package.json`);
+    if (manifestPath === undefined)
         return missingResult;
-    }
     const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
     if (!isObject(manifest))
         return missingResult;
     const bin = isObject(manifest['bin']) ? manifest['bin'][PRETTIER_PACKAGE] : manifest['bin'];
     if (typeof bin !== 'string')
         return missingResult;
-    return { ok: true, cliPath: path.resolve(path.dirname(manifestPath), bin) };
+    return { ok: true, cliPath: path.resolve(path.dirname(manifestPath), bin), manifestPath };
+}
+async function findRepositoryConfig(manifestPath, cwd) {
+    try {
+        const prettier = createRequire(manifestPath)(PRETTIER_PACKAGE);
+        const resolveConfigFile = isObject(prettier) ? prettier['resolveConfigFile'] : undefined;
+        if (typeof resolveConfigFile !== 'function') {
+            return {
+                ok: false,
+                error: `\`${PRETTIER_PACKAGE}\` at ${path.dirname(manifestPath)} does not export \`resolveConfigFile\`.`,
+            };
+        }
+        const configFile = await Reflect.apply(resolveConfigFile, undefined, [path.join(cwd, 'placeholder')]);
+        return { ok: true, found: configFile !== null };
+    }
+    catch (error) {
+        return { ok: false, error: `could not search for a Prettier config: ${describeError(error)}` };
+    }
 }
 export function runPrettier(options) {
-    const { cliPath, mode, files, ignorePaths, cwd, budgetBytes = ARGUMENT_BUDGET_BYTES } = options;
+    const { cliPath, configPath, mode, files, ignorePaths, cwd, budgetBytes = ARGUMENT_BUDGET_BYTES } = options;
     const prettierArgs = [
         cliPath,
+        ...(configPath === undefined ? [] : ['--config', configPath]),
         '--ignore-unknown',
         ...ignorePaths.flatMap((ignorePath) => ['--ignore-path', ignorePath]),
         ...MODE_ARGS[mode],
@@ -153,6 +212,14 @@ function batchWithinBudget(files, budgetBytes) {
         batches.push(batch);
     return batches;
 }
+function resolveFrom(parent, specifier) {
+    try {
+        return createRequire(parent).resolve(specifier);
+    }
+    catch {
+        return undefined;
+    }
+}
 function runGit(args, cwd) {
     const result = spawnSync('git', args, { cwd, encoding: 'utf8' });
     if (result.error) {

package/dist/esm/help.d.ts

@@ -1,8 +1,8 @@
 import type { NmrConfig } from './types.js';
 /**
- * Generates the help text for the `nmr` CLI. Renders only nmr commands:
- * names from the workspace and root registries, excluding hooks (`*:pre`,
- * `*:post`).
+ * Generates the help text for the `nmr` CLI. Renders the names from the
+ * workspace and root registries, excluding hooks (`*:pre`, `*:post`), and
+ * the scripts that the package at `packageDir` adds to them.
  *
  * When `packageDir` is provided, tier-3 entries from that package's
  * `package.json:scripts` that match a registry name in the active section
@@ -11,5 +11,9 @@ import type { NmrConfig } from './types.js';
  * active section is the root section when `shouldUseRoot` is true (root cwd
  * or `-w`), otherwise the workspace section. A footnote is appended once
  * if any override marker was rendered.
+ *
+ * Every other entry, a hook included, is listed under `Package scripts:`
+ * unless it is an npm or pnpm lifecycle script or the active registry
+ * contains its name.
  */
 export declare function generateHelp(config: NmrConfig, packageDir: string | undefined, shouldUseRoot: boolean): string;

package/dist/esm/help.js

@@ -1,6 +1,28 @@
 import { isHookName } from "./helpers/hook-name.js";
 import { OUTPUT_STYLE_ENV_VAR, OUTPUT_STYLE_FLAG } from "./output-style.js";
 import { buildRootRegistry, buildWorkspaceRegistry, describeScript, isSelfReferential, readPackageJsonScripts, } from "./resolver.js";
+const LIFECYCLE_SCRIPT_NAMES = new Set([
+    'dependencies',
+    'install',
+    'pnpm:devPreinstall',
+    'postinstall',
+    'postpack',
+    'postprepare',
+    'postpublish',
+    'postuninstall',
+    'postversion',
+    'preinstall',
+    'prepack',
+    'prepare',
+    'preprepare',
+    'prepublish',
+    'prepublishOnly',
+    'preuninstall',
+    'preversion',
+    'publish',
+    'uninstall',
+    'version',
+]);
 export function generateHelp(config, packageDir, shouldUseRoot) {
     const lines = [
         'Usage: nmr [flags] <command> [args...]',
@@ -23,7 +45,8 @@ export function generateHelp(config, packageDir, shouldUseRoot) {
         '',
         'Workspace commands:',
     ];
-    const overrides = packageDir === undefined ? {} : collectOverrides(packageDir);
+    const packageScripts = packageDir === undefined ? {} : readRunnableScripts(packageDir);
+    const overrides = collectOverrides(packageScripts);
     let hadOverride = false;
     const workspaceRegistry = filterHooks(buildWorkspaceRegistry(config));
     const workspaceMarkedNames = !shouldUseRoot ? applyOverrides(workspaceRegistry, overrides) : new Set();
@@ -36,24 +59,44 @@ export function generateHelp(config, packageDir, shouldUseRoot) {
     if (rootMarkedNames.size > 0)
         hadOverride = true;
     formatRegistry(rootRegistry, rootMarkedNames, lines);
+    const activeRegistry = shouldUseRoot ? buildRootRegistry(config) : buildWorkspaceRegistry(config);
+    const unregisteredScripts = collectUnregisteredScripts(packageScripts, activeRegistry);
+    if (Object.keys(unregisteredScripts).length > 0) {
+        lines.push('', 'Package scripts:');
+        formatRegistry(unregisteredScripts, new Set(), lines);
+    }
     if (hadOverride) {
         lines.push('', '* Overridden by package.json');
     }
     return lines.join('\n');
 }
-function collectOverrides(packageDir) {
+function collectOverrides(packageScripts) {
+    const candidateOverrides = {};
+    for (const [name, value] of Object.entries(packageScripts)) {
+        if (!isHookName(name))
+            candidateOverrides[name] = value;
+    }
+    return candidateOverrides;
+}
+function collectUnregisteredScripts(packageScripts, registry) {
+    const unregisteredScripts = {};
+    for (const [name, value] of Object.entries(packageScripts)) {
+        if (Object.hasOwn(registry, name) || LIFECYCLE_SCRIPT_NAMES.has(name))
+            continue;
+        unregisteredScripts[name] = value;
+    }
+    return unregisteredScripts;
+}
+function readRunnableScripts(packageDir) {
     const scripts = readPackageJsonScripts(packageDir);
     if (!scripts)
         return {};
-    const candidateOverrides = {};
+    const runnableScripts = {};
     for (const [name, value] of Object.entries(scripts)) {
-        if (isHookName(name))
-            continue;
-        if (isSelfReferential(value, name, packageDir))
-            continue;
-        candidateOverrides[name] = value;
+        if (!isSelfReferential(value, name, packageDir))
+            runnableScripts[name] = value;
     }
-    return candidateOverrides;
+    return runnableScripts;
 }
 function applyOverrides(registry, overrides) {
     const markedNames = new Set();

package/dist/esm/prettier-default-config.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The house config that `nmr-fmt` passes to Prettier by path when the repository does not have a config of its own.
+ * It is a default export because that is the export that Prettier reads from a config file.
+ */
+declare const _default: import("prettier").Config;
+export default _default;

package/dist/esm/prettier-default-config.js

@@ -0,0 +1,2 @@
+import { definePrettierConfig } from "./prettier.js";
+export default definePrettierConfig();