@williamthorsen/nmr 0.12.1 → 0.13.0

package/AGENTS.md

@@ -36,6 +36,42 @@ In `.config/nmr.config.ts` or a package's `package.json`, override values have s
 - `":"` — no-op; exit 0. Prefer this over `""` if your repo enforces non-empty script values.
 - Any other string — runs in place of the default.
 
+## Pre and post hooks
+
+Every `nmr X` invocation auto-wraps as the equivalent of `nmr X:pre && nmr X && nmr X:post`. Hooks are first-class scripts that resolve through the same 3-tier registry (built-in defaults → `.config/nmr.config.ts` → per-package `package.json`). Wrapping is uniform; nested invocations from composite expansion get their own hook treatment. Hook failure short-circuits the chain via shell `&&` semantics, propagating the failing exit code.
+
+Behaviors worth knowing:
+
+- **Silent when absent** — missing hooks produce no error and no output.
+- **Skip overrides apply to hooks** — a hook value of `""` or `":"` is treated the same as not defining the hook. No console message.
+- **Skipping the main command skips its hooks** — when `X` is overridden to `""` or `":"`, neither `X:pre` nor `X:post` fires.
+- **Recursion guard** — direct invocation of a hook (e.g., `nmr build:pre`) is treated as a leaf operation. It does NOT itself attempt to resolve `build:pre:pre` or `build:pre:post`.
+- **Passthrough args attach only to the main command** — `nmr X --flag value` runs hooks without `--flag value`.
+
+Worked examples:
+
+```ts
+// .config/nmr.config.ts — extend `nmr build` with a pre-build compile step
+import { defineConfig } from '@williamthorsen/nmr';
+
+export default defineConfig({
+  workspaceScripts: {
+    'build:pre': 'npx rdy compile',
+  },
+});
+```
+
+```jsonc
+// packages/nmr/package.json — re-stamp .agents/nmr/AGENTS.md after every build
+{
+  "scripts": {
+    "build:post": "nmr-sync-agent-files",
+  },
+}
+```
+
+The second example calls the bin directly to sidestep the workspace-vs-root registry distinction.
+
 ## Agent-file sync
 
 The presence and version stamp of `.agents/nmr/AGENTS.md` is verified by `check:agent-files`, which is part of the default root `check:strict` composite. If it fails, run `nmr sync-agent-files`.

package/README.md

@@ -2,7 +2,25 @@
 
 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 --><!-- /section:release-notes -->
+<!-- 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 -->
 
 ## Installation
 

package/dist/esm/.cache

@@ -1 +1 @@
-ecd2594bf00be365cf1c1d58937d98631236e5a8841aade1fcaf6bb190cbf84b
+01752582ad3da5f245f0d28ce77644b2b67d6be30ddb469279c38399fbd7e03b

package/dist/esm/cli.js

@@ -1,10 +1,12 @@
 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";
-import { VERSION } from "./version.js";
+const VERSION = readPackageVersion(import.meta.url);
 function shellQuote(arg) {
   return "'" + arg.replace(/'/g, String.raw`'\''`) + "'";
 }
@@ -77,8 +79,10 @@ async function main() {
     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));
+    console.info(generateHelp(context.config, packageDir, useRoot));
     process.exit(0);
   }
   const { command } = parsed;
@@ -95,10 +99,8 @@ async function main() {
     const code2 = runCommand(delegateCmd, context.monorepoRoot, runOptions);
     process.exit(code2);
   }
-  const useRoot = parsed.workspaceRoot || context.isRoot;
   const registry = useRoot ? buildRootRegistry(context.config) : buildWorkspaceRegistry(context.config, parsed.intTest);
-  const packageDir = context.packageDir ?? context.monorepoRoot;
-  const resolved = resolveScript(command, registry, packageDir);
+  const resolved = resolveScript(command, registry, packageDir, parsed.workspaceRoot);
   if (!resolved) {
     if (process.env.NMR_RUN_IF_PRESENT === "1") {
       process.exit(0);
@@ -106,27 +108,52 @@ async function main() {
     console.error(`Unknown command: ${command}`);
     process.exit(1);
   }
-  const packageName = path.basename(packageDir);
-  if (resolved.command === "") {
-    if (!parsed.quiet) {
-      console.info(`\u26D4 ${packageName}: Override script is defined but empty. Skipping.`);
-    }
-    process.exit(0);
-  }
-  if (resolved.command === ":") {
-    if (!parsed.quiet) {
-      console.info(`\u26D4 ${packageName}: Override script is a no-op. Skipping.`);
-    }
-    process.exit(0);
+  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} ${packageName}: Using override script: ${resolved.command}`);
+    console.info(`\u{1F4E6} ${path.basename(packageDir)}: Using override script: ${resolved.command}`);
   }
   const substitutedCommand = applyDevBin(resolved.command, context.config.devBin, context.monorepoRoot);
