@williamthorsen/nmr 0.11.0 → 0.12.0

package/AGENTS.md

@@ -0,0 +1,41 @@
+---
+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.
+
+## Discover scripts by running nmr
+
+Run `nmr` with no command (from the monorepo root or any workspace package) to list every available script, including composite expansions and resolved shell commands. Check this before guessing a script name from another repo — the registry is authoritative.
+
+## 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.
+
+## Root vs. workspace context
+
+nmr walks up to find `pnpm-workspace.yaml`, then decides which registry to use based on whether your cwd is inside a workspace package. The same command name (e.g. `build`, `test`, `check:strict`) often exists in both registries with different behavior — the root version typically delegates across all workspaces. Use `-w` to force the root registry from inside a package dir, and `-F <pkg>` to run a single package's script from anywhere.
+
+## Composite scripts
+
+A script value shown in `nmr` output as `[a, b, c]` is a composite: it runs `nmr a && nmr b && nmr c`, stopping at the first failure. Composites can reference other composites.
+
+## `root:*` siblings
+
+Some root scripts (e.g. `lint`, `typecheck`, `test`) expand to `nmr root:X && pnpm --recursive exec nmr X`. The `root:X` variant runs only against root-level files; the plain name runs everywhere. Use `root:X` directly when you want to isolate a failure to the root code.
+
+## Override behaviors
+
+In `.config/nmr.config.ts` or a package's `package.json`, override values have special semantics:
+
+- `""` (empty string) — skip the script with a "Skipping" message; exit 0.
+- `":"` — no-op; exit 0. Prefer this over `""` if your repo enforces non-empty script values.
+- Any other string — runs in place of the default.
+
+## 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,6 +2,22 @@
 
 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.12.0 (2026-04-23)
