@williamthorsen/nmr 0.54.1 → 0.55.0

package/.meta/changelog.json

@@ -1,4 +1,37 @@
 [
+  {
+    "version": "0.55.0",
+    "date": "2026-11-06",
+    "sections": [
+      {
+        "title": "🎉 Features",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Adds the built-in root command `lint:shell`, which runs the new `nmr-shellcheck` bin to lint every tracked `*.sh` file with nmr's pinned shellcheck and passes without downloading shellcheck when the repo does not track any. (#1161)",
+            "hash": "d5cb485398fbc00f81b5533bd8c71033d81e6026",
+            "entry": 1
+          },
+          {
+            "description": "Adds a warning to nmr's readyup kit that reports a `lint:shell` entry in `.config/nmr.config.ts`, which overrides the built-in command, and directs the repo to delete the entry. (#1161)",
+            "hash": "d5cb485398fbc00f81b5533bd8c71033d81e6026",
+            "entry": 2
+          }
+        ]
+      },
+      {
+        "title": "🐛 Bug fixes",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Adopt the crash convention in release-kit (#1158)",
+            "body": "Makes `release-kit` report a bug in its own code as `release-kit: internal error: <message>` followed by the stack, rather than as the `Error: <message>` line that it keeps for a failure in the user's input, config, or environment. The same change makes `nmr` and `v11y-check` print a Node system error, such as `EACCES` or `ENOENT`, as `Error: <message>` rather than as an internal error.",
+            "hash": "3a62cc768b23f37156c846f32fd4acaa70f7f931"
+          }
+        ]
+      }
+    ]
+  },
   {
     "version": "0.54.1",
     "date": "2026-11-05",

package/.readyup/kits/default.js

@@ -7691,6 +7691,7 @@ function buildRootScripts(workspaceGlobs) {
     "fmt:check": "nmr-fmt --check",
     lint: "eslint --fix .",
     "lint:check": "eslint .",
+    "lint:shell": "nmr-shellcheck",
     "lint:strict": "strict-lint",
     "lint:workflows": "nmr-actionlint",
     // The audit takes seconds and `ci` takes minutes, so the cheap gate fails first. The audit reads the
@@ -7880,6 +7881,8 @@ var INSTALL_LIFECYCLE_SCRIPTS = [
 ];
 var LEFTHOOK_CHECK_INSTALL_PATTERN = /\blefthook\s+check-install\b/;
 var LEFTHOOK_INSTALL_PATTERN = /\blefthook\s+install\b/;
+var LINT_SHELL_KEY_PATTERN = /['"]lint:shell['"]\s*:/;
+var NMR_CONFIG_PATH = ".config/nmr.config.ts";
 var rootScriptChecks = [
   {
     name: "root package.json has no nmr-provided scripts",
@@ -7887,6 +7890,13 @@ var rootScriptChecks = [
     quiet: true,
     check: noRedundantRootScripts,
     fix: "Remove scripts from root package.json that nmr provides as built-in root scripts, and invoke them through nmr directly"
+  },
+  {
+    name: ".config/nmr.config.ts does not override lint:shell",
+    severity: "warn",
+    quiet: true,
+    check: () => noLintShellOverride(),
+    fix: "Delete the `lint:shell` entry from `rootScripts` in .config/nmr.config.ts, because nmr provides `lint:shell` as a built-in root command that passes when the repo does not track any shell script"
   }
 ];
 var gitHookChecks = [
@@ -7914,6 +7924,11 @@ var legacyRunnerChecks = [
     fix: 'Remove "ws" script entries and replace any "pnpm run ws" invocations with nmr in each packages/*/package.json'
   }
 ];
+function noLintShellOverride(cwd = process.cwd()) {
+  const content = readFileIn(cwd, NMR_CONFIG_PATH);
+  if (content === void 0 || !LINT_SHELL_KEY_PATTERN.test(content)) return true;
+  return { ok: false, detail: `${NMR_CONFIG_PATH}: rootScripts.lint:shell` };
+}
 function noUnguardedLefthookInstall(cwd = process.cwd()) {
   const scripts = readRootScripts(cwd);
   const unguardedScripts = INSTALL_LIFECYCLE_SCRIPTS.flatMap((name) => {
@@ -9190,7 +9205,7 @@ function hasSupportedStrictLintVersion() {
   });
 }
 function getMinVersion() {
-  const pickedFields = { "version": "0.54.1" };
+  const pickedFields = { "version": "0.55.0" };
   if (typeof pickedFields["version"] !== "string") {
     throw new TypeError("nmr/package.json: 'version' must be a string");
   }

package/.readyup/manifest.json

@@ -27,7 +27,7 @@
           "checklist": "nmr",
           "checks": [
             "@williamthorsen/nmr in devDependencies",
-            "@williamthorsen/nmr >= 0.54.1",
+            "@williamthorsen/nmr >= 0.55.0",
             "pnpm-workspace.yaml exists",
             "catalogued dependencies use catalog:",
             "package.json has packageManager field",
@@ -38,6 +38,7 @@
             "eslint >= 10.0.0",
             "@williamthorsen/strict-lint >= 9.3.0",
             "root package.json has no nmr-provided scripts",
+            ".config/nmr.config.ts does not override lint:shell",
             "no root install script runs lefthook install unguarded",
             "all workspace packages can build",
             "every bin target is a committed wrapper",
@@ -109,10 +110,15 @@
           "path": "../../nmr-core/dist/esm/helpers/workspace-patterns.js"
         },
         {
-          "hash": "8fe9a346",
+          "hash": "76923c93",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/index.js"
         },
+        {
+          "hash": "85d76864",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/isAnticipatedFailure.js"
+        },
         {
           "hash": "de51ceb3",
           "kind": "module",
@@ -124,7 +130,7 @@
           "path": "../../nmr-core/dist/esm/runGit.js"
         },
         {
-          "hash": "6f46d90a",
+          "hash": "01ad20df",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/terminal.js"
         },
@@ -184,7 +190,7 @@
           "path": "lib/repo-files.ts"
         },
         {
-          "hash": "2a90a1d3",
+          "hash": "a62f92eb",
           "kind": "module",
           "path": "lib/root-scripts.ts"
         },
@@ -214,7 +220,7 @@
           "path": "lib/workspace-build.ts"
         },
         {
-          "hash": "dad7f436",
+          "hash": "f22b8da5",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -237,7 +243,7 @@
           "path": "../src/config.ts"
         },
         {
-          "hash": "b8e98c81",
+          "hash": "463c7bbd",
           "kind": "module",
           "path": "../src/default-scripts.ts"
         },
@@ -327,7 +333,7 @@
       "readyupVersion": "0.45.0",
       "source": "kits/default.ts",
       "sourceHash": "9fd61bf4",
-      "targetHash": "04e5d541"
+      "targetHash": "6eb9c2b5"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.55.0 — 2026-11-06
+
+### 🎉 Features
+
+- Adds the built-in root command `lint:shell`, which runs the new `nmr-shellcheck` bin to lint every tracked `*.sh` file with nmr's pinned shellcheck and passes without downloading shellcheck when the repo does not track any. (#1161)
+- Adds a warning to nmr's readyup kit that reports a `lint:shell` entry in `.config/nmr.config.ts`, which overrides the built-in command, and directs the repo to delete the entry. (#1161)
+
+### 🐛 Bug fixes
+
+- Adopt the crash convention in release-kit (#1158)
+
+  Makes `release-kit` report a bug in its own code as `release-kit: internal error: <message>` followed by the stack, rather than as the `Error: <message>` line that it keeps for a failure in the user's input, config, or environment. The same change makes `nmr` and `v11y-check` print a Node system error, such as `EACCES` or `ENOENT`, as `Error: <message>` rather than as an internal error.
+
 ## 0.54.1 — 2026-11-05
 
 ### 🐛 Bug fixes

package/README.md

@@ -5,14 +5,18 @@
 Context-aware script runner for pnpm monorepos. Includes 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.54.1 (2026-11-05)
+## Release notes — v0.55.0 (2026-11-06)
+
+### 🎉 Features
+
+- Adds the built-in root command `lint:shell`, which runs the new `nmr-shellcheck` bin to lint every tracked `*.sh` file with nmr's pinned shellcheck and passes without downloading shellcheck when the repo does not track any. (#1161)
+- Adds a warning to nmr's readyup kit that reports a `lint:shell` entry in `.config/nmr.config.ts`, which overrides the built-in command, and directs the repo to delete the entry. (#1161)
 
 ### 🐛 Bug fixes
 
-- Fixes the issue that `pnpm add` failed when an install hook such as `postinstall` ran an nmr command delegated by `NMR_DELEGATE` or the user config, because the host's frozen install rejected a manifest that was ahead of its lockfile, by making nmr run such a command on this machine unless `--delegate` or `--delegate-to` is passed. (#1151)
-- Fixes the issue that `nmr` printed an unexpected crash as its raw stack, whose first line, `Error: <message>`, read the same as a handled error; it now prints `nmr: internal error: <message>` followed by the stack frames, and still prints an error caused by the user's own config as `Error: <message>`. (#1153)
-- Fixes the issue that the `nmr` sub-bins, such as `nmr-compile` and `nmr-fmt`, and the `v11y` subcommands reported an unexpected crash as a handled `Error: <message>` line, rather than as `<bin>: internal error: <message>` with its stack frames. (#1157)
-- Fixes the issue that the bin scripts of `nmr`, `release-kit`, and `v11y-check` reported every error other than missing build output as `<bin>: failed to load: <message>` without a stack, which hid where the fault occurred. (#1157)
+- Adopt the crash convention in release-kit (#1158)
+
+  Makes `release-kit` report a bug in its own code as `release-kit: internal error: <message>` followed by the stack, rather than as the `Error: <message>` line that it keeps for a failure in the user's input, config, or environment. The same change makes `nmr` and `v11y-check` print a Node system error, such as `EACCES` or `ENOENT`, as `Error: <message>` rather than as an internal error.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -319,7 +323,7 @@ rdy list --from npm:@williamthorsen/nmr  # what nmr publishes
 - [Machine lock](docs/machine-lock.md): Which commands wait for one another, where the lock lives, and bypassing it
 - [Delegating to another machine](docs/delegate.md): The user config, `--delegate`, `--delegate-to`, `NMR_DELEGATE`, where a command runs, choosing among several hosts, what the host runs, and setting it up
 - [Dependency upgrades](docs/upgrades.md): `nmr upgrade`, the upgrade policy, the Node version pin, `report-catalog`, `report-overrides`, and `nmr-taze`
-- [Standalone utilities](docs/utilities.md): `nmr-actionlint`, `nmr-clean`, `nmr-compile`, `nmr-fmt`, `nmr-vitest`, and `ensure-prepublish-hooks`
+- [Standalone utilities](docs/utilities.md): `nmr-actionlint`, `nmr-clean`, `nmr-compile`, `nmr-fmt`, `nmr-shellcheck`, `nmr-vitest`, and `ensure-prepublish-hooks`
 - [Shared Vitest config](docs/vitest.md): Test tiers, test selections, the conventions check, and customization
 - [Shared Prettier config](docs/prettier.md): What it formats and how to customize it
 - [Workspace introspection](docs/workspace.md): The two workspace lookups

package/bin/nmr-shellcheck.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+try {
+  await import('../dist/esm/cli-shellcheck.js');
+} catch (error) {
+  if (error?.code === 'ERR_MODULE_NOT_FOUND') {
+    process.stderr.write('nmr-shellcheck: build output not found; run `pnpm run bootstrap` first\n');
+  } else {
+    const message = typeof error?.message === 'string' && error.message !== '' ? error.message : String(error);
+    const lines = typeof error?.stack === 'string' ? error.stack.split('\n') : [];
+    const firstFrame = lines.findIndex((line) => /^\s+at /.test(line));
+    const frames = firstFrame === -1 ? '' : `${lines.slice(firstFrame).join('\n')}\n`;
+    process.stderr.write(`nmr-shellcheck: internal error: ${message}\n${frames}`);
+  }
+  process.exit(1);
+}

package/dist/esm/check-cache.js

@@ -10,6 +10,7 @@ export const DEFAULT_CACHEABLE_COMMANDS = [
     'fix:check',
     'fmt:check',
     'lint:check',
+    'lint:shell',
     'lint:strict',
     'lint:workflows',
     'root:check',

package/dist/esm/cli-shellcheck.d.ts

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

package/dist/esm/cli-shellcheck.js

@@ -0,0 +1,11 @@
+import process from 'node:process';
+import { reportFailure } from '@williamthorsen/nmr-core';
+import { runShellcheck } from "./commands/shellcheck.js";
+import { findMonorepoRoot } from "./workspace.js";
+try {
+    process.exitCode = await runShellcheck(findMonorepoRoot(), process.argv.slice(2));
+}
+catch (error) {
+    reportFailure('nmr-shellcheck', error);
+    process.exitCode = 1;
+}

package/dist/esm/commands/shellcheck.d.ts

@@ -0,0 +1,25 @@
+import { type WorkflowTool } from './workflow-tools.js';
+/** How a spawned shellcheck ended. */
+export interface ShellcheckOutcome {
+    error?: Error | undefined;
+    signal: NodeJS.Signals | null;
+    status: number | null;
+}
+export interface RunShellcheckOptions {
+    /** Directory under which the pinned tools are cached; defaults to `node_modules/.cache/nmr-tools` at the root. */
+    cacheRoot?: string;
+    ensure?: (tool: WorkflowTool, cacheRoot: string) => Promise<string>;
+    /** Lists the tracked `*.sh` files under the root, relative to it. */
+    listFiles?: (monorepoRoot: string) => string[];
+    spawn?: (file: string, args: string[], cwd: string) => ShellcheckOutcome;
+}
+/**
+ * Lints the monorepo's tracked shell scripts with the pinned shellcheck and returns its exit status. Trailing
+ * arguments replace the file list. A repo that does not track any `*.sh` file passes without fetching the tool.
+ */
+export declare function runShellcheck(monorepoRoot: string, args: readonly string[], options?: RunShellcheckOptions): Promise<number>;
+/**
+ * Lists the `*.sh` files that git tracks under the root, relative to it. git's `*` also matches `/`, so the pathspec
+ * reaches every directory.
+ */
+export declare function listTrackedScripts(monorepoRoot: string): string[];

package/dist/esm/commands/shellcheck.js

@@ -0,0 +1,41 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { UserError } from '@williamthorsen/nmr-core';
+import { describeSignalExitCode } from "../child-process.js";
+import { ensureTool } from "./workflow-tools.js";
+export async function runShellcheck(monorepoRoot, args, options = {}) {
+    const shellcheckArgs = args.length > 0 ? [...args] : listPresentScripts(monorepoRoot, options.listFiles);
+    if (shellcheckArgs.length === 0) {
+        console.info('No shell scripts to lint: the working tree does not contain any tracked *.sh file.');
+        return 0;
+    }
+    const cacheRoot = options.cacheRoot ?? path.join(monorepoRoot, 'node_modules', '.cache', 'nmr-tools');
+    const ensure = options.ensure ?? ((tool, root) => ensureTool(tool, { cacheRoot: root }));
+    const shellcheckPath = await ensure('shellcheck', cacheRoot);
+    const outcome = (options.spawn ?? spawnInherited)(shellcheckPath, shellcheckArgs, monorepoRoot);
+    if (outcome.error !== undefined) {
+        throw new UserError(`Cannot run shellcheck: ${outcome.error.message}`, { cause: outcome.error });
+    }
+    if (outcome.signal !== null) {
+        return describeSignalExitCode(outcome.signal);
+    }
+    return outcome.status ?? 1;
+}
+export function listTrackedScripts(monorepoRoot) {
+    const result = spawnSync('git', ['ls-files', '-z', '--', '*.sh'], { cwd: monorepoRoot, encoding: 'utf8' });
+    if (result.error !== undefined) {
+        throw new UserError(`Cannot list tracked shell scripts: ${result.error.message}`, { cause: result.error });
+    }
+    if (result.status !== 0) {
+        throw new UserError(`Cannot list tracked shell scripts: ${result.stderr.trim()}`);
+    }
+    return result.stdout.split('\0').filter((file) => file !== '');
+}
+function listPresentScripts(monorepoRoot, listFiles = listTrackedScripts) {
+    return listFiles(monorepoRoot).filter((file) => fs.existsSync(path.join(monorepoRoot, file)));
+}
+function spawnInherited(file, args, cwd) {
+    const result = spawnSync(file, args, { cwd, stdio: 'inherit' });
+    return { error: result.error, signal: result.signal, status: result.status };
+}

package/dist/esm/default-scripts.js

@@ -46,6 +46,7 @@ export function buildRootScripts(workspaceGlobs) {
         'fmt:check': 'nmr-fmt --check',
         lint: 'eslint --fix .',
         'lint:check': 'eslint .',
+        'lint:shell': 'nmr-shellcheck',
         'lint:strict': 'strict-lint',
         'lint:workflows': 'nmr-actionlint',
         prepush: [{ run: 'audit', shouldDeclineArguments: true }, 'ci'],

package/docs/check-cache.md

@@ -10,7 +10,7 @@ The cache is a working-tree cache, not a build cache: It answers "has this exact
 
 ## What is cached
 
-Cacheable by default: `check`, `check:strict`, `ci`, `fix:check`, `fmt:check`, `lint:check`, `lint:strict`, `lint:workflows`, `test`, `test:coverage`, `test:tool`, `test:unit`, `typecheck`, and the `root:` variants `root:check`, `root:lint:check`, `root:lint:strict`, `root:test`, `root:test:tool`, `root:test:unit`, and `root:typecheck`.
+Cacheable by default: `check`, `check:strict`, `ci`, `fix:check`, `fmt:check`, `lint:check`, `lint:shell`, `lint:strict`, `lint:workflows`, `test`, `test:coverage`, `test:tool`, `test:unit`, `typecheck`, and the `root:` variants `root:check`, `root:lint:check`, `root:lint:strict`, `root:test`, `root:test:tool`, `root:test:unit`, and `root:typecheck`.
 
 Everything else runs every time:
 

package/docs/scripts.md

@@ -202,6 +202,10 @@ The result does not depend on what the machine has installed. nmr pins actionlin
 
 The supported platforms are macOS and Linux on x64 and arm64; on any other, the command fails and names the platform. actionlint reads its own configuration from `.github/actionlint.yaml`, through which a repo can ignore a finding.
 
+### Shell lint
+
+`lint:shell`, a root command, lints every `*.sh` file that git tracks under the monorepo root with [shellcheck](https://www.shellcheck.net/) and fails on any finding. A repo that does not track any `*.sh` file passes without downloading shellcheck, and a tracked file that is missing from the working tree is skipped. The command runs `nmr-shellcheck`, whose trailing arguments replace the file list, so `nmr lint:shell scripts/release.sh` lints that file alone. It uses the shellcheck that [Workflow lint](#workflow-lint) pins, downloads, and caches. Neither `check`, `check:strict`, nor `root:check` runs it.
+
 ### Root-only
 
 The `root:`-prefixed commands operate on root-level code only (not workspace packages).

package/docs/utilities.md

@@ -1,6 +1,6 @@
 # Standalone utilities
 
-The binaries behind nmr's default `clean`, `compile`, `fmt`, `lint:workflows`, and package `test` commands, and a check for the `prepublishOnly` hooks of publishable packages.
+The binaries behind nmr's default `clean`, `compile`, `fmt`, `lint:shell`, `lint:workflows`, and package `test` commands, and a check for the `prepublishOnly` hooks of publishable packages.
 
 ## `nmr-actionlint`
 
@@ -74,6 +74,14 @@ Pass `--no-cache`, or set `NMR_NO_CACHE=1`, to run uncached. `nmr --no-cache fmt
 nmr-fmt --check --no-cache
 ```
 
+## `nmr-shellcheck`
+
+Lint the monorepo's tracked `*.sh` files with the pinned shellcheck binary, passing when the repo does not track any. Any arguments replace the file list and reach shellcheck as given. This is the default root `lint:shell` script; [Shell lint](scripts.md#shell-lint) covers its behavior.
+
+```bash
+nmr-shellcheck
+```
+
 ## `nmr-vitest`
 
 Run Vitest from a package directory with the monorepo's shared config. Vitest 5 does not search parent directories for a config, so `nmr-vitest` names it: When the working directory does not contain a `vitest.config.*` or `vite.config.*` of its own, it passes `--config` naming the `vitest.config.*` at the monorepo root, the directory that contains `pnpm-workspace.yaml`. It does not search the directories in between. A package with a config of its own, a monorepo root without a `vitest.config.*`, and a directory outside any monorepo all run Vitest without the flag. An explicit `--config` or `-c` ahead of any `--` passes through unchanged, and so does every other argument. This is the command behind every package-scope `test*` script.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.54.1",
+  "version": "0.55.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -64,6 +64,7 @@
     "nmr-fmt": "bin/nmr-fmt.js",
     "nmr-report-catalog": "bin/nmr-report-catalog.js",
     "nmr-report-overrides": "bin/nmr-report-overrides.js",
+    "nmr-shellcheck": "bin/nmr-shellcheck.js",
     "nmr-taze": "bin/nmr-taze.js",
     "nmr-vitest": "bin/nmr-vitest.js"
   },
@@ -79,7 +80,7 @@
     "!docs/*.v*.md"
   ],
   "dependencies": {
-    "@williamthorsen/nmr-core": "0.15.0",
+    "@williamthorsen/nmr-core": "0.15.1",
     "@williamthorsen/toolbelt.errors": "0.9.0",
     "@williamthorsen/toolbelt.filesystem": "0.10.0",
     "glob": "14.0.3",
@@ -95,7 +96,7 @@
     "readyup": "0.45.0",
     "tinyglobby": "0.2.17",
     "typescript": "6.0.3",
-    "vite": "8.3.5",
+    "vite": "8.3.6",
     "vitest": "5.1.0",
     "yaml": "2.9.1"
   },