@williamthorsen/nmr 0.12.1 → 0.14.0

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
 
@@ -36,6 +48,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

@@ -220,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 @@
-ecd2594bf00be365cf1c1d58937d98631236e5a8841aade1fcaf6bb190cbf84b
+2d3864d638817ab1f6e49b7d20cb118260518782ce8c8c372346c837f72edadc

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/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';
-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.14.0",
   "private": false,
   "description": "Context-aware script runner for PNPM monorepos",
   "keywords": [
@@ -39,12 +39,15 @@
     "dist"
   ],
   "dependencies": {
-    "jiti": "2.6.1",
+    "jiti": "2.7.0",
     "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
-};