@williamthorsen/nmr 1.0.0 → 2.0.1

package/dist/esm/commands/publish-output.js

@@ -0,0 +1,66 @@
+import { existsSync } from 'node:fs';
+import { rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { UserError } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { getCompiler } from "./compiler.js";
+import { isWithin } from "./rewrite-specifiers.js";
+export async function discardScratchDirs(emitDir) {
+    try {
+        await removeScratchDirs(emitDir);
+    }
+    catch {
+    }
+}
+export async function publishOutput(emitDir, stagedFiles) {
+    if (stagedFiles.size === 0) {
+        await rm(emitDir, { force: true, recursive: true });
+        return 0;
+    }
+    writeStagedOutput(stagedFiles, emitDir);
+    await swapIntoPlace(emitDir);
+    return stagedFiles.size;
+}
+export async function removeScratchDirs(emitDir) {
+    const { previousDir, stagingDir } = resolveScratchDirs(emitDir);
+    await rm(previousDir, { force: true, recursive: true });
+    await rm(stagingDir, { force: true, recursive: true });
+}
+export function resolveScratchDirs(emitDir) {
+    const parent = path.dirname(emitDir);
+    const name = path.basename(emitDir);
+    return {
+        previousDir: path.join(parent, `.${name}.previous`),
+        stagingDir: path.join(parent, `.${name}.staging`),
+    };
+}
+async function swapIntoPlace(emitDir) {
+    const { previousDir, stagingDir } = resolveScratchDirs(emitDir);
+    const hadPreviousOutput = existsSync(emitDir);
+    if (hadPreviousOutput) {
+        await rename(emitDir, previousDir);
+    }
+    try {
+        await rename(stagingDir, emitDir);
+    }
+    catch (error) {
+        if (hadPreviousOutput && !existsSync(emitDir)) {
+            await rename(previousDir, emitDir);
+        }
+        throw new UserError(`failed to move the built output into ${emitDir}: ${describeError(error)}`, {
+            cause: error,
+        });
+    }
+    await discardScratchDirs(emitDir);
+}
+function writeStagedOutput(stagedFiles, emitDir) {
+    const ts = getCompiler();
+    const { stagingDir } = resolveScratchDirs(emitDir);
+    for (const [fileName, file] of stagedFiles) {
+        if (!isWithin(emitDir, fileName)) {
+            throw new Error(`the compiler emitted ${fileName}, which is outside the output directory ${emitDir}. ` +
+                "Verify the resolved tsconfig's 'outDir' and 'declarationDir'.");
+        }
+        ts.sys.writeFile(path.join(stagingDir, path.relative(emitDir, fileName)), file.text, file.writeByteOrderMark);
+    }
+}

package/dist/esm/commands/report-catalog.d.ts

@@ -8,3 +8,8 @@ import { type OutputStyle } from '@williamthorsen/nmr-core';
  * pass runs, to keep the reader from taking that result to mean that every dependency is up to date.
  */
 export declare function reportCatalog(cwd: string, style: OutputStyle): void;
+/**
+ * Runs `nmr-report-catalog` against `argv` from `cwd` and returns the exit code to report. The command takes neither
+ * an option nor an operand, so anything but `--help` is a usage error and reports nothing.
+ */
+export declare function runReportCatalog(argv: string[], cwd: string): Promise<number>;

package/dist/esm/commands/report-catalog.js

@@ -1,8 +1,12 @@
+import process from 'node:process';
 import { formatGlyphLine } from '@williamthorsen/nmr-core';
+import { defineCommand, runCli } from '@williamthorsen/nmr-core/cli';
+import { NMR_REPORT_CATALOG_BIN } from "../bins.js";
 import { findContainingPackageDir } from "../context.js";
 import { NMR_GLYPHS } from "../glyphs.js";
 import { DEPENDENCY_FIELDS, readPackageJson } from "../helpers/package-json.js";
 import { reportClosing } from "../helpers/reportClosing.js";
+import { resolveBinStyles } from "../resolveBinStyles.js";
 import { findMonorepoRoot, getWorkspacePackageDirs } from "../workspace.js";
 const CATALOG_PROTOCOL = 'catalog:';
 export function reportCatalog(cwd, style) {
@@ -21,6 +25,21 @@ export function reportCatalog(cwd, style) {
     }
     reportClosing(formatGlyphLine(NMR_GLYPHS, style, 'catalog', describeCatalog(dependencies.length, monorepoRoot)), console.warn);
 }
+export async function runReportCatalog(argv, cwd) {
+    const command = defineCommand({
+        summary: 'Report the catalogued dependencies that a package-scoped upgrade does not read',
+        run: () => {
+            reportCatalog(cwd, resolveBinStyles().stderr);
+            return 0;
+        },
+    });
+    return runCli(argv, command, {
+        name: NMR_REPORT_CATALOG_BIN,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        baseDir: cwd,
+    });
+}
 function describeCatalog(count, monorepoRoot) {
     const subject = count === 1 ? '1 catalogued dependency went' : `${count} catalogued dependencies went`;
     const object = count === 1 ? 'it' : 'them';

package/dist/esm/commands/report-overrides.d.ts

@@ -4,3 +4,8 @@ import { type OutputStyle } from '@williamthorsen/nmr-core';
  * `pnpm.overrides` block left behind in the root `package.json`.
  */
 export declare function reportOverrides(monorepoRoot: string, style: OutputStyle): void;
+/**
+ * Runs `nmr-report-overrides` against `argv` for the monorepo containing `cwd` and returns the exit code to report.
+ * The command takes neither an option nor an operand, so anything but `--help` is a usage error and reports nothing.
+ */
+export declare function runReportOverrides(argv: string[], cwd: string): Promise<number>;

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

@@ -1,8 +1,12 @@
+import process from 'node:process';
 import { formatGlyphLine, UserError } from '@williamthorsen/nmr-core';
+import { defineCommand, runCli } from '@williamthorsen/nmr-core/cli';
+import { NMR_REPORT_OVERRIDES_BIN } from "../bins.js";
 import { NMR_GLYPHS } from "../glyphs.js";
 import { getPnpmOverrides, readPackageJson } from "../helpers/package-json.js";
 import { reportClosing } from "../helpers/reportClosing.js";
-import { readWorkspaceOverrides } from "../workspace.js";
+import { resolveBinStyles } from "../resolveBinStyles.js";
+import { findMonorepoRoot, readWorkspaceOverrides } from "../workspace.js";
 export function reportOverrides(monorepoRoot, style) {
     const declaredOverrides = listEntries(readWorkspaceOverrides(monorepoRoot));
     if (declaredOverrides.length > 0) {
@@ -14,6 +18,21 @@ export function reportOverrides(monorepoRoot, style) {
     }
     rejectLegacyOverrides(monorepoRoot);
 }
+export async function runReportOverrides(argv, cwd) {
+    const command = defineCommand({
+        summary: 'Report the pnpm overrides that the monorepo declares',
+        run: () => {
+            reportOverrides(findMonorepoRoot(cwd), resolveBinStyles().stderr);
+            return 0;
+        },
+    });
+    return runCli(argv, command, {
+        name: NMR_REPORT_OVERRIDES_BIN,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        baseDir: cwd,
+    });
+}
 function describeOverrides(count) {
     return count === 1
         ? '1 override is active. Check whether it is still needed.'

package/dist/esm/config-validation.js

@@ -1,12 +1,11 @@
 import { isRecord, UserError } from '@williamthorsen/nmr-core';
 import { assertResolvableCheckCacheCommands } from "./config-check-cache.js";
-import { isStringRecord } from "./helpers/type-guards.js";
 import { findUnexpressibleToken } from "./steps.js";
 import { formatVerbosityRejection, isCommandVerbosity } from "./verbosity.js";
 export const CONFIG_TIERS = {
     root: {
         label: 'a monorepo-root config',
-        honoredKeys: ['checkCache', 'delegate', 'devBin', 'output', 'rootScripts', 'selfHostedRunner', 'workspaceScripts'],
+        honoredKeys: ['checkCache', 'delegate', 'output', 'rootScripts', 'selfHostedRunner', 'workspaceScripts'],
         elsewhere: "the package's own config",
     },
     workspace: {
@@ -44,9 +43,6 @@ export function validateConfig(value, configPath, baseDir) {
         config.checkCache = checkCache;
     if (value['delegate'] !== undefined)
         config.delegate = validateDelegateField(value['delegate'], configPath);
-    const devBin = validateStringRecordField(value, 'devBin', configPath);
-    if (devBin)
-        config.devBin = devBin;
     const output = validateOutputField(value, configPath);
     if (output)
         config.output = output;
@@ -225,12 +221,3 @@ function validateScriptField(value, fieldName, configPath) {
     assertValidElements(scripts, fieldName, configPath);
     return scripts;
 }
-function validateStringRecordField(value, fieldName, configPath) {
-    if (!Object.hasOwn(value, fieldName) || value[fieldName] === undefined) {
-        return undefined;
-    }
-    if (!isStringRecord(value[fieldName])) {
-        throw new UserError(`Invalid nmr config at ${configPath}: \`${fieldName}\` must be a Record<string, string>`);
-    }
-    return value[fieldName];
-}

package/dist/esm/config.d.ts

@@ -6,7 +6,7 @@ import type { NmrConfig } from './types.js';
  */
 export declare function loadConfig(baseDir: string): Promise<NmrConfig>;
 /**
- * Loads the monorepo-root `.config/nmr.config.ts`, the tier that feeds script resolution and `devBin`.
+ * Loads the monorepo-root `.config/nmr.config.ts`, the tier that feeds script resolution.
  * Returns an empty config if the file doesn't exist.
  *
  * Throws on a recognized key that this tier does not honor. `build` governs one package's compile, which reads the

package/dist/esm/crossing-diagnostics.d.ts

@@ -24,7 +24,7 @@ export declare function assertNoSelfReference(options: {
  *
  * Ahead of the gate, so that a command that usually skips still reports its crossing. A `--log` reports
  * none, running nothing that could cross. Reads the resolved steps rather than the full chain: the line names
- * a declaration to edit, and a hook, a passthrough, and a `devBin` substitution are none.
+ * a declaration to edit, and neither a hook nor a passthrough is one.
  */
 export declare function reportNmrCrossing(options: {
     config: NmrConfig;

package/dist/esm/resolver.d.ts

@@ -1,18 +1,6 @@
 import { type ScriptRegistry, type ScriptValue } from './resolve-scripts.js';
 import { type Step } from './steps.js';
 import type { NmrConfig } from './types.js';
-/**
- * Replaces the first token of a command with a `devBin` substitute.
- * Relative paths in the replacement are resolved from `monorepoRoot`.
- */
-export declare function applyDevBin(command: string, devBin: Record<string, string> | undefined, monorepoRoot: string): string;
-/**
- * Applies a `devBin` substitution to each opaque step, leaving nmr's own compositions alone.
- *
- * A structural step names a command that nmr resolves for itself, so substituting its first token would replace
- * the `nmr` that runs the composite rather than the leaf tool that `devBin` documents replacing.
- */
-export declare function applyDevBinToSteps(steps: readonly Step[], devBin: Record<string, string> | undefined, monorepoRoot: string): readonly Step[];
 /**
  * Where a resolved script was read from.
  *

package/dist/esm/resolver.js

@@ -1,44 +1,9 @@
 import { readFileSync } from 'node:fs';
-import path from 'node:path';
 import { hasErrnoCode, isRecord } from '@williamthorsen/nmr-core';
 import { parsePackageJson, readScriptRecord, resolvePackageJsonPath } from "./helpers/package-json.js";
 import { getDefaultRootScripts, getDefaultWorkspaceScripts, } from "./resolve-scripts.js";
 import { composeNmrStep, readSelfReference } from "./steps.js";
 import { isMonorepoRoot } from "./workspace.js";
-export function applyDevBin(command, devBin, monorepoRoot) {
-    if (!devBin) {
-        return command;
-    }
-    const spaceIndex = command.indexOf(' ');
-    const firstToken = spaceIndex === -1 ? command : command.slice(0, spaceIndex);
-    const restOfCommand = spaceIndex === -1 ? '' : command.slice(spaceIndex);
-    const replacement = devBin[firstToken];
-    if (replacement === undefined) {
-        return command;
-    }
-    const resolvedReplacement = resolveReplacementPaths(replacement, monorepoRoot);
-    return resolvedReplacement + restOfCommand;
-}
-export function applyDevBinToSteps(steps, devBin, monorepoRoot) {
-    if (!devBin) {
-        return steps;
-    }
-    return steps.map((step) => step.kind === 'opaque' ? { kind: 'opaque', command: applyDevBin(step.command, devBin, monorepoRoot) } : step);
-}
-function resolveReplacementPaths(replacement, monorepoRoot) {
-    const tokens = replacement.split(' ');
-    return tokens
-        .map((token, index) => {
-        if (index === 0)
-            return token;
-        if (token.startsWith('-'))
-            return token;
-        if (!token.includes('/'))
-            return token;
-        return path.resolve(monorepoRoot, token);
-    })
-        .join(' ');
-}
 export function expandScript(script, isWorkspaceRoot) {
     if (typeof script === 'string') {
         return [{ kind: 'opaque', command: script }];

package/dist/esm/run-chain.d.ts

@@ -2,7 +2,7 @@ import { type OutputStyle } from '@williamthorsen/nmr-core';
 import type { TreeSnapshot } from './check-cache.js';
 import { type Invocation, type PhaseResult, type RunPlan } from './invocation.js';
 import type { ScriptRegistry } from './resolve-scripts.js';
-import { type ResolvedScript } from './resolver.js';
+import type { ResolvedScript } from './resolver.js';
 /**
  * Assembles the chain that a resolved script runs at this scope, the hooks wrapped around it included, and the key
  * under which a pass by that chain is recorded. Settles a no-op override and an argument that no step can take.

package/dist/esm/run-chain.js

@@ -9,7 +9,6 @@ import { quoteForShell } from "./helpers/quoteForShell.js";
 import { wrapWithHooks } from "./hooks.js";
 import { USAGE_EXIT_CODE } from "./invocation.js";
 import { reportVerdict } from "./presentation.js";
-import { applyDevBinToSteps } from "./resolver.js";
 import { dropRecursiveSteps, renderChain } from "./steps.js";
 export function assembleChain(options) {
     const { invocation, registry, resolvedScript, snapshot } = options;
@@ -21,9 +20,7 @@ export function assembleChain(options) {
         reportVerdict({ command, scope: invocation.scope, outcome: 'no-op', reason: noOpReason }, stdout, invocation.format, styles.stdout);
         return { settled: true, result: { exitCode: 0 } };
     }
-    const substitutedSteps = applyDevBinToSteps(runnableSteps, context.config.devBin, context.monorepoRoot);
-    const substitutedCommand = renderChain(substitutedSteps);
-    const bindResult = bindPassthrough(substitutedSteps, parsedArgs.passthrough, command);
+    const bindResult = bindPassthrough(runnableSteps, parsedArgs.passthrough, command);
     if (!bindResult.ok) {
         reportError(NMR_BIN, bindResult.error, stderr);
         return { settled: true, result: { exitCode: USAGE_EXIT_CODE } };
@@ -53,7 +50,6 @@ export function assembleChain(options) {
         monorepoRoot: context.monorepoRoot,
         snapshot,
         stderr,
-        substitution: substitutedCommand === resolvedCommand ? undefined : substitutedCommand,
     });
     return { settled: false, value: { commandString: fullCommand, key, ownSteps: mainSteps, steps: fullSteps } };
 }

package/dist/esm/types.d.ts

@@ -59,7 +59,6 @@ export interface NmrConfig {
      * config says. A delegation flag still sends a run elsewhere.
      */
     delegate?: false;
-    devBin?: Record<string, string>;
     output?: OutputConfig;
     workspaceScripts?: Record<string, ScriptValue>;
     rootScripts?: Record<string, ScriptValue>;

package/docs/check-cache.md

@@ -63,7 +63,6 @@ The gate never wrongly skips. When it cannot be sure, it does nothing and the co
 - When the monorepo root is not the git toplevel.
 - When a changed path cannot be read, contains a newline or bytes that are not UTF-8, or is neither a file nor a symlink (an untracked nested repository, for instance).
 - When the repository does not have a pnpm install to fingerprint.
-- Under a `devBin` substitution, which runs a binary built from a location that the tree id does not describe.
 - For any invocation carrying arguments after the command name, and for every step below it: the arguments narrow what runs, and a step served from a recorded pass is a step that did not.
 
 `NMR_DEBUG=1` reports why a run did not skip and why the cache did not apply.

package/docs/scripts.md

@@ -79,7 +79,7 @@ The line names the declaration to which it is an edit (the file, the field, and
 
 One kind of `package.json` entry is resolved in its own file: an entry whose whole value is `nmr <name>`, without flags, arguments, assignments, or a launcher, where `<name>` is a script in the same `package.json` that runs a command other than nmr and does not have a `:pre` or `:post` hook. Replace the entry's value with that command, and delete the script: `"build:pre": "nmr compile:ports"` beside `"compile:ports": "node scripts/compile-ports.ts"` becomes `"build:pre": "node scripts/compile-ports.ts"`. Keep the script when the registry also defines `<name>`, because the script then overrides nmr's own command. The script must come from the same file: Inlining a command that resolves from the registry would copy nmr's own command text into the package, where nmr's later changes do not reach it.
 
-nmr recognizes `nmr` in command position: at the start of a step, after an unquoted `&&`, `||`, `;`, `|`, or a newline, past any leading `NAME=value` assignments, and behind `npx`, `bunx`, or an `exec`, `dlx`, or `x` subcommand of `npm`, `pnpm`, `yarn`, or `bun`. This line reports a boundary rather than enforcing a rule: It covers a step that nmr runs as written, and only the reporting of the nested run is degraded. The line is also partial in three ways: a value-taking flag standing immediately before the program name hides it (`npx -p foo nmr`), a launcher outside that set goes unreported, and a `devBin` substitution that introduces `nmr` itself is not reported, the line being an edit to a declaration rather than to a substitution.
+nmr recognizes `nmr` in command position: at the start of a step, after an unquoted `&&`, `||`, `;`, `|`, or a newline, past any leading `NAME=value` assignments, and behind `npx`, `bunx`, or an `exec`, `dlx`, or `x` subcommand of `npm`, `pnpm`, `yarn`, or `bun`. This line reports a boundary rather than enforcing a rule: It covers a step that nmr runs as written, and only the reporting of the nested run is degraded. The line is also partial in two ways: a value-taking flag standing immediately before the program name hides it (`npx -p foo nmr`), and a launcher outside that set goes unreported.
 
 A [self-referential entry](#three-tier-override-system), in `package.json` or in `.config/nmr.config.ts`, is the shape that nmr cannot run as written, and it is rejected rather than reported. The same recognition finds it, so the same residuals apply: What goes unrecognized there re-enters nmr once, and the run then fails with an error naming the command and the directory that it re-entered.
 
@@ -125,7 +125,6 @@ A minimal `.config/nmr.config.ts` is in the [README](../README.md#configuration)
 | `delegate`         | `false`                                                                       | Keeps every check on the machine that has the tree, whatever `NMR_DELEGATE` or the [user config](delegate.md#the-user-config) says; a delegation flag still sends a run elsewhere (root config only)                                                                                                                                         |
 | `workspaceScripts` | `Record<string, ScriptValue>`                                                 | Scripts added or overridden in the workspace registry (tier 2)                                                                                                                                                                                                                                                                               |
 | `rootScripts`      | `Record<string, ScriptValue>`                                                 | Scripts added or overridden in the root registry (tier 2)                                                                                                                                                                                                                                                                                    |
-| `devBin`           | `Record<string, string>`                                                      | Map binary names to source-repo replacement commands                                                                                                                                                                                                                                                                                         |
 | `output`           | `{ commandVerbosity?: CommandVerbosity; extraAgentEnvVars?: string[] }`       | How loudly runs report command output; see [configuring](reporting.md#configuring)                                                                                                                                                                                                                                                           |
 | `selfHostedRunner` | `{ exempt: string }`                                                          | Why a qualifying repo keeps CI off the self-hosted runners; stops [nmr's readyup kit](../README.md#conformance-checks) from recommending `CI_RUNS_ON` (root config only). The reason is structural: a circular dependency, a platform or capacity the runners lack, or network reach. A missing tool is installed by a workflow step instead |
 
@@ -135,7 +134,7 @@ Each field belongs to exactly one tier, and nmr loads from a config only the fie
 
 ### Package-level configuration
 
-A package may have its own `.config/nmr.config.ts`, which `nmr-compile` reads from the package that it is compiling. This tier honors `build` alone; declaring `workspaceScripts`, `rootScripts`, or `devBin` there fails with a message naming them, rather than being quietly ignored: Those belong in the monorepo-root config, and a package that appeared to set them would otherwise build on settings that nothing applied. The monorepo-root config has the mirror restriction: `build` there fails the same way, since only a package's own config affects the compile.
+A package may have its own `.config/nmr.config.ts`, which `nmr-compile` reads from the package that it is compiling. This tier honors `build` alone; declaring `workspaceScripts`, `rootScripts`, or any other root-config field there fails with a message naming them, rather than being quietly ignored: Those belong in the monorepo-root config, and a package that appeared to set them would otherwise build on settings that nothing applied. The monorepo-root config has the mirror restriction: `build` there fails the same way, since only a package's own config affects the compile.
 
 ```ts
 // packages/my-package/.config/nmr.config.ts
@@ -150,23 +149,29 @@ export default defineConfig({
 
 > **Building nmr from source:** A config file that has to load while nmr itself is being built (before its `dist` exists) must use the type-only form, `import type { NmrConfig } from '@williamthorsen/nmr/config'` with `satisfies NmrConfig`, which does not produce a runtime import. `defineConfig` is unavailable at that moment, because it resolves through nmr's build output. Every other config, including every consumer's, imports nmr from an installed tarball that contains `dist`, and can use `defineConfig` freely.
 
-### `devBin`: source-repo binary substitution
+### Running a workspace bin from source
 
-During development of a CLI tool inside the monorepo, the published binary may not reflect the latest source changes. `devBin` maps a binary name to a replacement command that runs from source:
+A script that runs a bin built in this monorepo runs its build output, which can lag the source or be missing before the first build. To run the source instead, override the script whose value runs the bin, and call `node` on the bin's source file: Node runs TypeScript directly.
+
+A resolved script runs in the directory of its scope: A root script runs from the monorepo root, so a path relative to the root works there, and a workspace script runs in each package's directory, so the config builds an absolute path from `import.meta.dirname`, the config's own `.config` directory.
 
 ```ts
+// .config/nmr.config.ts
+import { defineConfig } from '@williamthorsen/nmr/config';
+
+const myCli = `${import.meta.dirname}/../packages/my-cli/src/cli.ts`;
+
 export default defineConfig({
-  devBin: {
-    'my-cli': 'tsx packages/my-cli/src/cli.ts',
+  rootScripts: {
+    'build:post': 'node packages/my-cli/src/cli.ts compile',
+  },
+  workspaceScripts: {
+    lint: `node "${myCli}" lint`,
   },
 });
 ```
 
-When nmr resolves a command whose first token matches a `devBin` key, it replaces that token with the mapped command. Arguments are preserved. Relative paths in the replacement are resolved from the monorepo root.
-
-For example, if a workspace script resolves to `my-cli --verbose`, nmr rewrites it to `tsx /absolute/path/to/packages/my-cli/src/cli.ts --verbose`.
-
-> **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.
+A package's own `package.json` script outranks the config (tier 3), so a package script that runs the bin is changed in that `package.json`.
 
 ## Default commands
 

package/docs/upgrades.md

@@ -130,7 +130,7 @@ These commands are available as `nmr` subcommands and as standalone `nmr-`-prefi
 
 ### `report-catalog`
 
-Report the dependencies that the current package takes from a [pnpm catalog](https://pnpm.io/catalogs), which a package-scoped `upgrade` cannot read (see [dependency upgrades](#dependency-upgrades) for why). Each line names the dependency, its `catalog:` specifier, and the monorepo root from which a covering pass runs. The workspace `upgrade` script runs it automatically, so a repo does not need to wire it up. The subcommand belongs to the workspace registry and runs from a package directory. The `nmr-report-catalog` bin reports nothing when run from the monorepo root, because a root-scoped pass reads the catalog itself.
+Report the dependencies that the current package takes from a [pnpm catalog](https://pnpm.io/catalogs), which a package-scoped `upgrade` cannot read (see [dependency upgrades](#dependency-upgrades) for why). Each line names the dependency, its `catalog:` specifier, and the monorepo root from which a covering pass runs. The workspace `upgrade` script runs it automatically, so a repo does not need to wire it up. The subcommand belongs to the workspace registry and runs from a package directory. The `nmr-report-catalog` bin reports nothing when run from the monorepo root, because a root-scoped pass reads the catalog itself. It takes no arguments: `--help` prints its usage, and any other argument is a usage error, which exits 2 without reporting.
 
 ```bash
 nmr report-catalog

package/docs/utilities.md

@@ -12,7 +12,7 @@ nmr-actionlint
 
 ## `nmr-clean`
 
-Remove a package's build output (`dist`) and its `nmr-compile` cache entries, the key and the recorded emit duration, so that the next build cannot skip on leftover state. Run from a package directory, it cleans that package; run from the monorepo root, it sweeps every workspace package in a single pass, running each package's resolved `clean`, so a package that overrides `clean`, in `.config/nmr.config.ts` or in its own `package.json`, gets its own command rather than the sweep. Removal is idempotent: Cleaning an unbuilt package is a silent no-op. This is the default `clean` script at both levels.
+Remove a package's build output (`dist`) and its `nmr-compile` cache entries, the key and the recorded emit duration, so that the next build cannot skip on leftover state. Run from a package directory, it cleans that package; run from the monorepo root, it sweeps every workspace package in a single pass, running each package's resolved `clean`, so a package that overrides `clean`, in `.config/nmr.config.ts` or in its own `package.json`, gets its own command rather than the sweep. Removal is idempotent: Cleaning an unbuilt package is a silent no-op. This is the default `clean` script at both levels. It takes no arguments: `--help` prints its usage, and any other argument is a usage error, which exits 2 without removing anything.
 
 ```bash
 nmr-clean
@@ -20,7 +20,7 @@ nmr-clean
 
 ## `nmr-compile`
 
-Compile a single package's `src` tree to `dist/esm` with the TypeScript compiler API, emitting `.js` from one program and `.d.ts` from a second that reuses it. The package's own `removeComments` governs the `.js` emit; the declarations emit forces it off, so `.d.ts` files keep their doc comments either way. Because the compiler parses each source file, every relative import form (static, re-export, dynamic `import()`, and bare side-effect) is rewritten from `.ts` or `.tsx` 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 every input is unchanged and the previous output is still on disk (the key 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.
+Compile a single package's `src` tree to `dist/esm` with the TypeScript compiler API, emitting `.js` from one program and `.d.ts` from a second that reuses it. The package's own `removeComments` governs the `.js` emit; the declarations emit forces it off, so `.d.ts` files keep their doc comments either way. Because the compiler parses each source file, every relative import form (static, re-export, dynamic `import()`, and bare side-effect) is rewritten from `.ts` or `.tsx` 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 every input is unchanged and the previous output is still on disk (the key 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. It takes no arguments: `--help` prints its usage, and any other argument is a usage error, which exits 2 without compiling.
 
 **What it compiles.** Entry points are `src/**/*.{ts,tsx}` less the directories that contain test scaffolding rather than published code: `__fixtures__/`, `__mocks__/`, `__tests__/`, and `test-utils/`. Add to that list per package with [`build.extraIgnorePatterns`](scripts.md#package-level-configuration). Ignoring a directory drops it as an _entry point_, not from the emit: The compiler still emits whatever the surviving entry points import, so a helper that production code uses is still compiled and the compiler never emits a dangling specifier in its importer. This list is deliberately not the Vitest [coverage exclusions](vitest.md#what-the-config-excludes): Helpers live in `test-utils/` precisely so that they stay covered.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "1.0.0",
+  "version": "2.0.1",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -80,9 +80,9 @@
     "!docs/*.v*.md"
   ],
   "dependencies": {
-    "@williamthorsen/nmr-core": "0.16.0",
-    "@williamthorsen/toolbelt.errors": "0.9.0",
-    "@williamthorsen/toolbelt.filesystem": "0.10.0",
+    "@williamthorsen/nmr-core": "0.16.1",
+    "@williamthorsen/toolbelt.errors": "0.9.1",
+    "@williamthorsen/toolbelt.filesystem": "0.10.1",
     "glob": "14.0.4",
     "prettier": "3.9.10",
     "prettier-plugin-sh": "0.20.2",
@@ -90,13 +90,13 @@
     "unconfig": "7.5.0"
   },
   "devDependencies": {
-    "@williamthorsen/toolbelt.testing": "0.8.0",
-    "@williamthorsen/toolbelt.vitest": "0.13.2",
+    "@williamthorsen/toolbelt.testing": "0.8.1",
+    "@williamthorsen/toolbelt.vitest": "0.13.3",
     "esbuild": "0.28.2",
-    "readyup": "0.45.0",
+    "readyup": "0.45.1",
     "tinyglobby": "0.2.17",
     "typescript": "6.0.3",
-    "vite": "8.3.6",
+    "vite": "8.3.7",
     "vitest": "5.1.0",
     "yaml": "2.9.1"
   },