@williamthorsen/nmr 0.13.0 → 0.14.1

package/AGENTS.md

@@ -4,7 +4,7 @@ source: '@williamthorsen/nmr@0.0.0-source'
 
 # nmr: agent guidance
 
-This file is managed by `@williamthorsen/nmr`. Do not edit — re-run `pnpm exec nmr sync-agent-files` after an nmr upgrade to refresh it.
+This file is managed by `@williamthorsen/nmr`. Do not edit — re-run `nmr sync-agent-files` after an nmr upgrade to refresh it.
 
 ## Discover scripts by running nmr
 
@@ -13,8 +13,20 @@ Run `nmr` with no command (from the monorepo root or any workspace package) to l
 ## Invocation rules
 
 - Use `nmr <command>` for anything nmr provides. Do not use `pnpm run <command>`.
-- Use `pnpm exec nmr`, not `npx nmr`. Inside git worktrees, `npx` can resolve a different nmr binary from outside the working tree.
-- If `nmr` itself fails to run (fresh clone, missing build output), run `pnpm run bootstrap` from the repo root first.
+- You can invoke nmr from the monorepo root or any workspace package.
+
+### How to make `nmr` resolvable
+
+`nmr` ships as a workspace bin. The bare `nmr` command works only when your shell can find `<root>/node_modules/.bin/nmr`. Choose one:
+
+- **direnv** (recommended for contributors). With [direnv](https://direnv.net/) installed, the repo's `.envrc` adds `node_modules/.bin` to your `PATH` automatically. From any subdirectory, bare `nmr` works.
+- **`pnpm exec nmr <command>`** — works without setup. pnpm resolves the bin from the workspace root.
+
+Avoid `npx nmr`. Inside git worktrees, `npx` can resolve a different nmr binary from outside the working tree.
+
+### Bootstrap fallback
+
+If `nmr` itself fails to run (fresh clone, missing build output), run `pnpm run bootstrap` from the repo root first.
 
 ## Root vs. workspace context
 

package/README.md

@@ -2,25 +2,7 @@
 
 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.13.0 (2026-05-04)
-
-### 🎉 Features
-
-- Add :pre and :post hook conventions to nmr commands (#339)
-
-  Adds `:pre` and `:post` hook conventions to nmr's command runner. Consumers can declare `X:pre` or `X:post` scripts that nmr runs automatically before and after script `X`. The hook commands are optional and ignored if missing. Hooks fire even when the main command is overridden, and direct invocations like `nmr build:pre` are treated as leaf operations rather than recursively cascading into `build:pre:pre` lookups.
-
-- Filter `nmr --help` to nmr commands (#348)
-
-  Restricts `nmr --help` to nmr commands only. Hook scripts (names ending in `:pre` or `:post`) are now hidden from help, and generic `package.json` lifecycle scripts (`prepare`, `postinstall`, `bootstrap`) no longer appear. When a `package.json` script overrides a built-in nmr command, the override is shown inline alongside the command name with a `*` marker, and a single `* Overridden by package.json` footnote is appended whenever any marker is rendered. Help also now reflects the active resolution context: invoked from a subpackage you see workspace-level overrides; invoked from the repo root (or with `-w`) you see root-level overrides.
-
-### 🐛 Bug fixes
-
-- Honor -w flag in composite-script step subprocesses (#346)
-
-  Fixes an issue where invoking `nmr -w <command>` from inside a workspace package, with `<command>` resolving to a composite (multi-step) script defined at the root level, failed with `Unknown command` for any step that was reachable only via the root script registry. The `-w` flag is now propagated to every step's subprocess invocation, so composite scripts run end-to-end regardless of which directory they are invoked from.
-<!-- /section:release-notes -->
+<!-- section:release-notes --><!-- /section:release-notes -->
 
 ## Installation
 
@@ -63,7 +45,7 @@ nmr's key feature is that the same command runs different scripts depending on w
 Use `-w` to escape package context:
 
 ```bash
-# From inside packages/core, run the root check suite
+# From inside packages/nmr-core, run the root check suite
 nmr -w check
 ```
 
@@ -238,11 +220,11 @@ Packages with a `vitest.integration.config.ts` file get different test commands.
 
 #### Audit
 
-| Command      | Runs                          |
-| ------------ | ----------------------------- |
-| `audit`      | `audit:prod`, `audit:dev`     |
-| `audit:dev`  | `pnpm exec audit-deps --dev`  |
-| `audit:prod` | `pnpm exec audit-deps --prod` |
+| Command      | Runs                      |
+| ------------ | ------------------------- |
+| `audit`      | `audit:prod`, `audit:dev` |
+| `audit:dev`  | `pnpm exec v11y --dev`    |
+| `audit:prod` | `pnpm exec v11y --prod`   |
 
 #### Dependencies
 

package/dist/esm/.cache

@@ -1 +1 @@
-01752582ad3da5f245f0d28ce77644b2b67d6be30ddb469279c38399fbd7e03b
+100ea1821185a3e234d52dd9a44609bf7ead7593a0e877d8d1c331754f7883a4

package/dist/esm/cli.js

@@ -1,162 +1,16 @@
-import path from "node:path";
 import process from "node:process";
-import { readPackageVersion } from "@williamthorsen/nmr-core";
-import { resolveContext } from "./context.js";
-import { generateHelp } from "./help.js";
-import { isHookName } from "./helpers/hook-name.js";
-import { applyDevBin, buildRootRegistry, buildWorkspaceRegistry, resolveScript } from "./resolver.js";
-import { runCommand } from "./runner.js";
-const VERSION = readPackageVersion(import.meta.url);
-function shellQuote(arg) {
-  return "'" + arg.replace(/'/g, String.raw`'\''`) + "'";
-}
-function parseArgs(argv) {
-  const args = argv.slice(2);
-  const result = {
-    quiet: false,
-    recursive: false,
-    workspaceRoot: false,
-    help: false,
-    version: false,
-    intTest: false,
-    passthrough: []
-  };
-  let i = 0;
-  while (i < args.length) {
-    const arg = args[i];
-    if (arg === void 0) break;
-    if (arg === "-F" || arg === "--filter") {
-      i++;
-      const filterValue = args[i];
-      if (filterValue === void 0) {
-        console.error("Error: -F/--filter requires a pattern argument");
-        process.exit(1);
-      }
-      result.filter = filterValue;
-      i++;
-      continue;
-    }
-    if (arg === "-R" || arg === "--recursive") {
-      result.recursive = true;
-      i++;
-      continue;
-    }
-    if (arg === "-w" || arg === "--workspace-root") {
-      result.workspaceRoot = true;
-      i++;
-      continue;
-    }
-    if (arg === "-?" || arg === "--help") {
-      result.help = true;
-      i++;
-      continue;
-    }
-    if (arg === "-V" || arg === "--version") {
-      result.version = true;
-      i++;
-      continue;
-    }
-    if (arg === "-q" || arg === "--quiet") {
-      result.quiet = true;
-      i++;
-      continue;
-    }
-    if (arg === "--int-test") {
-      result.intTest = true;
-      i++;
-      continue;
-    }
-    result.command = arg;
-    result.passthrough = args.slice(i + 1);
-    break;
-  }
-  return result;
-}
-async function main() {
-  const parsed = parseArgs(process.argv);
-  if (parsed.version) {
-    console.info(VERSION);
-    process.exit(0);
-  }
-  const context = await resolveContext();
-  const useRoot = parsed.workspaceRoot || context.isRoot;
-  const packageDir = useRoot ? context.monorepoRoot : context.packageDir ?? context.monorepoRoot;
-  if (parsed.help || !parsed.command) {
-    console.info(generateHelp(context.config, packageDir, useRoot));
-    process.exit(0);
-  }
-  const { command } = parsed;
-  const passthrough = parsed.passthrough.length > 0 ? " " + parsed.passthrough.map(shellQuote).join(" ") : "";
-  const runOptions = { quiet: parsed.quiet };
-  if (parsed.filter) {
-    const delegateCmd = `pnpm --filter ${shellQuote(parsed.filter)} exec nmr ${command}${passthrough}`;
-    const code2 = runCommand(delegateCmd, context.monorepoRoot, runOptions);
-    process.exit(code2);
-  }
-  if (parsed.recursive) {
-    process.env.NMR_RUN_IF_PRESENT = "1";
-    const delegateCmd = `pnpm --recursive exec nmr ${command}${passthrough}`;
-    const code2 = runCommand(delegateCmd, context.monorepoRoot, runOptions);
-    process.exit(code2);
-  }
-  const registry = useRoot ? buildRootRegistry(context.config) : buildWorkspaceRegistry(context.config, parsed.intTest);
-  const resolved = resolveScript(command, registry, packageDir, parsed.workspaceRoot);
-  if (!resolved) {
-    if (process.env.NMR_RUN_IF_PRESENT === "1") {
-      process.exit(0);
-    }
-    console.error(`Unknown command: ${command}`);
-    process.exit(1);
-  }
-  const skipExitCode = handleSkipMessage(resolved.command, packageDir, parsed.quiet);
-  if (skipExitCode !== void 0) {
-    process.exit(skipExitCode);
-  }
-  if (resolved.source === "package" && !parsed.quiet && registry[command] !== void 0) {
-    console.info(`\u{1F4E6} ${path.basename(packageDir)}: Using override script: ${resolved.command}`);
-  }
-  const substitutedCommand = applyDevBin(resolved.command, context.config.devBin, context.monorepoRoot);
-  const mainCommand = substitutedCommand + passthrough;
-  const isHookInvocation = isHookName(command);
-  const fullCommand = isHookInvocation ? mainCommand : wrapWithHooks(command, mainCommand, registry, packageDir, parsed.workspaceRoot);
-  const code = runCommand(fullCommand, void 0, runOptions);
-  process.exit(code);
-}
-function handleSkipMessage(resolvedCommand, packageDir, quiet) {
-  if (resolvedCommand === "") {
-    if (!quiet) {
-      console.info(`\u26D4 ${path.basename(packageDir)}: Override script is defined but empty. Skipping.`);
-    }
-    return 0;
-  }
-  if (resolvedCommand === ":") {
-    if (!quiet) {
-      console.info(`\u26D4 ${path.basename(packageDir)}: Override script is a no-op. Skipping.`);
-    }
-    return 0;
-  }
-  return void 0;
-}
-function wrapWithHooks(command, mainCommand, registry, packageDir, workspaceRoot) {
-  const segments = [];
-  const flag = workspaceRoot ? "-w " : "";
-  if (hasRunnableHook(`${command}:pre`, registry, packageDir, workspaceRoot)) {
-    segments.push(`nmr ${flag}${command}:pre`);
-  }
-  segments.push(mainCommand);
-  if (hasRunnableHook(`${command}:post`, registry, packageDir, workspaceRoot)) {
-    segments.push(`nmr ${flag}${command}:post`);
-  }
-  return segments.join(" && ");
-}
-function hasRunnableHook(hookName, registry, packageDir, workspaceRoot) {
-  const resolved = resolveScript(hookName, registry, packageDir, workspaceRoot);
-  if (!resolved) return false;
-  return resolved.command !== "" && resolved.command !== ":";
-}
+import { runCli } from "./runCli.js";
 try {
-  await main();
+  const { exitCode } = await runCli({
+    args: process.argv.slice(2),
+    cwd: process.cwd(),
+    env: process.env,
+    stdout: process.stdout,
+    stderr: process.stderr
+  });
+  process.exit(exitCode);
 } catch (error) {
-  console.error(error);
+  process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}
+`);
   process.exit(1);
 }

package/dist/esm/context.d.ts

@@ -1,4 +1,4 @@
-import type { NmrConfig } from './config.js';
+import type { NmrConfig } from './config.ts';
 export interface ResolvedContext {
     monorepoRoot: string;
     isRoot: boolean;

package/dist/esm/default-scripts.js

@@ -28,8 +28,8 @@ const standardTestScripts = {
 };
 const rootScripts = {
   audit: ["audit:prod", "audit:dev"],
-  "audit:dev": "pnpm exec audit-deps --dev",
-  "audit:prod": "pnpm exec audit-deps --prod",
+  "audit:dev": "pnpm exec v11y --dev",
+  "audit:prod": "pnpm exec v11y --prod",
   build: "pnpm --recursive exec nmr build",
   check: ["typecheck", "fmt:check", "lint:check", "test"],
   "check:agent-files": "nmr-sync-agent-files --check",

package/dist/esm/help.d.ts

@@ -1,2 +1,2 @@
-import type { NmrConfig } from './config.js';
+import type { NmrConfig } from './config.ts';
 export declare function generateHelp(config: NmrConfig, packageDir: string | undefined, useRoot: boolean): string;

package/dist/esm/resolve-scripts.d.ts

@@ -1,4 +1,4 @@
-import type { ScriptRegistry } from './default-scripts.js';
-export type { ScriptRegistry, ScriptValue } from './default-scripts.js';
+import type { ScriptRegistry } from './default-scripts.ts';
+export type { ScriptRegistry, ScriptValue } from './default-scripts.ts';
 export declare function getDefaultWorkspaceScripts(useIntTests: boolean): ScriptRegistry;
 export declare function getDefaultRootScripts(): ScriptRegistry;

package/dist/esm/resolver.d.ts

@@ -1,5 +1,5 @@
-import type { NmrConfig } from './config.js';
-import type { ScriptRegistry, ScriptValue } from './resolve-scripts.js';
+import type { NmrConfig } from './config.ts';
+import type { ScriptRegistry, ScriptValue } from './resolve-scripts.ts';
 export declare function applyDevBin(command: string, devBin: Record<string, string> | undefined, monorepoRoot: string): string;
 export interface ResolvedScript {
     command: string;

package/dist/esm/runCli.d.ts

@@ -0,0 +1,12 @@
+import type { Writable } from 'node:stream';
+export interface RunCliOptions {
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    stdout: Writable;
+    stderr: Writable;
+}
+export interface RunCliResult {
+    exitCode: number;
+}
+export declare function runCli(options: RunCliOptions): Promise<RunCliResult>;

package/dist/esm/runCli.js

@@ -0,0 +1,169 @@
+import path from "node:path";
+import { readPackageVersion } from "@williamthorsen/nmr-core";
+import { resolveContext } from "./context.js";
+import { generateHelp } from "./help.js";
+import { isHookName } from "./helpers/hook-name.js";
+import { applyDevBin, buildRootRegistry, buildWorkspaceRegistry, resolveScript } from "./resolver.js";
+import { runCommand } from "./runner.js";
+const VERSION = readPackageVersion(import.meta.url);
+async function runCli(options) {
+  const { args, cwd, env, stdout, stderr } = options;
+  const parseResult = parseArgs(args);
+  if (!parseResult.ok) {
+    stderr.write(`${parseResult.error}
+`);
+    return { exitCode: 1 };
+  }
+  const { parsed } = parseResult;
+  if (parsed.version) {
+    stdout.write(`${VERSION}
+`);
+    return { exitCode: 0 };
+  }
+  const context = await resolveContext(cwd);
+  const useRoot = parsed.workspaceRoot || context.isRoot;
+  const packageDir = useRoot ? context.monorepoRoot : context.packageDir ?? context.monorepoRoot;
+  if (parsed.help || !parsed.command) {
+    stdout.write(`${generateHelp(context.config, packageDir, useRoot)}
+`);
+    return { exitCode: 0 };
+  }
+  const { command } = parsed;
+  const passthrough = parsed.passthrough.length > 0 ? " " + parsed.passthrough.map(shellQuote).join(" ") : "";
+  const runOptions = { quiet: parsed.quiet, stdout, stderr, env };
+  if (parsed.filter) {
+    const delegateCmd = `pnpm --filter ${shellQuote(parsed.filter)} exec nmr ${command}${passthrough}`;
+    const exitCode2 = runCommand(delegateCmd, context.monorepoRoot, runOptions);
+    return { exitCode: exitCode2 };
+  }
+  if (parsed.recursive) {
+    const childEnv = { ...env, NMR_RUN_IF_PRESENT: "1" };
+    const delegateCmd = `pnpm --recursive exec nmr ${command}${passthrough}`;
+    const exitCode2 = runCommand(delegateCmd, context.monorepoRoot, { ...runOptions, env: childEnv });
+    return { exitCode: exitCode2 };
+  }
+  const registry = useRoot ? buildRootRegistry(context.config) : buildWorkspaceRegistry(context.config, parsed.intTest);
+  const resolved = resolveScript(command, registry, packageDir, parsed.workspaceRoot);
+  if (!resolved) {
+    if (env.NMR_RUN_IF_PRESENT === "1") {
+      return { exitCode: 0 };
+    }
+    stderr.write(`Unknown command: ${command}
+`);
+    return { exitCode: 1 };
+  }
+  const skipExitCode = handleSkipMessage(resolved.command, packageDir, parsed.quiet, stdout);
+  if (skipExitCode !== void 0) {
+    return { exitCode: skipExitCode };
+  }
+  if (resolved.source === "package" && !parsed.quiet && registry[command] !== void 0) {
+    stdout.write(`\u{1F4E6} ${path.basename(packageDir)}: Using override script: ${resolved.command}
+`);
+  }
+  const substitutedCommand = applyDevBin(resolved.command, context.config.devBin, context.monorepoRoot);
+  const mainCommand = substitutedCommand + passthrough;
+  const isHookInvocation = isHookName(command);
+  const fullCommand = isHookInvocation ? mainCommand : wrapWithHooks(command, mainCommand, registry, packageDir, parsed.workspaceRoot);
+  const exitCode = runCommand(fullCommand, cwd, runOptions);
+  return { exitCode };
+}
+function parseArgs(args) {
+  const parsed = {
+    quiet: false,
+    recursive: false,
+    workspaceRoot: false,
+    help: false,
+    version: false,
+    intTest: false,
+    passthrough: []
+  };
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg === void 0) break;
+    if (arg === "-F" || arg === "--filter") {
+      i++;
+      const filterValue = args[i];
+      if (filterValue === void 0) {
+        return { ok: false, error: "Error: -F/--filter requires a pattern argument" };
+      }
+      parsed.filter = filterValue;
+      i++;
+      continue;
+    }
+    if (arg === "-R" || arg === "--recursive") {
+      parsed.recursive = true;
+      i++;
+      continue;
+    }
+    if (arg === "-w" || arg === "--workspace-root") {
+      parsed.workspaceRoot = true;
+      i++;
+      continue;
+    }
+    if (arg === "-?" || arg === "--help") {
+      parsed.help = true;
+      i++;
+      continue;
+    }
+    if (arg === "-V" || arg === "--version") {
+      parsed.version = true;
+      i++;
+      continue;
+    }
+    if (arg === "-q" || arg === "--quiet") {
+      parsed.quiet = true;
+      i++;
+      continue;
+    }
+    if (arg === "--int-test") {
+      parsed.intTest = true;
+      i++;
+      continue;
+    }
+    parsed.command = arg;
+    parsed.passthrough = args.slice(i + 1);
+    break;
+  }
+  return { ok: true, parsed };
+}
+function handleSkipMessage(resolvedCommand, packageDir, quiet, stdout) {
+  if (resolvedCommand === "") {
+    if (!quiet) {
+      stdout.write(`\u26D4 ${path.basename(packageDir)}: Override script is defined but empty. Skipping.
+`);
+    }
+    return 0;
+  }
+  if (resolvedCommand === ":") {
+    if (!quiet) {
+      stdout.write(`\u26D4 ${path.basename(packageDir)}: Override script is a no-op. Skipping.
+`);
+    }
+    return 0;
+  }
+  return void 0;
+}
+function wrapWithHooks(command, mainCommand, registry, packageDir, workspaceRoot) {
+  const segments = [];
+  const flag = workspaceRoot ? "-w " : "";
+  if (hasRunnableHook(`${command}:pre`, registry, packageDir, workspaceRoot)) {
+    segments.push(`nmr ${flag}${command}:pre`);
+  }
+  segments.push(mainCommand);
+  if (hasRunnableHook(`${command}:post`, registry, packageDir, workspaceRoot)) {
+    segments.push(`nmr ${flag}${command}:post`);
+  }
+  return segments.join(" && ");
+}
+function hasRunnableHook(hookName, registry, packageDir, workspaceRoot) {
+  const resolved = resolveScript(hookName, registry, packageDir, workspaceRoot);
+  if (!resolved) return false;
+  return resolved.command !== "" && resolved.command !== ":";
+}
+function shellQuote(arg) {
+  return "'" + arg.replace(/'/g, String.raw`'\''`) + "'";
+}
+export {
+  runCli
+};

package/dist/esm/runner.d.ts

@@ -1,4 +1,8 @@
+import type { Writable } from 'node:stream';
 export interface RunCommandOptions {
     quiet?: boolean;
+    stdout?: Writable;
+    stderr?: Writable;
+    env?: NodeJS.ProcessEnv;
 }
 export declare function runCommand(command: string, cwd?: string, options?: RunCommandOptions): number;

package/dist/esm/runner.js

@@ -1,37 +1,39 @@
-import { execSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import process from "node:process";
 function runCommand(command, cwd, options) {
   const quiet = options?.quiet === true;
-  const stdio = quiet ? "pipe" : "inherit";
-  try {
-    execSync(command, { stdio, cwd });
-    return 0;
-  } catch (error) {
-    if (error !== null && typeof error === "object") {
-      if (quiet) {
-        writeErrorOutput(error);
-      }
-      if ("status" in error) {
-        const { status } = error;
-        return typeof status === "number" ? status : 1;
-      }
-    }
+  const stdout = options?.stdout ?? process.stdout;
+  const stderr = options?.stderr ?? process.stderr;
+  const env = options?.env ?? process.env;
+  const stdoutChannel = quiet ? "pipe" : streamFdOrPipe(stdout);
+  const stderrChannel = quiet ? "pipe" : streamFdOrPipe(stderr);
+  const result = spawnSync(command, [], {
+    shell: true,
+    stdio: ["inherit", stdoutChannel, stderrChannel],
+    cwd,
+    env
+  });
+  if (result.error) {
+    stderr.write(`${result.error.message}
+`);
     return 1;
   }
-}
-function writeErrorOutput(error) {
-  if ("stdout" in error) {
-    const { stdout } = error;
-    if (Buffer.isBuffer(stdout) && stdout.length > 0) {
-      process.stderr.write(stdout);
-    }
-  }
-  if ("stderr" in error) {
-    const { stderr } = error;
-    if (Buffer.isBuffer(stderr) && stderr.length > 0) {
-      process.stderr.write(stderr);
+  if (quiet) {
+    if (result.status !== 0) {
+      writeBuffer(result.stdout, stderr);
+      writeBuffer(result.stderr, stderr);
     }
+  } else {
+    if (stdoutChannel === "pipe") writeBuffer(result.stdout, stdout);
+    if (stderrChannel === "pipe") writeBuffer(result.stderr, stderr);
   }
+  return result.status ?? 1;
+}
+function streamFdOrPipe(stream) {
+  return "fd" in stream && typeof stream.fd === "number" ? stream.fd : "pipe";
+}
+function writeBuffer(buffer, dest) {
+  if (buffer.length > 0) dest.write(buffer);
 }
 export {
   runCommand

package/dist/esm/scripts.d.ts

@@ -1,2 +1,2 @@
-export type { ScriptRegistry, ScriptValue } from './default-scripts.js';
-export { getDefaultRootScripts, getDefaultWorkspaceScripts } from './resolve-scripts.js';
+export type { ScriptRegistry, ScriptValue } from './default-scripts.ts';
+export { getDefaultRootScripts, getDefaultWorkspaceScripts } from './resolve-scripts.ts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "private": false,
   "description": "Context-aware script runner for PNPM monorepos",
   "keywords": [
@@ -39,10 +39,10 @@
     "dist"
   ],
   "dependencies": {
-    "jiti": "2.6.1",
+    "jiti": "2.7.0",
     "js-yaml": "4.1.1",
     "zod": "4.4.3",
-    "@williamthorsen/nmr-core": "0.3.1"
+    "@williamthorsen/nmr-core": "0.3.2"
   },
   "publishConfig": {
     "access": "public"