-  const fullCommand = substitutedCommand + passthrough;
+  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 !== ":";
+}
 try {
   await main();
 } catch (error) {

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

@@ -1,7 +1,8 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { VERSION } from "../version.js";
+import { readPackageVersion } from "@williamthorsen/nmr-core";
+const VERSION = readPackageVersion(import.meta.url);
 const PACKAGE_NAME = "@williamthorsen/nmr";
 const DESTINATION_RELATIVE_PATH = ".agents/nmr/AGENTS.md";
 const SOURCE_FILENAME = "AGENTS.md";

package/dist/esm/help.d.ts

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

package/dist/esm/help.js

@@ -1,6 +1,12 @@
-import { buildRootRegistry, buildWorkspaceRegistry } from "./resolver.js";
-import { describeScript } from "./resolver.js";
-function generateHelp(config) {
+import { isHookName } from "./helpers/hook-name.js";
+import {
+  buildRootRegistry,
+  buildWorkspaceRegistry,
+  describeScript,
+  isSelfReferential,
+  readPackageJsonScripts
+} from "./resolver.js";
+function generateHelp(config, packageDir, useRoot) {
   const lines = [
     "Usage: nmr [flags] <command> [args...]",
     "",
@@ -14,16 +20,58 @@ function generateHelp(config) {
     "",
     "Workspace commands:"
   ];
-  formatRegistry(buildWorkspaceRegistry(config, false), lines);
+  const overrides = packageDir === void 0 ? {} : collectOverrides(packageDir);
+  let hadOverride = false;
+  const workspaceRegistry = filterHooks(buildWorkspaceRegistry(config, false));
+  const workspaceMarked = !useRoot ? applyOverrides(workspaceRegistry, overrides) : /* @__PURE__ */ new Set();
+  if (workspaceMarked.size > 0) hadOverride = true;
+  formatRegistry(workspaceRegistry, workspaceMarked, lines);
   lines.push("", "Root commands:");
-  formatRegistry(buildRootRegistry(config), lines);
+  const rootRegistry = filterHooks(buildRootRegistry(config));
+  const rootMarked = useRoot ? applyOverrides(rootRegistry, overrides) : /* @__PURE__ */ new Set();
+  if (rootMarked.size > 0) hadOverride = true;
+  formatRegistry(rootRegistry, rootMarked, lines);
+  if (hadOverride) {
+    lines.push("", "* Overridden by package.json");
+  }
   return lines.join("\n");
 }
-function formatRegistry(registry, lines) {
-  const maxKeyLen = Math.max(...Object.keys(registry).map((k) => k.length));
-  const pad = Math.max(maxKeyLen + 2, 20);
+function collectOverrides(packageDir) {
+  const scripts = readPackageJsonScripts(packageDir);
+  if (!scripts) return {};
+  const filtered = {};
+  for (const [name, value] of Object.entries(scripts)) {
+    if (isHookName(name)) continue;
+    if (isSelfReferential(value, name)) continue;
+    filtered[name] = value;
+  }
+  return filtered;
+}
+function applyOverrides(registry, overrides) {
+  const marked = /* @__PURE__ */ new Set();
+  for (const [name, value] of Object.entries(overrides)) {
+    if (name in registry) {
+      registry[name] = value;
+      marked.add(name);
+    }
+  }
+  return marked;
+}
+function filterHooks(registry) {
+  const filtered = {};
+  for (const [key, value] of Object.entries(registry)) {
+    if (!isHookName(key)) filtered[key] = value;
+  }
+  return filtered;
+}
+function formatRegistry(registry, marked, lines) {
+  const keys = Object.keys(registry);
+  if (keys.length === 0) return;
+  const maxKeyLen = Math.max(...keys.map((k) => k.length));
+  const pad = Math.max(maxKeyLen + 1 + 2, 20);
   for (const [key, value] of Object.entries(registry)) {
-    lines.push(`  ${key.padEnd(pad)} ${describeScript(value)}`);
+    const marker = marked.has(key) ? "*" : " ";
+    lines.push(`  ${(key + marker).padEnd(pad)} ${describeScript(value)}`);
   }
 }
 export {

package/dist/esm/helpers/hook-name.d.ts

@@ -0,0 +1 @@
+export declare function isHookName(key: string): boolean;

package/dist/esm/helpers/hook-name.js

@@ -0,0 +1,6 @@
+function isHookName(key) {
+  return key.length > 4 && key.endsWith(":pre") || key.length > 5 && key.endsWith(":post");
+}
+export {
+  isHookName
+};

package/dist/esm/resolver.d.ts

@@ -5,8 +5,10 @@ export interface ResolvedScript {
     command: string;
     source: 'default' | 'package';
 }
-export declare function expandScript(script: ScriptValue): string;
+export declare function expandScript(script: ScriptValue, workspaceRoot: boolean): string;
 export declare function describeScript(script: ScriptValue): string;
+export declare function readPackageJsonScripts(packageDir: string): Record<string, string> | undefined;
 export declare function buildWorkspaceRegistry(config: NmrConfig, useIntTests: boolean): ScriptRegistry;
 export declare function buildRootRegistry(config: NmrConfig): ScriptRegistry;
-export declare function resolveScript(commandName: string, registry: ScriptRegistry, packageDir?: string): ResolvedScript | undefined;
+export declare function isSelfReferential(script: string, commandName: string): boolean;
+export declare function resolveScript(commandName: string, registry: ScriptRegistry, packageDir: string | undefined, workspaceRoot: boolean): ResolvedScript | undefined;

package/dist/esm/resolver.js

@@ -25,11 +25,12 @@ function resolveReplacementPaths(replacement, monorepoRoot) {
     return path.resolve(monorepoRoot, token);
   }).join(" ");
 }
-function expandScript(script) {
+function expandScript(script, workspaceRoot) {
   if (typeof script === "string") {
     return script;
   }
-  return script.map((s) => `nmr ${s}`).join(" && ");
+  const flag = workspaceRoot ? "-w " : "";
+  return script.map((s) => `nmr ${flag}${s}`).join(" && ");
 }
 function describeScript(script) {
   return typeof script === "string" ? script : `[${script.join(", ")}]`;
@@ -69,7 +70,7 @@ function isSelfReferential(script, commandName) {
   const prefix = `nmr ${commandName}`;
   return script === prefix || script.startsWith(`${prefix} `);
 }
-function resolveScript(commandName, registry, packageDir) {
+function resolveScript(commandName, registry, packageDir, workspaceRoot) {
   if (packageDir) {
     const pkgScripts = readPackageJsonScripts(packageDir);
     if (pkgScripts && commandName in pkgScripts) {
@@ -83,7 +84,7 @@ function resolveScript(commandName, registry, packageDir) {
   if (registryEntry === void 0) {
     return void 0;
   }
-  return { command: expandScript(registryEntry), source: "default" };
+  return { command: expandScript(registryEntry, workspaceRoot), source: "default" };
 }
 export {
   applyDevBin,
@@ -91,5 +92,7 @@ export {
   buildWorkspaceRegistry,
   describeScript,
   expandScript,
+  isSelfReferential,
+  readPackageJsonScripts,
   resolveScript
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "private": false,
   "description": "Context-aware script runner for PNPM monorepos",
   "keywords": [
@@ -41,10 +41,13 @@
   "dependencies": {
     "jiti": "2.6.1",
     "js-yaml": "4.1.1",
-    "zod": "4.4.1"
+    "zod": "4.4.3",
+    "@williamthorsen/nmr-core": "0.3.1"
   },
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {}
+  "scripts": {
+    "build:post": "nmr-sync-agent-files"
+  }
 }

package/dist/esm/version.d.ts

@@ -1 +0,0 @@
-export declare const VERSION = "0.12.1";

package/dist/esm/version.js

@@ -1,4 +0,0 @@
-const VERSION = "0.12.1";
-export {
-  VERSION
-};