@williamthorsen/nmr-core 0.3.0

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright (c) 2026 William Thorsen
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+The software is provided "as is" and the author disclaims all warranties with regard to this software including all implied warranties of merchantability and fitness. In no event shall the author be liable for any special, direct, indirect, or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.

package/README.md

@@ -0,0 +1,21 @@
+# @williamthorsen/nmr-core
+
+Shared utilities for node-monorepo-tools packages.
+
+This package serves as the shared library foundation for the monorepo. For the nmr CLI tool, see [`@williamthorsen/nmr`](../nmr).
+
+<!-- section:release-notes -->
+## Release notes — v0.3.0 (2026-04-23)
+
+### Features
+
+- Scaffold audit.yaml workflow from audit-deps init (#277)
+
+  Adds GitHub Actions workflow scaffolding to `audit-deps init`. Running the command now writes both `.config/audit-deps.config.json` and `.github/workflows/audit.yaml` in the target repo, so that consumers no longer have to copy the canonical caller workflow by hand from this repo. The workflow content is shipped as a bundled template that ships to npm, and the repo's own workflow is kept byte-identical to that template via a consistency test — the canonical workflow cannot silently drift from what is published.
+<!-- /section:release-notes -->
+
+## Installation
+
+```bash
+pnpm add -D @williamthorsen/nmr-core
+```

package/dist/esm/.cache

@@ -0,0 +1 @@
+45293b659d2a5fd6eb962de2df0c6baec80dcb02ed10f63893831df600a7a39b

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

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

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

@@ -0,0 +1,9 @@
+import { reportOverrides } from "./commands/report-overrides.js";
+import { findMonorepoRoot } from "./context.js";
+try {
+  const monorepoRoot = findMonorepoRoot();
+  reportOverrides(monorepoRoot);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/dist/esm/cli-sync-pnpm-version.d.ts

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

package/dist/esm/cli-sync-pnpm-version.js

@@ -0,0 +1,9 @@
+import { syncPnpmVersion } from "./commands/sync-pnpm-version.js";
+import { findMonorepoRoot } from "./context.js";
+try {
+  const monorepoRoot = findMonorepoRoot();
+  syncPnpmVersion(monorepoRoot);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/dist/esm/cli.d.ts

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

package/dist/esm/cli.js

@@ -0,0 +1,110 @@
+import process from "node:process";
+import { resolveContext } from "./context.js";
+import { generateHelp } from "./help.js";
+import { buildRootRegistry, buildWorkspaceRegistry, resolveScript } from "./resolver.js";
+import { runCommand } from "./runner.js";
+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,
+    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 === "-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);
+  const context = await resolveContext();
+  if (parsed.help || !parsed.command) {
+    console.info(generateHelp(context.config));
+    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) {
+    const delegateCmd = `pnpm --recursive exec nmr ${command}${passthrough}`;
+    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 resolved = resolveScript(command, registry, context.packageDir);
+  if (!resolved) {
+    console.error(`Unknown command: ${command}`);
+    process.exit(1);
+  }
+  if (resolved.command === "") {
+    if (!parsed.quiet) {
+      console.info("Override script is defined but empty. Skipping.");
+    }
+    process.exit(0);
+  }
+  if (resolved.source === "package" && !parsed.quiet) {
+    console.info(`Using override script: ${resolved.command}`);
+  }
+  const fullCommand = resolved.command + passthrough;
+  const code = runCommand(fullCommand, void 0, runOptions);
+  process.exit(code);
+}
+try {
+  await main();
+} catch (error) {
+  console.error(error);
+  process.exit(1);
+}

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

@@ -0,0 +1 @@
+export declare function reportOverrides(monorepoRoot: string): void;

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

@@ -0,0 +1,15 @@
+import { getPnpmOverrides, readPackageJson } from "../helpers/package-json.js";
+function reportOverrides(monorepoRoot) {
+  const pkg = readPackageJson(monorepoRoot);
+  const overrides = getPnpmOverrides(pkg);
+  if (!overrides || Object.keys(overrides).length === 0) {
+    return;
+  }
+  console.warn("\u{1F512} WARN: pnpm overrides are active! Check whether these are still needed:");
+  for (const [name, version] of Object.entries(overrides)) {
+    console.warn(`- ${name} \u2192 ${version}`);
+  }
+}
+export {
+  reportOverrides
+};

package/dist/esm/commands/sync-pnpm-version.d.ts

@@ -0,0 +1,3 @@
+declare function extractPnpmVersion(packageManager: string | undefined): string | null;
+export declare function syncPnpmVersion(monorepoRoot: string): void;
+export { extractPnpmVersion };

package/dist/esm/commands/sync-pnpm-version.js

@@ -0,0 +1,42 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { CodeQualityPnpmWorkflowSchema, getPnpmVersion } from "../helpers/code-quality-pnpm-action.js";
+import { readPackageJson } from "../helpers/package-json.js";
+import { readYamlFile } from "../helpers/yaml-utils.js";
+const WORKFLOW_RELATIVE_PATH = ".github/workflows/code-quality.yaml";
+function extractPnpmVersion(packageManager) {
+  if (!packageManager) {
+    return null;
+  }
+  const match = /^pnpm@(.+)$/.exec(packageManager);
+  return match?.[1] ?? null;
+}
+function syncPnpmVersion(monorepoRoot) {
+  console.info("Synchronizing pnpm version in GitHub workflow...");
+  const pkg = readPackageJson(monorepoRoot);
+  const pnpmVersion = extractPnpmVersion(pkg.packageManager);
+  if (!pnpmVersion) {
+    throw new Error(
+      `Could not extract pnpm version from package.json packageManager field
+packageManager field: ${pkg.packageManager ?? "(not set)"}`
+    );
+  }
+  console.info(`Package.json pnpm version: ${pnpmVersion}`);
+  const workflowPath = path.join(monorepoRoot, WORKFLOW_RELATIVE_PATH);
+  const workflowData = readYamlFile(workflowPath);
+  const workflow = CodeQualityPnpmWorkflowSchema.parse(workflowData);
+  const currentWorkflowVersion = getPnpmVersion(workflow);
+  console.info(`Current workflow pnpm version: ${currentWorkflowVersion}`);
+  if (currentWorkflowVersion === pnpmVersion) {
+    console.info("Workflow pnpm version is already up to date");
+    return;
+  }
+  const originalContent = readFileSync(workflowPath, "utf8");
+  const updatedContent = originalContent.replace(/(\s+pnpm-version:\s+)(['"]?)[\d.]+\2/, `$1$2${pnpmVersion}$2`);
+  writeFileSync(workflowPath, updatedContent, "utf8");
+  console.info(`\u2713 Updated workflow pnpm version: ${currentWorkflowVersion} \u2192 ${pnpmVersion}`);
+}
+export {
+  extractPnpmVersion,
+  syncPnpmVersion
+};

package/dist/esm/config.d.ts

@@ -0,0 +1,6 @@
+export interface NmrConfig {
+    workspaceScripts?: Record<string, string | string[]>;
+    rootScripts?: Record<string, string | string[]>;
+}
+export declare function defineConfig(config: NmrConfig): NmrConfig;
+export declare function loadConfig(monorepoRoot: string): Promise<NmrConfig>;

package/dist/esm/config.js

@@ -0,0 +1,21 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { createJiti } from "jiti";
+const CONFIG_FILENAME = "nmr.config.ts";
+const CONFIG_DIR = ".config";
+function defineConfig(config) {
+  return config;
+}
+async function loadConfig(monorepoRoot) {
+  const configPath = path.join(monorepoRoot, CONFIG_DIR, CONFIG_FILENAME);
+  if (!existsSync(configPath)) {
+    return {};
+  }
+  const jiti = createJiti(path.join(monorepoRoot, "package.json"));
+  const loaded = await jiti.import(configPath, { default: true });
+  return loaded;
+}
+export {
+  defineConfig,
+  loadConfig
+};

package/dist/esm/context.d.ts

@@ -0,0 +1,11 @@
+import type { NmrConfig } from './config.js';
+export interface ResolvedContext {
+    monorepoRoot: string;
+    isRoot: boolean;
+    packageDir?: string;
+    config: NmrConfig;
+}
+export declare function findMonorepoRoot(startDir?: string): string;
+export declare function getWorkspacePackageDirs(monorepoRoot: string): string[];
+export declare function findContainingPackageDir(dir: string, workspacePackageDirs: string[]): string | undefined;
+export declare function resolveContext(cwd?: string): Promise<ResolvedContext>;

package/dist/esm/context.js

@@ -0,0 +1,84 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import yaml from "js-yaml";
+import { loadConfig } from "./config.js";
+import { isObject } from "./helpers/type-guards.js";
+function findMonorepoRoot(startDir) {
+  let dir = path.resolve(startDir ?? process.cwd());
+  for (; ; ) {
+    if (existsSync(path.join(dir, "pnpm-workspace.yaml"))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      throw new Error("Could not find monorepo root: no pnpm-workspace.yaml found in any parent directory");
+    }
+    dir = parent;
+  }
+}
+function getWorkspacePackageDirs(monorepoRoot) {
+  const workspaceFile = path.join(monorepoRoot, "pnpm-workspace.yaml");
+  const content = readFileSync(workspaceFile, "utf8");
+  const parsed = yaml.load(content);
+  const packages = getPackagesFromParsedYaml(parsed);
+  if (!packages) {
+    return [];
+  }
+  const dirs = [];
+  for (const pattern of packages) {
+    if (pattern.endsWith("/*")) {
+      const prefix = pattern.slice(0, -2);
+      const prefixDir = path.resolve(monorepoRoot, prefix);
+      if (existsSync(prefixDir)) {
+        for (const entry of readdirSync(prefixDir)) {
+          const fullPath = path.join(prefixDir, entry);
+          if (statSync(fullPath).isDirectory() && existsSync(path.join(fullPath, "package.json"))) {
+            dirs.push(fullPath);
+          }
+        }
+      }
+    } else if (!pattern.includes("*")) {
+      const fullPath = path.resolve(monorepoRoot, pattern);
+      if (existsSync(fullPath) && existsSync(path.join(fullPath, "package.json"))) {
+        dirs.push(fullPath);
+      }
+    }
+  }
+  return dirs;
+}
+function findContainingPackageDir(dir, workspacePackageDirs) {
+  const resolved = path.resolve(dir);
+  for (const pkgDir of workspacePackageDirs) {
+    const resolvedPkgDir = path.resolve(pkgDir);
+    if (resolved === resolvedPkgDir || resolved.startsWith(resolvedPkgDir + path.sep)) {
+      return resolvedPkgDir;
+    }
+  }
+  return void 0;
+}
+function getPackagesFromParsedYaml(parsed) {
+  if (!isObject(parsed)) return void 0;
+  const packages = parsed.packages;
+  if (!Array.isArray(packages)) return void 0;
+  if (!packages.every((p) => typeof p === "string")) return void 0;
+  return packages;
+}
+async function resolveContext(cwd) {
+  const resolvedCwd = path.resolve(cwd ?? process.cwd());
+  const monorepoRoot = findMonorepoRoot(resolvedCwd);
+  const config = await loadConfig(monorepoRoot);
+  const workspaceDirs = getWorkspacePackageDirs(monorepoRoot);
+  const packageDir = findContainingPackageDir(resolvedCwd, workspaceDirs);
+  return {
+    monorepoRoot,
+    isRoot: packageDir === void 0,
+    ...packageDir === void 0 ? {} : { packageDir },
+    config
+  };
+}
+export {
+  findContainingPackageDir,
+  findMonorepoRoot,
+  getWorkspacePackageDirs,
+  resolveContext
+};

package/dist/esm/findPackageRoot.d.ts

@@ -0,0 +1 @@
+export declare function findPackageRoot(fromUrl: string): string;

package/dist/esm/findPackageRoot.js

@@ -0,0 +1,17 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+function findPackageRoot(fromUrl) {
+  let dir = dirname(fileURLToPath(fromUrl));
+  while (!existsSync(resolve(dir, "package.json"))) {
+    const parent = dirname(dir);
+    if (parent === dir) {
+      throw new Error("Could not find package root from " + fromUrl);
+    }
+    dir = parent;
+  }
+  return dir;
+}
+export {
+  findPackageRoot
+};

package/dist/esm/help.d.ts

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

package/dist/esm/help.js

@@ -0,0 +1,31 @@
+import { buildRootRegistry, buildWorkspaceRegistry } from "./resolver.js";
+import { describeScript } from "./resolver.js";
+function generateHelp(config) {
+  const lines = [
+    "Usage: nmr [flags] <command> [args...]",
+    "",
+    "Flags:",
+    "  -F, --filter <pattern>   Run command in matching packages",
+    "  -R, --recursive          Run command in all packages",
+    "  -w, --workspace-root     Run root command regardless of cwd",
+    "  -q, --quiet              Suppress output on success; show full output on failure",
+    "  -?, --help               Show this help",
+    "      --int-test           Use integration test scripts",
+    "",
+    "Workspace commands:"
+  ];
+  formatRegistry(buildWorkspaceRegistry(config, false), lines);
+  lines.push("", "Root commands:");
+  formatRegistry(buildRootRegistry(config), lines);
+  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);
+  for (const [key, value] of Object.entries(registry)) {
+    lines.push(`  ${key.padEnd(pad)} ${describeScript(value)}`);
+  }
+}
+export {
+  generateHelp
+};

package/dist/esm/helpers/code-quality-pnpm-action.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+export declare const CodeQualityPnpmWorkflowSchema: z.ZodObject<{
+    jobs: z.ZodObject<{
+        'code-quality': z.ZodObject<{
+            with: z.ZodObject<{
+                'pnpm-version': z.ZodString;
+            }, z.core.$loose>;
+        }, z.core.$loose>;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+export type CodeQualityPnpmWorkflow = z.infer<typeof CodeQualityPnpmWorkflowSchema>;
+export declare function getPnpmVersion(workflow: CodeQualityPnpmWorkflow): string;

package/dist/esm/helpers/code-quality-pnpm-action.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+const CodeQualityPnpmWorkflowSchema = z.looseObject({
+  jobs: z.looseObject({
+    "code-quality": z.looseObject({
+      with: z.looseObject({
+        "pnpm-version": z.string()
+      })
+    })
+  })
+});
+function getPnpmVersion(workflow) {
+  return workflow.jobs["code-quality"].with["pnpm-version"];
+}
+export {
+  CodeQualityPnpmWorkflowSchema,
+  getPnpmVersion
+};

package/dist/esm/helpers/package-json.d.ts

@@ -0,0 +1,11 @@
+export interface PackageJson {
+    name?: string;
+    version?: string;
+    packageManager?: string;
+    scripts?: Record<string, string>;
+    pnpm?: {
+        overrides?: Record<string, string>;
+    };
+}
+export declare function readPackageJson(dir: string): PackageJson;
+export declare function getPnpmOverrides(pkg: PackageJson): Record<string, string> | undefined;

package/dist/esm/helpers/package-json.js

@@ -0,0 +1,45 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { isObject } from "./type-guards.js";
+function readPackageJson(dir) {
+  const content = readFileSync(path.join(dir, "package.json"), "utf8");
+  const parsed = JSON.parse(content);
+  if (!isObject(parsed)) {
+    throw new TypeError(`Invalid package.json in ${dir}: expected an object`);
+  }
+  const pkg = {};
+  if (typeof parsed.name === "string") pkg.name = parsed.name;
+  if (typeof parsed.version === "string") pkg.version = parsed.version;
+  if (typeof parsed.packageManager === "string") pkg.packageManager = parsed.packageManager;
+  if (isObject(parsed.scripts)) {
+    const scripts = {};
+    for (const [key, val] of Object.entries(parsed.scripts)) {
+      if (typeof val === "string") scripts[key] = val;
+    }
+    pkg.scripts = scripts;
+  }
+  if (isObject(parsed.pnpm)) {
+    const pnpm = parsed.pnpm;
+    if (isObject(pnpm.overrides)) {
+      const overrides = {};
+      for (const [key, val] of Object.entries(pnpm.overrides)) {
+        if (typeof val === "string") overrides[key] = val;
+      }
+      pkg.pnpm = { overrides };
+    }
+  }
+  return pkg;
+}
+function getPnpmOverrides(pkg) {
+  if (!isObject(pkg.pnpm)) return void 0;
+  const overrides = pkg.pnpm.overrides;
+  if (!isObject(overrides)) return void 0;
+  for (const value of Object.values(overrides)) {
+    if (typeof value !== "string") return void 0;
+  }
+  return overrides;
+}
+export {
+  getPnpmOverrides,
+  readPackageJson
+};

package/dist/esm/helpers/type-guards.d.ts

@@ -0,0 +1 @@
+export declare function isObject(value: unknown): value is Record<string, unknown>;

package/dist/esm/helpers/type-guards.js

@@ -0,0 +1,6 @@
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+export {
+  isObject
+};

package/dist/esm/helpers/yaml-utils.d.ts

@@ -0,0 +1 @@
+export declare function readYamlFile(filepath: string): unknown;

package/dist/esm/helpers/yaml-utils.js

@@ -0,0 +1,14 @@
+import { readFileSync } from "node:fs";
+import yaml from "js-yaml";
+function readYamlFile(filepath) {
+  try {
+    const content = readFileSync(filepath, "utf8");
+    return yaml.load(content);
+  } catch (error) {
+    throw new Error(`Failed to read YAML file: ${filepath}
+${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+export {
+  readYamlFile
+};

package/dist/esm/index.d.ts

@@ -0,0 +1,7 @@
+export declare const PACKAGE_NAME = "@williamthorsen/nmr-core";
+export { findPackageRoot } from './findPackageRoot.js';
+export type { FlagDefinition, FlagSchema, ParsedArgs, ParsedFlags } from './parseArgs.js';
+export { parseArgs, translateParseError } from './parseArgs.js';
+export { printError, printSkip, printStep, printSuccess, reportWriteResult } from './terminal.js';
+export type { WriteOutcome, WriteResult } from './writeFileWithCheck.js';
+export { writeFileWithCheck } from './writeFileWithCheck.js';

package/dist/esm/index.js

@@ -0,0 +1,17 @@
+const PACKAGE_NAME = "@williamthorsen/nmr-core";
+import { findPackageRoot } from "./findPackageRoot.js";
+import { parseArgs, translateParseError } from "./parseArgs.js";
+import { printError, printSkip, printStep, printSuccess, reportWriteResult } from "./terminal.js";
+import { writeFileWithCheck } from "./writeFileWithCheck.js";
+export {
+  PACKAGE_NAME,
+  findPackageRoot,
+  parseArgs,
+  printError,
+  printSkip,
+  printStep,
+  printSuccess,
+  reportWriteResult,
+  translateParseError,
+  writeFileWithCheck
+};

package/dist/esm/parseArgs.d.ts

@@ -0,0 +1,15 @@
+export interface FlagDefinition {
+    long: string;
+    type: 'boolean' | 'string';
+    short?: string;
+}
+export type FlagSchema = Record<string, FlagDefinition>;
+export type ParsedFlags<S extends FlagSchema> = {
+    [K in keyof S]: S[K]['type'] extends 'boolean' ? boolean : string | undefined;
+};
+export interface ParsedArgs<S extends FlagSchema> {
+    flags: ParsedFlags<S>;
+    positionals: string[];
+}
+export declare function parseArgs<S extends FlagSchema>(argv: string[], schema: S): ParsedArgs<S>;
+export declare function translateParseError(error: unknown): string;

package/dist/esm/parseArgs.js

@@ -0,0 +1,93 @@
+function handleEqualsForm(arg, eqIndex, longToKey, definitions) {
+  const longFlag = arg.slice(0, eqIndex);
+  const key = longToKey.get(longFlag);
+  if (key === void 0) {
+    throw new Error(`unknown flag '${longFlag}'`);
+  }
+  const def = definitions.get(key);
+  if (def?.type === "boolean") {
+    throw new Error(`flag '${longFlag}' does not accept a value`);
+  }
+  const value = arg.slice(eqIndex + 1);
+  if (value === "") {
+    throw new Error(`${longFlag} requires a value`);
+  }
+  return { key, value };
+}
+function handleBareFlag(arg, index, argv, longToKey, shortToKey, definitions) {
+  const key = longToKey.get(arg) ?? shortToKey.get(arg);
+  if (key === void 0) {
+    throw new Error(`unknown flag '${arg}'`);
+  }
+  const def = definitions.get(key);
+  if (def?.type === "boolean") {
+    return { key, value: true, advance: 0 };
+  }
+  const next = argv[index + 1];
+  if (next === void 0 || next.startsWith("-") && next !== "-") {
+    throw new Error(`${def?.long} requires a value`);
+  }
+  return { key, value: next, advance: 1 };
+}
+function buildLookupTables(schema) {
+  const longToKey = /* @__PURE__ */ new Map();
+  const shortToKey = /* @__PURE__ */ new Map();
+  const definitions = /* @__PURE__ */ new Map();
+  for (const [key, def] of Object.entries(schema)) {
+    longToKey.set(def.long, key);
+    definitions.set(key, def);
+    if (def.short !== void 0) {
+      shortToKey.set(def.short, key);
+    }
+  }
+  return { longToKey, shortToKey, definitions };
+}
+function parseArgsInternal(argv, schema) {
+  const { longToKey, shortToKey, definitions } = buildLookupTables(schema);
+  const flags = {};
+  for (const [key, def] of Object.entries(schema)) {
+    flags[key] = def.type === "boolean" ? false : void 0;
+  }
+  const positionals = [];
+  let pastDelimiter = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i] ?? "";
+    if (pastDelimiter) {
+      positionals.push(arg);
+      continue;
+    }
+    if (arg === "--") {
+      pastDelimiter = true;
+      continue;
+    }
+    const eqIndex = arg.indexOf("=");
+    if (eqIndex !== -1 && arg.startsWith("--")) {
+      const { key, value } = handleEqualsForm(arg, eqIndex, longToKey, definitions);
+      flags[key] = value;
+      continue;
+    }
+    if (arg.startsWith("-") && arg !== "-") {
+      const { key, value, advance } = handleBareFlag(arg, i, argv, longToKey, shortToKey, definitions);
+      flags[key] = value;
+      i += advance;
+      continue;
+    }
+    positionals.push(arg);
+  }
+  return { flags, positionals };
+}
+function parseArgs(argv, schema) {
+  return parseArgsInternal(argv, schema);
+}
+function translateParseError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const flagMatch = message.match(/^unknown flag '(.+)'$/);
+  if (flagMatch?.[1] !== void 0) {
+    return `Unknown option: ${flagMatch[1]}`;
+  }
+  return message;
+}
+export {
+  parseArgs,
+  translateParseError
+};

package/dist/esm/registries.d.ts

@@ -0,0 +1,5 @@
+export type ScriptValue = string | string[];
+export type ScriptRegistry = Record<string, ScriptValue>;
+declare function getDefaultWorkspaceScripts(useIntTests: boolean): ScriptRegistry;
+declare function getDefaultRootScripts(): ScriptRegistry;
+export { getDefaultRootScripts, getDefaultWorkspaceScripts };

package/dist/esm/registries.js

@@ -0,0 +1,67 @@
+function getDefaultWorkspaceScripts(useIntTests) {
+  const commonScripts = {
+    build: ["compile", "generate-typings"],
+    check: ["typecheck", "fmt:check", "lint:check", "test"],
+    "check:strict": ["typecheck", "fmt:check", "lint:strict", "test:coverage"],
+    clean: "pnpm exec rimraf dist/*",
+    compile: "tsx ../../config/build.ts",
+    fmt: "prettier --list-different --write .",
+    "fmt:check": "prettier --check .",
+    "generate-typings": "tsc --project tsconfig.generate-typings.json",
+    lint: "eslint --fix .",
+    "lint:check": "eslint .",
+    "lint:strict": "strict-lint",
+    typecheck: "tsgo --noEmit",
+    "view-coverage": "open coverage/index.html"
+  };
+  const integrationTestOverrides = {
+    test: "pnpm exec vitest --config=vitest.standalone.config.ts",
+    "test:coverage": "pnpm exec vitest --config=vitest.standalone.config.ts --coverage",
+    "test:integration": "pnpm exec vitest --config=vitest.integration.config.ts",
+    "test:watch": "pnpm exec vitest --config=vitest.standalone.config.ts --watch"
+  };
+  const standardTestOverrides = {
+    test: "pnpm exec vitest",
+    "test:coverage": "pnpm exec vitest --coverage",
+    "test:watch": "pnpm exec vitest --watch"
+  };
+  return {
+    ...commonScripts,
+    ...useIntTests ? integrationTestOverrides : standardTestOverrides
+  };
+}
+function getDefaultRootScripts() {
+  return {
+    audit: ["audit:prod", "audit:dev"],
+    "audit:dev": "pnpm dlx audit-ci@^6 --config .audit-ci/config.dev.json5",
+    "audit:prod": "pnpm dlx audit-ci@^6 --config .audit-ci/config.prod.json5",
+    build: "pnpm --recursive exec nmr build",
+    check: ["typecheck", "fmt:check", "lint:check", "test"],
+    "check:strict": ["typecheck", "fmt:check", "lint:strict", "test:coverage", "audit"],
+    ci: ["check:strict", "build"],
+    fmt: `sh -c 'prettier --list-different --write "\${@:-.}"' --`,
+    "fmt:check": `sh -c 'prettier --check "\${@:-.}"' --`,
+    lint: "nmr root:lint && pnpm --recursive exec nmr lint",
+    "lint:check": "nmr root:lint:check && pnpm --recursive exec nmr lint:check",
+    "lint:strict": "nmr root:lint:strict && pnpm --recursive exec nmr lint:strict",
+    outdated: "pnpm outdated --compatible --recursive",
+    "outdated:latest": "pnpm outdated --recursive",
+    "report-overrides": "nmr-report-overrides",
+    "root:lint": "eslint --fix --ignore-pattern 'packages/**' .",
+    "root:lint:check": "eslint --ignore-pattern 'packages/**' .",
+    "root:lint:strict": "strict-lint --ignore-pattern 'packages/**' .",
+    "root:test": "vitest --config ./vitest.root.config.ts",
+    "root:typecheck": "tsgo --noEmit",
+    "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",
+    "test:watch": "vitest --watch",
+    typecheck: "nmr root:typecheck && pnpm --recursive exec nmr typecheck",
+    update: "pnpm update --recursive",
+    "update:latest": "pnpm update --latest --recursive"
+  };
+}
+export {
+  getDefaultRootScripts,
+  getDefaultWorkspaceScripts
+};

package/dist/esm/resolver.d.ts

@@ -0,0 +1,11 @@
+import type { NmrConfig } from './config.js';
+import type { ScriptRegistry, ScriptValue } from './registries.js';
+export interface ResolvedScript {
+    command: string;
+    source: 'default' | 'package';
+}
+export declare function expandScript(script: ScriptValue): string;
+export declare function describeScript(script: ScriptValue): string;
+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;

package/dist/esm/resolver.js

@@ -0,0 +1,64 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { isObject } from "./helpers/type-guards.js";
+import { getDefaultRootScripts, getDefaultWorkspaceScripts } from "./registries.js";
+function expandScript(script) {
+  if (typeof script === "string") {
+    return script;
+  }
+  return script.map((s) => `nmr ${s}`).join(" && ");
+}
+function describeScript(script) {
+  return typeof script === "string" ? script : `[${script.join(", ")}]`;
+}
+function readPackageJsonScripts(packageDir) {
+  try {
+    const raw = readFileSync(path.join(packageDir, "package.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    if (!isObject(parsed)) return void 0;
+    const scripts = parsed.scripts;
+    if (!isObject(scripts)) return void 0;
+    const result = {};
+    for (const [key, val] of Object.entries(scripts)) {
+      if (typeof val === "string") result[key] = val;
+    }
+    return result;
+  } catch {
+    return void 0;
+  }
+}
+function buildWorkspaceRegistry(config, useIntTests) {
+  return {
+    ...getDefaultWorkspaceScripts(useIntTests),
+    ...config.workspaceScripts
+  };
+}
+function buildRootRegistry(config) {
+  return {
+    ...getDefaultRootScripts(),
+    ...config.rootScripts
+  };
+}
+function resolveScript(commandName, registry, packageDir) {
+  if (packageDir) {
+    const pkgScripts = readPackageJsonScripts(packageDir);
+    if (pkgScripts && commandName in pkgScripts) {
+      const override = pkgScripts[commandName];
+      if (override !== void 0) {
+        return { command: override, source: "package" };
+      }
+    }
+  }
+  const registryEntry = registry[commandName];
+  if (registryEntry === void 0) {
+    return void 0;
+  }
+  return { command: expandScript(registryEntry), source: "default" };
+}
+export {
+  buildRootRegistry,
+  buildWorkspaceRegistry,
+  describeScript,
+  expandScript,
+  resolveScript
+};

package/dist/esm/runner.d.ts

@@ -0,0 +1,4 @@
+export interface RunCommandOptions {
+    quiet?: boolean;
+}
+export declare function runCommand(command: string, cwd?: string, options?: RunCommandOptions): number;

package/dist/esm/runner.js

@@ -0,0 +1,38 @@
+import { execSync } 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;
+      }
+    }
+    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);
+    }
+  }
+}
+export {
+  runCommand
+};

package/dist/esm/terminal.d.ts

@@ -0,0 +1,6 @@
+import type { WriteResult } from './writeFileWithCheck.ts';
+export declare function printStep(message: string): void;
+export declare function printSuccess(message: string): void;
+export declare function printSkip(message: string): void;
+export declare function printError(message: string): void;
+export declare function reportWriteResult(result: WriteResult, dryRun: boolean): void;

package/dist/esm/terminal.js

@@ -0,0 +1,55 @@
+function printStep(message) {
+  console.info(`
+> ${message}`);
+}
+function printSuccess(message) {
+  console.info(`  \u2705 ${message}`);
+}
+function printSkip(message) {
+  console.info(`  \u26A0\uFE0F ${message}`);
+}
+function printError(message) {
+  console.error(`  \u274C ${message}`);
+}
+function reportWriteResult(result, dryRun) {
+  switch (result.outcome) {
+    case "created":
+      if (dryRun) {
+        printSuccess(`[dry-run] Would create ${result.filePath}`);
+      } else {
+        printSuccess(`Created ${result.filePath}`);
+      }
+      break;
+    case "overwritten":
+      if (dryRun) {
+        printSuccess(`[dry-run] Would overwrite ${result.filePath}`);
+      } else {
+        printSuccess(`Overwrote ${result.filePath}`);
+      }
+      break;
+    case "up-to-date":
+      printSuccess(`${result.filePath} (up to date)`);
+      break;
+    case "skipped":
+      if (result.error) {
+        printSkip(`${result.filePath} (could not read for comparison: ${result.error})`);
+      } else {
+        printSkip(`${result.filePath} (already exists)`);
+      }
+      break;
+    case "failed":
+      if (result.error) {
+        printError(`Failed to write ${result.filePath}: ${result.error}`);
+      } else {
+        printError(`Failed to write ${result.filePath}`);
+      }
+      break;
+  }
+}
+export {
+  printError,
+  printSkip,
+  printStep,
+  printSuccess,
+  reportWriteResult
+};

package/dist/esm/tests/consistency.d.ts

@@ -0,0 +1 @@
+export declare function runConsistencyChecks(): void;

package/dist/esm/tests/consistency.js

@@ -0,0 +1,70 @@
+import assert from "node:assert";
+import fs from "node:fs";
+import path from "node:path";
+import yaml from "js-yaml";
+import { describe, expect, it } from "vitest";
+import { findMonorepoRoot } from "../context.js";
+import { getRuntimeVersionFromAsdf } from "./helpers/get-runtime-version-from-asdf.js";
+import { getValueAtPathOrThrow } from "./helpers/get-value-at-path.js";
+const GITHUB_ACTION_FILE_PATH = ".github/workflows/code-quality.yaml";
+function checkPnpmVersionConsistency(monorepoRoot) {
+  describe("pnpm version consistency", () => {
+    it("pnpm version is the same in GitHub action and package.json", async () => {
+      const actionVersion = await getPnpmVersionFromAction(monorepoRoot);
+      const packageJsonVersion = getPnpmVersionFromPackageJson(monorepoRoot);
+      expect(actionVersion).toBe(packageJsonVersion);
+    });
+  });
+}
+function checkNodeVersionConsistency(monorepoRoot) {
+  describe("Node.js version consistency", () => {
+    it("version is the same in GitHub action and .tool-versions", async () => {
+      const toolVersion = await getRuntimeVersionFromAsdf("nodejs", monorepoRoot);
+      const actionVersion = await getNodeVersionFromAction(monorepoRoot);
+      expect(toolVersion).toBe(actionVersion);
+    });
+  });
+}
+async function getPnpmVersionFromAction(monorepoRoot) {
+  const actionPath = path.join(monorepoRoot, GITHUB_ACTION_FILE_PATH);
+  const actionYaml = await fs.promises.readFile(actionPath, { encoding: "utf8" });
+  const action = yaml.load(actionYaml);
+  assert.ok(action, "Action YAML not found");
+  const version = getValueAtPathOrThrow(action, "jobs.code-quality.with.pnpm-version");
+  assert.ok(typeof version === "string" && version.length > 0, "pnpm version not found in action");
+  return version;
+}
+function getPnpmVersionFromPackageJson(monorepoRoot) {
+  const pkgPath = path.join(monorepoRoot, "package.json");
+  const raw = fs.readFileSync(pkgPath, "utf8");
+  const pkg = JSON.parse(raw);
+  const pm = getValueAtPathOrThrow(pkg, "packageManager");
+  if (typeof pm !== "string") {
+    throw new TypeError('"packageManager" field missing or not a string in package.json.');
+  }
+  const [name, version] = pm.split("@");
+  if (name !== "pnpm") {
+    throw new Error("packageManager is not pnpm.");
+  }
+  if (!version) {
+    throw new Error("pnpm version missing in package.json.");
+  }
+  return version;
+}
+async function getNodeVersionFromAction(monorepoRoot) {
+  const actionPath = path.join(monorepoRoot, GITHUB_ACTION_FILE_PATH);
+  const actionYaml = await fs.promises.readFile(actionPath, { encoding: "utf8" });
+  const action = yaml.load(actionYaml);
+  assert.ok(action, "Action YAML not found");
+  const version = getValueAtPathOrThrow(action, "jobs.code-quality.with.node-version");
+  assert.ok(typeof version === "string" && version.length > 0, "Node.js version not found in action");
+  return version;
+}
+function runConsistencyChecks() {
+  const monorepoRoot = findMonorepoRoot();
+  checkPnpmVersionConsistency(monorepoRoot);
+  checkNodeVersionConsistency(monorepoRoot);
+}
+export {
+  runConsistencyChecks
+};

package/dist/esm/tests/helpers/get-runtime-version-from-asdf.d.ts

@@ -0,0 +1 @@
+export declare function getRuntimeVersionFromAsdf(runtime: string, monorepoRoot: string): Promise<string>;

package/dist/esm/tests/helpers/get-runtime-version-from-asdf.js

@@ -0,0 +1,15 @@
+import assert from "node:assert";
+import fs from "node:fs";
+import path from "node:path";
+async function getRuntimeVersionFromAsdf(runtime, monorepoRoot) {
+  const toolVersionsPath = path.join(monorepoRoot, ".tool-versions");
+  const toolVersions = await fs.promises.readFile(toolVersionsPath, { encoding: "utf8" });
+  const versionLine = toolVersions.split("\n").find((line) => line.trim().startsWith(runtime));
+  assert.ok(versionLine, `${runtime} not found in .tool-versions`);
+  const [, version] = versionLine.trim().split(/\s+/);
+  assert.ok(version, `${runtime} version missing in .tool-versions`);
+  return version;
+}
+export {
+  getRuntimeVersionFromAsdf
+};

package/dist/esm/tests/helpers/get-value-at-path.d.ts

@@ -0,0 +1 @@
+export declare function getValueAtPathOrThrow(obj: unknown, objPath: string): unknown;

package/dist/esm/tests/helpers/get-value-at-path.js

@@ -0,0 +1,34 @@
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function getValueAtPathOrThrow(obj, objPath) {
+  if (!isObject(obj)) {
+    throw new Error("Expected an object as root value.");
+  }
+  const keys = objPath.split(".");
+  let current = obj;
+  for (const key of keys) {
+    if (Array.isArray(current)) {
+      const index = Number(key);
+      if (Number.isNaN(index)) {
+        throw new TypeError(`Expected array index at segment "${key}" in path "${objPath}"`);
+      }
+      if (index >= 0 && index < current.length) {
+        current = current[index];
+      } else {
+        throw new Error(`Array index out of bounds: "${key}" in path "${objPath}"`);
+      }
+    } else if (isObject(current)) {
+      if (!(key in current)) {
+        throw new Error(`Missing key "${key}" in path "${objPath}"`);
+      }
+      current = current[key];
+    } else {
+      throw new Error(`Unexpected non-object/non-array at segment "${key}" in path "${objPath}"`);
+    }
+  }
+  return current;
+}
+export {
+  getValueAtPathOrThrow
+};

package/dist/esm/writeFileWithCheck.d.ts

@@ -0,0 +1,10 @@
+export type WriteOutcome = 'created' | 'overwritten' | 'up-to-date' | 'skipped' | 'failed';
+export interface WriteResult {
+    filePath: string;
+    outcome: WriteOutcome;
+    error?: string;
+}
+export declare function writeFileWithCheck(filePath: string, content: string, options: {
+    dryRun: boolean;
+    overwrite: boolean;
+}): WriteResult;

package/dist/esm/writeFileWithCheck.js

@@ -0,0 +1,41 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+function normalizeTrailingWhitespace(content) {
+  return content.split("\n").map((line) => line.trimEnd()).join("\n").trimEnd();
+}
+function writeFileWithCheck(filePath, content, options) {
+  const { dryRun, overwrite } = options;
+  const fileExists = existsSync(filePath);
+  if (fileExists && !overwrite) {
+    try {
+      const existing = readFileSync(filePath, "utf8");
+      if (normalizeTrailingWhitespace(existing) === normalizeTrailingWhitespace(content)) {
+        return { filePath, outcome: "up-to-date" };
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return { filePath, outcome: "skipped", error: message };
+    }
+    return { filePath, outcome: "skipped" };
+  }
+  const outcome = fileExists ? "overwritten" : "created";
+  if (dryRun) {
+    return { filePath, outcome };
+  }
+  try {
+    mkdirSync(dirname(filePath), { recursive: true });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { filePath, outcome: "failed", error: message };
+  }
+  try {
+    writeFileSync(filePath, content, "utf8");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { filePath, outcome: "failed", error: message };
+  }
+  return { filePath, outcome };
+}
+export {
+  writeFileWithCheck
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@williamthorsen/nmr-core",
+  "version": "0.3.0",
+  "private": false,
+  "description": "Shared utilities for node-monorepo-tools packages",
+  "keywords": [
+    "monorepo",
+    "pnpm",
+    "utilities"
+  ],
+  "homepage": "https://github.com/williamthorsen/node-monorepo-tools/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/williamthorsen/node-monorepo-tools/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/williamthorsen/node-monorepo-tools.git",
+    "directory": "packages/core"
+  },
+  "license": "ISC",
+  "author": "William Thorsen <william@thorsen.dev> (https://github.com/williamthorsen)",
+  "type": "module",
+  "exports": {
+    ".": "./dist/esm/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {}
+}