@williamthorsen/nmr 0.21.0 → 0.22.0

package/README.md

@@ -3,23 +3,17 @@
 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.21.0 (2026-07-30)
+## Release notes — v0.22.0 (2026-07-31)
 
 ### 🎉 Features
 
-- Add a shared Vitest config export (#526)
+- 🚨 **Breaking:** Ship shell and Dockerfile formatting from a shared nmr Prettier config (#540)
 
-  Adds a shared Vitest configuration that can be used by repos that use `nmr`. Tests are now sorted into three named categories (unit, integration, and app), so that a run can target or skip a single category. A second variant excludes all tests in workspace packages, allowing the monorepo's own root-level tests to be run separately.
+  Adds the ability to format shell scripts and Dockerfiles to `nmr fmt`. `@williamthorsen/nmr` now provides a common config for consistency across projects. Shell fences inside Markdown are now formatted as well. These features are absorbed into `nmr fmt` and `nmr fmt:check`; the `fmt:sh` and `fmt:all` commands are removed.
 
-- 🚨 **Breaking:** Retire the Vitest config-file variants from nmr's defaults (#533)
+- 🚨 **Breaking:** Require the monorepo root in the shared root Vitest config (#541)
 
-  Packages no longer need extra Vitest config files to keep integration tests out of the default test run. Integration tests are now recognized by an `*.int.test.ts` suffix, and every package gets the same five commands: `test`, `test:all`, `test:coverage`, `test:integration`, and `test:watch`. The same five commands work from the monorepo root. A Vitest run that collects no test files now passes instead of failing. Consumers should migrate the Vitest config when upgrading.
-
-### 🐛 Bug fixes
-
-- Apply ignore rules from any working directory when formatting (#535)
-
-  Fixes an issue where `nmr fmt` and `nmr fmt:check` did not apply a pattern from a package's `.gitignore` or `.prettierignore` when the run started at the monorepo root, so files a package excluded could fail a root-level format gate while passing a package-scoped one. Untracked files that git does not ignore are now formatted alongside tracked ones, and a run started outside a git repository now fails instead of reporting a clean pass over nothing. Trailing arguments to `nmr fmt` are git pathspecs rather than Prettier flags; one that matches no formattable file now fails instead of exiting silently.
+  Modifies the testing configuration so that root-level test runs always cover the repository containing the configuration. The shared root Vitest config now requires a `monorepoRoot` option specifying an absolute path to the repository's own root, in place of the optional search origin. A repository nested inside a parent monorepo fails instead of resolving silently to its parent.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -46,17 +40,17 @@ nmr works out of the box with no configuration. It ships with built-in scripts f
 From a package directory:
 
 ```bash
-nmr test          # Run tests for the current package
-nmr build         # Compile to .js and .d.ts in one pass
-nmr check         # Typecheck, format check, lint check, and tests
+nmr test  # Run tests for the current package
+nmr build # Compile to .js and .d.ts in one pass
+nmr check # Typecheck, format check, lint check, and tests
 ```
 
 From the monorepo root:
 
 ```bash
-nmr test          # Run root tests + recursive workspace tests
-nmr build         # Build all packages
-nmr ci            # Run build && check:strict && audit (full CI pipeline)
+nmr test  # Run root tests + recursive workspace tests
+nmr build # Build all packages
+nmr ci    # Run build && check:strict && audit (full CI pipeline)
 ```
 
 nmr detects where you are and selects the right scripts automatically — see [context-aware resolution](#context-aware-resolution) below.
@@ -217,9 +211,9 @@ The second example calls the bin directly, which sidesteps the workspace-versus-
 The upgrade tool ([taze](https://github.com/antfu-collective/taze)) arrives with nmr, so your repo declares no dependency on it. Everything after the command name is passed through, including the range mode:
 
 ```bash
-nmr upgrade          # upgrades available within each package's version ceilings
-nmr upgrade major    # major upgrades, still inside the ceilings
-nmr upgrade --write  # apply the proposals to package.json
+nmr upgrade         # upgrades available within each package's version ceilings
+nmr upgrade major   # major upgrades, still inside the ceilings
+nmr upgrade --write # apply the proposals to package.json
 ```
 
 ### Configuring upgrades
@@ -348,12 +342,10 @@ The same five names the workspace registry carries, so a command means the same
 
 #### Format
 
-| Command     | Runs                    |
-| ----------- | ----------------------- |
-| `fmt`       | `nmr-fmt --write`       |
-| `fmt:all`   | `fmt`, `fmt:sh`         |
-| `fmt:check` | `nmr-fmt --check`       |
-| `fmt:sh`    | `shfmt --write **/*.sh` |
+| Command     | Runs              |
+| ----------- | ----------------- |
+| `fmt`       | `nmr-fmt --write` |
+| `fmt:check` | `nmr-fmt --check` |
 
 #### File selection
 
@@ -423,19 +415,19 @@ Position determines ownership: flags before the command name are nmr's own, and
 
 ```bash
 # From a package directory
-nmr test                    # Run workspace test script
-nmr build                   # Compile to .js and .d.ts in one pass
+nmr test  # Run workspace test script
+nmr build # Compile to .js and .d.ts in one pass
 
 # From the monorepo root
-nmr test                    # Root tests + recursive workspace tests
-nmr ci                      # build + check:strict + audit
+nmr test # Root tests + recursive workspace tests
+nmr ci   # build + check:strict + audit
 
 # Target specific packages
-nmr --filter core test      # Test only the core package
-nmr --recursive lint        # Lint all workspace packages
+nmr --filter core test # Test only the core package
+nmr --recursive lint   # Lint all workspace packages
 
 # Force root context from anywhere
-nmr --workspace-root check  # Run root check from a package dir
+nmr --workspace-root check # Run root check from a package dir
 ```
 
 ## Additional subcommands
@@ -455,8 +447,8 @@ nmr report-overrides
 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
+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.
@@ -570,12 +562,65 @@ for (const packageDir of getWorkspacePackageDirs(monorepoRoot)) {
 
 `findMonorepoRoot(startDir?)` walks up from `startDir`, defaulting to `process.cwd()`, until it reaches a directory containing `pnpm-workspace.yaml`. It throws if it runs out of parent directories without finding one.
 
-`getWorkspacePackageDirs(monorepoRoot)` reads the workspace patterns from that repo's `pnpm-workspace.yaml` and resolves them to absolute package directories, sorted and free of duplicates. Patterns carry pnpm's own semantics: `packages/*`, deeper globs such as `packages/**`, exact paths such as `tools/cli`, and `!`-prefixed exclusions such as `!packages/legacy` or `!**/test/**`, which filter every directory the positive patterns matched regardless of where they appear in the list. Nothing under `node_modules` is ever returned.
+`getWorkspacePackageDirs(monorepoRoot)` reads the workspace patterns from that repo's `pnpm-workspace.yaml` and resolves them to absolute package directories, sorted and free of duplicates. It throws if `monorepoRoot` holds no `pnpm-workspace.yaml`. Patterns carry pnpm's own semantics: `packages/*`, deeper globs such as `packages/**`, exact paths such as `tools/cli`, and `!`-prefixed exclusions such as `!packages/legacy` or `!**/test/**`, which filter every directory the positive patterns matched regardless of where they appear in the list. Nothing under `node_modules` is ever returned.
 
 One divergence from pnpm: a directory counts as a package only if it holds a `package.json`, not a `package.yaml` or `package.json5`.
 
 Quote exclusion patterns in the manifest — `- '!packages/legacy'`. An unquoted `!` opens a YAML tag rather than a string, so the entry never reaches nmr (or pnpm) as a pattern.
 
+## Shared Prettier config
+
+Every repo consuming nmr otherwise maintains its own copy of the house Prettier options, and wires up shell formatting itself. The `@williamthorsen/nmr/prettier` subpath publishes both as a factory, so a repo declares only what it customizes:
+
+```js
+// .prettierrc.js
+import { definePrettierConfig } from '@williamthorsen/nmr/prettier';
+
+export default definePrettierConfig();
+```
+
+`prettier` is a peer dependency (`>=3.9.5 <4`), declared optional — the consuming repo provides it. The shell and Dockerfile plugin is a dependency of nmr rather than a peer, so its version is pinned centrally and two repos cannot format the same script differently.
+
+### What it formats
+
+Beyond everything Prettier already handles, this config formats `.sh`, `.bash`, `.zsh`, and the other extensions and dotfile names of the Shell language, plus `Dockerfile` and `Containerfile`. `nmr fmt` therefore covers shell scripts with no extra script, glob, or workflow entry.
+
+Shell output matches `shfmt` run with no flags: `binaryNextLine`, `spaceRedirects`, and `switchCaseIndent` are pinned to shfmt's CLI defaults, which the underlying plugin inverts. A repo whose scripts shfmt already formatted sees no diff on adoption.
+
+### Language scoping
+
+`prettier-plugin-sh` routes 20 further file types to the same shell parser, among them `.gitignore`, `.env`, `.csh`, `.nu`, `.properties`, `.ics`, `.vcf`, `CODEOWNERS`, and `hosts`. Since `nmr fmt` hands git's whole file list to Prettier, registering the plugin as shipped would make every one of them formattable — and the shell parser either fails on them or silently rewrites them. A `.gitignore` pattern such as `a(b)c` fails to parse, and an unquoted `&` in a `.env` or `.properties` value is split across two lines.
+
+This config registers a narrowed plugin, so Prettier infers a parser for the Shell and Dockerfile languages alone. `.flaskenv`, `gradlew`, and `mvnw` are dropped from Shell as well: the first holds dotenv content the plugin misfiles as shell, and the other two are vendored wrappers their generators would overwrite.
+
+The parsers themselves stay registered, so a repo that wants a dropped language back assigns it explicitly:
+
+```js
+export default definePrettierConfig({
+  additionalOverrides: [{ files: ['APKBUILD', '*.ebuild'], options: { parser: 'sh' } }],
+});
+```
+
+### Customizing
+
+Any Prettier option passed to the factory spreads over the defaults:
+
+```js
+export default definePrettierConfig({
+  printWidth: 100,
+  additionalPlugins: [await import('prettier-plugin-tailwindcss')],
+  additionalOverrides: [{ files: ['*.md'], options: { proseWrap: 'always' } }],
+});
+```
+
+`additionalPlugins` and `additionalOverrides` append to what the config declares, so a later override wins over nmr's own and no seam can drop shell support. Passing `plugins` or `overrides` throws, and both are typed `never` — replacement is inexpressible rather than merely discouraged, because a silently ignored key would produce no diff to notice.
+
+### Adoption caveats
+
+- **Indentation follows `.editorconfig`**, as it did under shfmt: Prettier maps `indent_style` and `indent_size` to `useTabs` and `tabWidth`, and the plugin honours both. With no `.editorconfig`, the two disagree — shfmt indents shell with tabs, Prettier with two spaces. Add `indent_style = tab` under `[*.sh]` to keep tabs.
+- **Shell fences in Markdown are formatted**, which collapses hand-aligned comment columns in documentation. Prettier keeps the original text when an embedded snippet fails to parse, so illustrative or truncated fences are safe. Use `<!-- prettier-ignore -->` before a fence whose alignment matters.
+- **Adopting the house options reformats the repo.** `singleQuote`, `trailingComma`, and the rest apply on the first run; review that diff separately from the shell one.
+
 ## Shared Vitest config
 
 Every repo consuming nmr otherwise writes and maintains its own Vitest config. The `@williamthorsen/nmr/vitest` subpath publishes that config as a factory, so a repo declares only what it customizes:
@@ -602,9 +647,9 @@ The config declares three projects, named for what the tests cover:
 All three match only under a `__tests__` directory. Select them at run time with `--project`, which accepts negation:
 
 ```bash
-vitest --project '!integration'   # everything except integration tests
-vitest --project integration      # integration tests alone
-vitest                            # every project
+vitest --project '!integration' # everything except integration tests
+vitest --project integration    # integration tests alone
+vitest                          # every project
 ```
 
 `unit` is defined by subtracting the other categories rather than by an allow-list of suffixes, so a file such as `parser.smoke.test.ts` runs under `unit` instead of being silently dropped.
@@ -634,22 +679,18 @@ A monorepo's own root-level tests need a second config, because the package conf
 // vitest.root.config.ts
 import { defineRootVitestConfig } from '@williamthorsen/nmr/vitest';
 
-export default defineRootVitestConfig();
+export default defineRootVitestConfig({ monorepoRoot: import.meta.dirname });
 ```
 
 This variant reads `pnpm-workspace.yaml` and excludes every workspace package from all three projects, so a root run covers only root-level files. It reports no coverage of its own — packages cover their own sources.
 
-The monorepo root is located by walking up from the working directory, and every project is pinned to it, so the exclusions hold wherever the run is invoked from. Pass `startDir` to locate it from somewhere else:
-
-```ts
-export default defineRootVitestConfig({ startDir: import.meta.dirname });
-```
+`monorepoRoot` is required, and because the config sits at the monorepo root, it is always `import.meta.dirname`. Stating the root rather than searching for it is what makes the exclusions describe this repo: a search from the working directory would resolve whichever monorepo the run started in, and every project is then pinned to that one. A directory holding no `pnpm-workspace.yaml` throws, naming the directory.
 
 ### Migrating from the config-file variants
 
 nmr once selected a package's test scripts by looking for a `vitest.integration.config.ts` on disk, which meant three config files per package that separated its integration tests. Those files are no longer consulted. **Migrate the config and the scripts together**: one without the other leaves the repo in one of the two states below.
 
-1. Replace the repo's root `vitest.config.ts` with `defineVitestConfig()`, and its root-scoped config with `defineRootVitestConfig()`.
+1. Replace the repo's root `vitest.config.ts` with `defineVitestConfig()`, and its root-scoped config with `defineRootVitestConfig({ monorepoRoot: import.meta.dirname })`.
 2. Delete every `vitest.integration.config.ts` and `vitest.standalone.config.ts`, plus any per-package `vitest.config.ts` that only re-exports an ancestor. Vitest resolves config by walking up from the run root, so those are redundant.
 3. Rename integration tests to `*.int.test.ts` and tooling or drift tests to `*.app.test.ts`.
 4. Drop any hand-copied `test*` entries from `package.json`, which now shadow the defaults.

package/dist/esm/default-scripts.js

@@ -33,9 +33,7 @@ export const rootScripts = {
     fix: ['lint', 'fmt'],
     'fix:check': ['fmt:check', 'lint:check'],
     fmt: 'nmr-fmt --write',
-    'fmt:all': ['fmt', 'fmt:sh'],
     'fmt:check': 'nmr-fmt --check',
-    'fmt:sh': 'shfmt --write **/*.sh',
     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',

package/dist/esm/prettier.d.ts

@@ -0,0 +1,8 @@
+import type { Config } from 'prettier';
+export interface PrettierConfigOptions extends Omit<Config, 'overrides' | 'plugins'> {
+    additionalPlugins?: NonNullable<Config['plugins']>;
+    additionalOverrides?: NonNullable<Config['overrides']>;
+    overrides?: never;
+    plugins?: never;
+}
+export declare function definePrettierConfig(options?: PrettierConfigOptions): Config;

package/dist/esm/prettier.js

@@ -0,0 +1,60 @@
+import * as shPlugin from 'prettier-plugin-sh';
+const INFERRED_LANGUAGES = new Set(['Dockerfile', 'Shell']);
+const EXCLUDED_FILENAMES = new Set([
+    '.bash_history',
+    '.cshrc',
+    '.flaskenv',
+    '.login',
+    'cshrc',
+    'gradlew',
+    'login',
+    'mvnw',
+]);
+const DEFAULT_OPTIONS = {
+    binaryNextLine: false,
+    checkIgnorePragma: true,
+    jsxSingleQuote: false,
+    singleQuote: true,
+    spaceRedirects: false,
+    switchCaseIndent: false,
+    trailingComma: 'all',
+};
+const DEFAULT_OVERRIDES = [
+    {
+        files: ['*.json5', '*.jsonc', 'tsconfig.json', 'tsconfig.*.json'],
+        options: { parser: 'jsonc', singleQuote: false, trailingComma: 'all' },
+    },
+];
+export function definePrettierConfig(options = {}) {
+    assertNoReplacement(options);
+    const { additionalOverrides = [], additionalPlugins = [], ...overrideOptions } = options;
+    return {
+        ...DEFAULT_OPTIONS,
+        ...overrideOptions,
+        overrides: [...DEFAULT_OVERRIDES, ...additionalOverrides],
+        plugins: [buildShellPlugin(), ...additionalPlugins],
+    };
+}
+function buildShellPlugin() {
+    return {
+        ...shPlugin,
+        languages: shPlugin.languages.filter(isInferredLanguage).map(withoutExcludedFilenames),
+    };
+}
+function isInferredLanguage(language) {
+    return INFERRED_LANGUAGES.has(language.name);
+}
+function withoutExcludedFilenames(language) {
+    if (language.filenames === undefined)
+        return language;
+    return { ...language, filenames: language.filenames.filter((name) => !EXCLUDED_FILENAMES.has(name)) };
+}
+function assertNoReplacement(options) {
+    if ('overrides' in options)
+        throw ownedKeyError('overrides', 'additionalOverrides');
+    if ('plugins' in options)
+        throw ownedKeyError('plugins', 'additionalPlugins');
+}
+function ownedKeyError(key, seam) {
+    return new TypeError(`definePrettierConfig: \`${key}\` is owned by this config. Use \`${seam}\` to append to it.`);
+}

package/dist/esm/vitest.d.ts

@@ -9,7 +9,7 @@ export interface VitestConfigOptions {
     project?: ProjectConfig;
 }
 export interface RootVitestConfigOptions extends VitestConfigOptions {
-    startDir?: string;
+    monorepoRoot: string;
 }
 export declare function defineVitestConfig(options?: VitestConfigOptions): ViteUserConfig;
-export declare function defineRootVitestConfig(options?: RootVitestConfigOptions): ViteUserConfig;
+export declare function defineRootVitestConfig(options: RootVitestConfigOptions | undefined): ViteUserConfig;

package/dist/esm/vitest.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { defaultExclude, mergeConfig } from 'vitest/config';
-import { findMonorepoRoot, getWorkspacePackageDirs } from "./workspace.js";
+import { getWorkspacePackageDirs } from "./workspace.js";
 const APP_PATTERNS = ['**/__tests__/**/*.app.test.{ts,tsx}'];
 const INTEGRATION_PATTERNS = ['**/__tests__/**/*.int.test.{ts,tsx}'];
 const ALL_TEST_PATTERNS = ['**/__tests__/**/*.test.{ts,tsx}'];
@@ -12,11 +12,18 @@ const COVERAGE_EXCLUDE = [
     '**/*.types.ts',
 ];
 const PACKAGE_COVERAGE_INCLUDE = ['**/src/**/*.{ts,tsx}'];
+const MISSING_MONOREPO_ROOT = 'defineRootVitestConfig requires `monorepoRoot`, an absolute path to the directory holding pnpm-workspace.yaml. Pass `import.meta.dirname` from the root config.';
 export function defineVitestConfig(options = {}) {
     return buildConfig(options, { coverageInclude: PACKAGE_COVERAGE_INCLUDE });
 }
-export function defineRootVitestConfig(options = {}) {
-    const monorepoRoot = findMonorepoRoot(options.startDir);
+export function defineRootVitestConfig(options) {
+    if (options === undefined) {
+        throw new TypeError(MISSING_MONOREPO_ROOT);
+    }
+    const monorepoRoot = options.monorepoRoot;
+    if (typeof monorepoRoot !== 'string' || !path.isAbsolute(monorepoRoot)) {
+        throw new TypeError(MISSING_MONOREPO_ROOT);
+    }
     return buildConfig(options, {
         coverageInclude: [],
         projectExclude: getWorkspaceExcludePatterns(monorepoRoot),

package/dist/esm/workspace.js

@@ -3,21 +3,25 @@ import path from 'node:path';
 import { parse } from 'yaml';
 import { isObject } from "./helpers/type-guards.js";
 import { resolvePackageDirs } from "./helpers/workspace-patterns.js";
+const WORKSPACE_MANIFEST = 'pnpm-workspace.yaml';
 export function findMonorepoRoot(startDir) {
     let dir = path.resolve(startDir ?? process.cwd());
     for (;;) {
-        if (existsSync(path.join(dir, 'pnpm-workspace.yaml'))) {
+        if (existsSync(path.join(dir, WORKSPACE_MANIFEST))) {
             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');
+            throw new Error(`Could not find monorepo root: no ${WORKSPACE_MANIFEST} found in any parent directory`);
         }
         dir = parent;
     }
 }
 export function getWorkspacePackageDirs(monorepoRoot) {
-    const workspaceFile = path.join(monorepoRoot, 'pnpm-workspace.yaml');
+    const workspaceFile = path.join(monorepoRoot, WORKSPACE_MANIFEST);
+    if (!existsSync(workspaceFile)) {
+        throw new Error(`Not a monorepo root: no ${WORKSPACE_MANIFEST} in ${monorepoRoot}`);
+    }
     const content = readFileSync(workspaceFile, 'utf8');
     const parsed = parse(content);
     const packages = getPackagesFromParsedYaml(parsed);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -26,6 +26,10 @@
       "types": "./dist/esm/index.d.ts",
       "default": "./dist/esm/index.js"
     },
+    "./prettier": {
+      "types": "./dist/esm/prettier.d.ts",
+      "default": "./dist/esm/prettier.js"
+    },
     "./scripts": {
       "types": "./dist/esm/scripts.d.ts",
       "default": "./dist/esm/scripts.js"
@@ -61,6 +65,7 @@
   "dependencies": {
     "glob": "13.0.6",
     "jiti": "2.7.0",
+    "prettier-plugin-sh": "0.19.0",
     "taze": "19.16.0",
     "yaml": "2.9.0",
     "@williamthorsen/nmr-core": "0.7.3"