+
+### Features
+
+- Add agent-facing AGENTS.md and sync-agent-files command (#263)
+
+  Ships nmr-owned agent guidance alongside the `@williamthorsen/nmr` package so consuming repos stop hand-maintaining their own copies of the runner's invocation rules. A new `nmr sync-agent-files` command pulls that guidance into `.agents/nmr/AGENTS.md` in the consuming repo, stamped with the installed nmr version; a companion `--check` variant verifies the stamp against the installed version on every root `check:strict` run. Drift between installed nmr and the committed guidance now fails the quality gate automatically with a single actionable fix message, without per-consumer wiring.
+
+- Rename check:fixable script to fix:check (#266)
+
+  Renames the `check:fixable` convenience script to `fix:check` in both the workspace and root default script registries. The new name mirrors the existing `fmt` / `fmt:check` pattern, aligning the read-only variant with its mutating counterpart (`fix`) so the command's read-only semantics are recognizable from the name alone.
+
+  The script's expansion (`fmt:check`, `lint:check`) is unchanged.
+<!-- /section:release-notes -->
+
 ## Installation
 
 ```bash
@@ -133,11 +149,11 @@ These scripts are available out of the box. Repo-wide config (tier 2) and per-pa
 | ------------------ | -------------------------------------------------------- |
 | `build`            | `compile`, `generate-typings`                            |
 | `check`            | `typecheck`, `fmt:check`, `lint:check`, `test`           |
-| `check:fixable`    | `fmt:check`, `lint:check`                                |
 | `check:strict`     | `typecheck`, `fmt:check`, `lint:strict`, `test:coverage` |
 | `clean`            | `pnpm exec rimraf dist/*`                                |
 | `compile`          | `tsx ../../config/build.ts`                              |
 | `fix`              | `lint`, `fmt`                                            |
+| `fix:check`        | `fmt:check`, `lint:check`                                |
 | `fmt`              | `prettier --list-different --write .`                    |
 | `fmt:check`        | `prettier --check .`                                     |
 | `generate-typings` | `tsc --project tsconfig.generate-typings.json`           |
@@ -173,11 +189,17 @@ Packages with a `vitest.integration.config.ts` file get different test commands.
 
 #### Check and quality
 
-| Command         | Runs                                                     |
-| --------------- | -------------------------------------------------------- |
-| `check`         | `typecheck`, `fmt:check`, `lint:check`, `test`           |
-| `check:fixable` | `fmt:check`, `lint:check`                                |
-| `check:strict`  | `typecheck`, `fmt:check`, `lint:strict`, `test:coverage` |
+| Command             | Runs                                                                          |
+| ------------------- | ----------------------------------------------------------------------------- |
+| `check`             | `typecheck`, `fmt:check`, `lint:check`, `test`                                |
+| `check:agent-files` | `nmr-sync-agent-files --check`                                                |
+| `check:strict`      | `typecheck`, `fmt:check`, `lint:strict`, `test:coverage`, `check:agent-files` |
+
+#### Fix
+
+| Command     | Runs                      |
+| ----------- | ------------------------- |
+| `fix:check` | `fmt:check`, `lint:check` |
 
 #### Test
 
@@ -245,6 +267,7 @@ These scripts operate on root-level code only (not workspace packages):
 | Command             | Runs                    |
 | ------------------- | ----------------------- |
 | `report-overrides`  | `nmr-report-overrides`  |
+| `sync-agent-files`  | `nmr-sync-agent-files`  |
 | `sync-pnpm-version` | `nmr-sync-pnpm-version` |
 
 ## CLI reference
@@ -296,6 +319,25 @@ Report any active `pnpm.overrides` in the root `package.json`. Useful as a `post
 nmr report-overrides
 ```
 
+### `sync-agent-files`
+
+Sync the agent-facing guidance shipped with nmr into the consuming repo.
+
+```bash
+nmr sync-agent-files          # write .agents/nmr/AGENTS.md, stamped with the installed nmr version
+nmr sync-agent-files --check  # verify the stamp matches; exit 1 with a fix message if not
+```
+
+Run `nmr sync-agent-files` once after upgrading nmr. The generated file is committed to the consuming repo; do not edit it by hand.
+
+The default root `check:strict` composite includes `check:agent-files`, which runs `--check` automatically — so any CI pipeline already running `check:strict` catches drift without per-consumer wiring.
+
+To expose the synced guidance to Claude Code sessions, add this include to the consuming repo's `.agents/PROJECT.md`:
+
+```markdown
+@.agents/nmr/AGENTS.md
+```
+
 ### `sync-pnpm-version`
 
 Synchronize the pnpm version from the root `package.json` `packageManager` field into the GitHub `code-quality.yaml` workflow file.

package/bin/nmr-sync-agent-files.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+try {
+  await import('../dist/esm/cli-sync-agent-files.js');
+} catch (error) {
+  if (error.code === 'ERR_MODULE_NOT_FOUND') {
+    process.stderr.write('nmr-sync-agent-files: build output not found — run `pnpm run build` first\n');
+  } else {
+    process.stderr.write(`nmr-sync-agent-files: failed to load: ${error.message}\n`);
+  }
+  process.exit(1);
+}

package/dist/esm/.cache

@@ -1 +1 @@
-c78bf7d8a9e046770c7c8de71f6bf1424bd0919ce2c557d53fc83d984a4528f8
+d28e365779e353583b02eb587a2dfe64797c3a00544b42b8b18922aff2959d34

package/dist/esm/cli-sync-agent-files.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,31 @@
+import { check, sync } from "./commands/sync-agent-files.js";
+import { findMonorepoRoot } from "./context.js";
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  if (args.length === 0) return { mode: "sync" };
+  if (args.length === 1 && args[0] === "--check") return { mode: "check" };
+  return { error: `Usage: nmr sync-agent-files [--check]` };
+}
+try {
+  const parsed = parseArgs(process.argv);
+  if ("error" in parsed) {
+    console.error(parsed.error);
+    process.exit(1);
+  }
+  const monorepoRoot = findMonorepoRoot();
+  if (parsed.mode === "sync") {
+    const { written, stamp } = sync(monorepoRoot);
+    console.info(`\u2713 Wrote ${written} (${stamp})`);
+    process.exit(0);
+  }
+  const result = check(monorepoRoot);
+  if (result.ok) {
+    console.info(`\u2713 .agents/nmr/AGENTS.md is in sync (${result.stamp})`);
+    process.exit(0);
+  }
+  console.error(result.reason);
+  process.exit(1);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/dist/esm/commands/sync-agent-files.d.ts

@@ -0,0 +1,14 @@
+export declare function parseSourceStamp(content: string): string | null;
+export interface SyncResult {
+    written: string;
+    stamp: string;
+}
+export declare function sync(destinationDir: string): SyncResult;
+export type CheckResult = {
+    ok: true;
+    stamp: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function check(destinationDir: string): CheckResult;

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

@@ -0,0 +1,77 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { VERSION } from "../version.js";
+const PACKAGE_NAME = "@williamthorsen/nmr";
+const DESTINATION_RELATIVE_PATH = ".agents/nmr/AGENTS.md";
+const SOURCE_FILENAME = "AGENTS.md";
+function getSourcePath() {
+  let dir = path.dirname(fileURLToPath(import.meta.url));
+  while (dir !== path.dirname(dir)) {
+    const candidate = path.join(dir, SOURCE_FILENAME);
+    if (existsSync(candidate)) return candidate;
+    dir = path.dirname(dir);
+  }
+  throw new Error(`Could not locate ${SOURCE_FILENAME} in any parent of ${fileURLToPath(import.meta.url)}`);
+}
+function getDestinationPath(destinationDir) {
+  return path.join(destinationDir, DESTINATION_RELATIVE_PATH);
+}
+function currentSourceStamp() {
+  return `${PACKAGE_NAME}@${VERSION}`;
+}
+const FRONTMATTER_REGEX = /^---\n((?:.*\n)*?)---\n/;
+function stripFrontmatter(content) {
+  return content.replace(FRONTMATTER_REGEX, "");
+}
+function parseSourceStamp(content) {
+  const frontmatterMatch = FRONTMATTER_REGEX.exec(content);
+  if (!frontmatterMatch) return null;
+  const frontmatterBody = frontmatterMatch[1] ?? "";
+  const sourceMatch = /^source:\s*['"]([^'"]+)['"]\s*$/m.exec(frontmatterBody);
+  return sourceMatch?.[1] ?? null;
+}
+function sync(destinationDir) {
+  const sourcePath = getSourcePath();
+  const sourceContent = readFileSync(sourcePath, "utf8");
+  const body = stripFrontmatter(sourceContent);
+  const stamp = currentSourceStamp();
+  const output = `---
+source: '${stamp}'
+---
+${body}`;
+  const destinationPath = getDestinationPath(destinationDir);
+  mkdirSync(path.dirname(destinationPath), { recursive: true });
+  writeFileSync(destinationPath, output, "utf8");
+  return { written: destinationPath, stamp };
+}
+function check(destinationDir) {
+  const destinationPath = getDestinationPath(destinationDir);
+  const expected = currentSourceStamp();
+  if (!existsSync(destinationPath)) {
+    return {
+      ok: false,
+      reason: `${DESTINATION_RELATIVE_PATH} is missing. Run \`nmr sync-agent-files\`.`
+    };
+  }
+  const content = readFileSync(destinationPath, "utf8");
+  const found = parseSourceStamp(content);
+  if (found === null) {
+    return {
+      ok: false,
+      reason: `Cannot parse version stamp in ${DESTINATION_RELATIVE_PATH}. Run \`nmr sync-agent-files\`.`
+    };
+  }
+  if (found !== expected) {
+    return {
+      ok: false,
+      reason: `${DESTINATION_RELATIVE_PATH} is out of sync (file: ${found}, installed: ${expected}). Run \`nmr sync-agent-files\`.`
+    };
+  }
+  return { ok: true, stamp: expected };
+}
+export {
+  check,
+  parseSourceStamp,
+  sync
+};

package/dist/esm/default-scripts.js

@@ -1,11 +1,11 @@
 const commonWorkspaceScripts = {
   build: ["compile", "generate-typings"],
   check: ["typecheck", "fmt:check", "lint:check", "test"],
-  "check:fixable": ["fmt:check", "lint:check"],
   "check:strict": ["typecheck", "fmt:check", "lint:strict", "test:coverage"],
   clean: "pnpm exec rimraf dist/*",
   compile: "tsx ../../config/build.ts",
   fix: ["lint", "fmt"],
+  "fix:check": ["fmt:check", "lint:check"],
   fmt: "prettier --list-different --write .",
   "fmt:check": "prettier --check .",
   "generate-typings": "tsc --project tsconfig.generate-typings.json",
@@ -32,11 +32,12 @@ const rootScripts = {
   "audit:prod": "pnpm exec audit-deps --prod",
   build: "pnpm --recursive exec nmr build",
   check: ["typecheck", "fmt:check", "lint:check", "test"],
-  "check:fixable": ["fmt:check", "lint:check"],
-  "check:strict": ["typecheck", "fmt:check", "lint:strict", "test:coverage"],
+  "check:agent-files": "nmr-sync-agent-files --check",
+  "check:strict": ["typecheck", "fmt:check", "lint:strict", "test:coverage", "check:agent-files"],
   ci: ["build", "check:strict", "audit"],
   clean: "pnpm --recursive exec nmr clean",
   fix: ["lint", "fmt"],
+  "fix:check": ["fmt:check", "lint:check"],
   fmt: `sh -c 'prettier --list-different --write "\${@:-.}"' --`,
   "fmt:all": ["fmt", "fmt:sh"],
   "fmt:check": `sh -c 'prettier --check "\${@:-.}"' --`,
@@ -53,6 +54,7 @@ const rootScripts = {
   "root:lint:strict": "strict-lint --ignore-pattern 'packages/**' .",
   "root:test": "vitest --config ./vitest.root.config.ts",
   "root:typecheck": "tsgo --noEmit",
+  "sync-agent-files": "nmr-sync-agent-files",
   "sync-pnpm-version": "nmr-sync-pnpm-version",
   test: "nmr root:test && pnpm --recursive exec nmr test",
   "test:coverage": "nmr root:test && pnpm --recursive exec nmr test:coverage",

package/dist/esm/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.11.0";
+export declare const VERSION = "0.12.0";

package/dist/esm/version.js

@@ -1,4 +1,4 @@
-const VERSION = "0.11.0";
+const VERSION = "0.12.0";
 export {
   VERSION
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "private": false,
   "description": "Context-aware script runner for PNPM monorepos",
   "keywords": [
@@ -30,9 +30,11 @@
     "ensure-prepublish-hooks": "bin/ensure-prepublish-hooks.js",
     "nmr": "bin/nmr.js",
     "nmr-report-overrides": "bin/nmr-report-overrides.js",
+    "nmr-sync-agent-files": "bin/nmr-sync-agent-files.js",
     "nmr-sync-pnpm-version": "bin/nmr-sync-pnpm-version.js"
   },
   "files": [
+    "AGENTS.md",
     "bin",
     "dist"
   ],