@williamthorsen/nmr 0.40.0 → 0.42.0

package/dist/esm/help.js

@@ -1,6 +1,28 @@
 import { isHookName } from "./helpers/hook-name.js";
 import { OUTPUT_STYLE_ENV_VAR, OUTPUT_STYLE_FLAG } from "./output-style.js";
 import { buildRootRegistry, buildWorkspaceRegistry, describeScript, isSelfReferential, readPackageJsonScripts, } from "./resolver.js";
+const LIFECYCLE_SCRIPT_NAMES = new Set([
+    'dependencies',
+    'install',
+    'pnpm:devPreinstall',
+    'postinstall',
+    'postpack',
+    'postprepare',
+    'postpublish',
+    'postuninstall',
+    'postversion',
+    'preinstall',
+    'prepack',
+    'prepare',
+    'preprepare',
+    'prepublish',
+    'prepublishOnly',
+    'preuninstall',
+    'preversion',
+    'publish',
+    'uninstall',
+    'version',
+]);
 export function generateHelp(config, packageDir, shouldUseRoot) {
     const lines = [
         'Usage: nmr [flags] <command> [args...]',
@@ -23,7 +45,8 @@ export function generateHelp(config, packageDir, shouldUseRoot) {
         '',
         'Workspace commands:',
     ];
-    const overrides = packageDir === undefined ? {} : collectOverrides(packageDir);
+    const packageScripts = packageDir === undefined ? {} : readRunnableScripts(packageDir);
+    const overrides = collectOverrides(packageScripts);
     let hadOverride = false;
     const workspaceRegistry = filterHooks(buildWorkspaceRegistry(config));
     const workspaceMarkedNames = !shouldUseRoot ? applyOverrides(workspaceRegistry, overrides) : new Set();
@@ -36,24 +59,44 @@ export function generateHelp(config, packageDir, shouldUseRoot) {
     if (rootMarkedNames.size > 0)
         hadOverride = true;
     formatRegistry(rootRegistry, rootMarkedNames, lines);
+    const activeRegistry = shouldUseRoot ? buildRootRegistry(config) : buildWorkspaceRegistry(config);
+    const unregisteredScripts = collectUnregisteredScripts(packageScripts, activeRegistry);
+    if (Object.keys(unregisteredScripts).length > 0) {
+        lines.push('', 'Package scripts:');
+        formatRegistry(unregisteredScripts, new Set(), lines);
+    }
     if (hadOverride) {
         lines.push('', '* Overridden by package.json');
     }
     return lines.join('\n');
 }
-function collectOverrides(packageDir) {
+function collectOverrides(packageScripts) {
+    const candidateOverrides = {};
+    for (const [name, value] of Object.entries(packageScripts)) {
+        if (!isHookName(name))
+            candidateOverrides[name] = value;
+    }
+    return candidateOverrides;
+}
+function collectUnregisteredScripts(packageScripts, registry) {
+    const unregisteredScripts = {};
+    for (const [name, value] of Object.entries(packageScripts)) {
+        if (Object.hasOwn(registry, name) || LIFECYCLE_SCRIPT_NAMES.has(name))
+            continue;
+        unregisteredScripts[name] = value;
+    }
+    return unregisteredScripts;
+}
+function readRunnableScripts(packageDir) {
     const scripts = readPackageJsonScripts(packageDir);
     if (!scripts)
         return {};
-    const candidateOverrides = {};
+    const runnableScripts = {};
     for (const [name, value] of Object.entries(scripts)) {
-        if (isHookName(name))
-            continue;
-        if (isSelfReferential(value, name, packageDir))
-            continue;
-        candidateOverrides[name] = value;
+        if (!isSelfReferential(value, name, packageDir))
+            runnableScripts[name] = value;
     }
-    return candidateOverrides;
+    return runnableScripts;
 }
 function applyOverrides(registry, overrides) {
     const markedNames = new Set();

package/dist/esm/prettier-default-config.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The house config that `nmr-fmt` passes to Prettier by path when the repository does not have a config of its own.
+ * It is a default export because that is the export that Prettier reads from a config file.
+ */
+declare const _default: import("prettier").Config;
+export default _default;

package/dist/esm/prettier-default-config.js

@@ -0,0 +1,2 @@
+import { definePrettierConfig } from "./prettier.js";
+export default definePrettierConfig();

package/dist/esm/runCli.js

@@ -16,9 +16,9 @@ import { isTerminalStream, OUTPUT_STYLE_ENV_VAR, OUTPUT_STYLE_FLAG, resolveOutpu
 import { renderRecording, renderRefusal, resolveRecording } from "./recording.js";
 import { assembleReplay } from "./replay-assembly.js";
 import { readReportFormatEnv, REPORT_FORMAT_ENV_VAR, resolveReportFormat } from "./report-format.js";
-import { applyDevBinToSteps, buildRootRegistry, buildWorkspaceRegistry, expandScript, findChainedSelfReference, resolveScript, } from "./resolver.js";
+import { applyDevBinToSteps, buildRootRegistry, buildWorkspaceRegistry, expandScript, findChainedSelfReference, readPackageJsonScripts, resolveScript, } from "./resolver.js";
 import { resolveChannel, runSteps } from "./runner.js";
-import { composeNmrStep, dropRecursiveSteps, findNmrCrossing, renderChain } from "./steps.js";
+import { composeNmrStep, dropRecursiveSteps, findNmrCrossing, quoteToken, renderChain } from "./steps.js";
 import { UserError } from "./UserError.js";
 import { COMMAND_VERBOSITY_ENV_VAR, readVerbosityEnv, resolveVerbosity, } from "./verbosity.js";
 import { writeVerdict } from "./verdict.js";
@@ -34,7 +34,7 @@ const NAMED_ESCAPES = new Map([
 ]);
 export const RUN_IF_PRESENT_ENV_VAR = 'NMR_RUN_IF_PRESENT';
 export async function runCli(options) {
-    const { args, cwd, env, stdout, stderr } = options;
+    const { args, env, stdout, stderr } = options;
     const parseResult = parseArgs(args);
     if (!parseResult.ok) {
         reportError(parseResult.error, stderr);
@@ -52,6 +52,18 @@ export async function runCli(options) {
         return { exitCode: 1 };
     }
     const { styles } = presentationRead;
+    const { exitCode, isUnknownCommand = false } = await runInvocation({ ...options, parsedArgs, presentationRead });
+    if (exitCode !== 0 && !isUnknownCommand && isTopLevelInvocation(env)) {
+        const hint = formatMisplacedFlagHint(args, parsedArgs.passthrough, styles.stderr);
+        if (hint !== undefined) {
+            stderr.write(`${hint}\n`);
+        }
+    }
+    return { exitCode };
+}
+async function runInvocation(options) {
+    const { cwd, env, parsedArgs, presentationRead, stderr, stdout } = options;
+    const { styles } = presentationRead;
     if (parsedArgs.shouldShowVersion) {
         stdout.write(`${VERSION}\n`);
         return { exitCode: 0 };
@@ -103,7 +115,8 @@ export async function runCli(options) {
     };
     const delegation = composeDelegation({ childEnv, command, parsedArgs });
     if (delegation !== undefined) {
-        return runDelegation({ context, delegation, parsedArgs, runOptions, stderr });
+        const result = await runDelegation({ context, delegation, parsedArgs, runOptions, stderr });
+        return { ...result, isUnknownCommand: result.exitCode !== 0 && !isDefinedInAnyScope(command, context) };
     }
     const registry = shouldUseRoot ? buildRootRegistry(context.config) : buildWorkspaceRegistry(context.config);
     assertNoSelfReference({
@@ -120,7 +133,7 @@ export async function runCli(options) {
             return { exitCode: 0 };
         }
         reportError(`Unknown command: ${command}`, stderr);
-        return { exitCode: 1 };
+        return { exitCode: 1, isUnknownCommand: true };
     }
     const { isEmptiedByWorkspace, steps: runnableSteps } = readRunnableSteps(resolvedScript, context.workspacePackageDirs);
     const resolvedCommand = renderChain(runnableSteps);
@@ -200,6 +213,7 @@ export async function runCli(options) {
     reportVerdict({ command, scope, ...outcome }, stdout, format, styles.stdout);
     return { exitCode };
 }
+const FILTER_FLAGS = new Set(['-F', '--filter']);
 const BOOLEAN_FLAGS = new Map([
     ['-?', 'shouldShowHelp'],
     ['--help', 'shouldShowHelp'],
@@ -587,7 +601,7 @@ function parseArgs(args) {
         const arg = args[index];
         if (arg === undefined)
             break;
-        if (arg === '-F' || arg === '--filter') {
+        if (FILTER_FLAGS.has(arg)) {
             index++;
             const filterValue = args[index];
             if (!filterValue) {
@@ -862,6 +876,69 @@ async function runGated(options) {
         outcome: exitCode === 0 ? { outcome: 'passed', durationMs } : { outcome: 'failed', durationMs, exitCode },
     };
 }
+function formatMisplacedFlagHint(args, passthrough, style) {
+    const { flagNames, movedTokens, remainingTokens } = splitMisplacedFlags(passthrough);
+    if (flagNames.length === 0) {
+        return undefined;
+    }
+    const commandIndex = args.length - passthrough.length - 1;
+    const correctedTokens = [
+        'nmr',
+        ...args.slice(0, commandIndex),
+        ...movedTokens,
+        ...args.slice(commandIndex, commandIndex + 1),
+        ...remainingTokens,
+    ];
+    const subject = flagNames.length === 1 ? 'is an nmr flag' : 'are nmr flags';
+    return (`${STATUS_GLYPHS[style].warning.text} ${renderQuotedList(flagNames)} ${subject}; ` +
+        `nmr reads its flags only before the command: \`${correctedTokens.map(quoteToken).join(' ')}\``);
+}
+function isDefinedInAnyScope(command, context) {
+    const registries = [buildRootRegistry(context.config), buildWorkspaceRegistry(context.config)];
+    if (registries.some((registry) => Object.hasOwn(registry, command))) {
+        return true;
+    }
+    return [context.monorepoRoot, ...context.workspacePackageDirs].some((dir) => Object.hasOwn(readPackageJsonScripts(dir) ?? {}, command));
+}
+function isTopLevelInvocation(env) {
+    const runId = env[RUN_ID_ENV_VAR];
+    return runId === undefined || runId === '';
+}
+function readMisplacedFlagLength(args, index) {
+    const arg = args[index] ?? '';
+    if (FILTER_FLAGS.has(arg)) {
+        return (args[index + 1] ?? '') === '' ? undefined : 2;
+    }
+    const booleanFlag = BOOLEAN_FLAGS.get(arg);
+    if (booleanFlag !== undefined) {
+        return booleanFlag === 'shouldShowHelp' || booleanFlag === 'shouldShowVersion' ? undefined : 1;
+    }
+    const styleArgument = readOutputStyleArgument(args, index);
+    return styleArgument?.ok === true ? styleArgument.consumedCount : undefined;
+}
+function splitMisplacedFlags(passthrough) {
+    const flagNames = new Set();
+    const movedTokens = [];
+    const remainingTokens = [];
+    let index = 0;
+    while (index < passthrough.length) {
+        const arg = passthrough[index] ?? '';
+        if (arg === '--') {
+            remainingTokens.push(...passthrough.slice(index));
+            break;
+        }
+        const flagLength = readMisplacedFlagLength(passthrough, index);
+        if (flagLength === undefined) {
+            remainingTokens.push(arg);
+            index++;
+            continue;
+        }
+        flagNames.add(arg.startsWith(`${OUTPUT_STYLE_FLAG}=`) ? OUTPUT_STYLE_FLAG : arg);
+        movedTokens.push(...passthrough.slice(index, index + flagLength));
+        index += flagLength;
+    }
+    return { flagNames: [...flagNames], movedTokens, remainingTokens };
+}
 function quoteForShell(arg) {
     return "'" + arg.replace(/'/g, String.raw `'\''`) + "'";
 }

package/dist/esm/steps.d.ts

@@ -75,6 +75,8 @@ export declare function findNmrCrossing(steps: readonly Step[]): string | undefi
  * literally would be quoted whole by the rendering, turning the element into a command that nobody wrote.
  */
 export declare function findUnexpressibleToken(element: string): string | undefined;
+/** Quotes a token that the shell would not read literally, and leaves every other token bare. */
+export declare function quoteToken(token: string): string;
 /**
  * Returns the command that a structural step's nmr process runs, whether the step hands that command to other
  * scopes rather than running it in its own scope, and whether it anchors the command at the monorepo root.

package/dist/esm/steps.js

@@ -33,6 +33,12 @@ export function findNmrCrossing(steps) {
 export function findUnexpressibleToken(element) {
     return tokenize(element).find((token) => !SHELL_SAFE_TOKEN.test(token));
 }
+export function quoteToken(token) {
+    if (SHELL_SAFE_TOKEN.test(token)) {
+        return token;
+    }
+    return "'" + token.replaceAll("'", String.raw `'\''`) + "'";
+}
 export function readNmrStep(step) {
     if (step.kind !== 'structural') {
         return undefined;
@@ -66,12 +72,6 @@ function isRedirectionOperator(char, precedingText, nextChar) {
     }
     return (char === '&' && nextChar === '>') || /[<>]\s*$/.test(precedingText);
 }
-function quoteToken(token) {
-    if (SHELL_SAFE_TOKEN.test(token)) {
-        return token;
-    }
-    return "'" + token.replaceAll("'", String.raw `'\''`) + "'";
-}
 function readNmrTail(segment) {
     const [head, ...rest] = dropLeadingAssignments(tokenizeSegment(segment));
     if (head === undefined) {

package/dist/esm/vitest-source-resolution.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { isBuiltin } from 'node:module';
 import path from 'node:path';
+import { findDirectoryChainMatch } from '@williamthorsen/toolbelt.filesystem';
 import { parsePackageJson } from "./helpers/package-json.js";
 import { isObject } from "./helpers/type-guards.js";
 import { UserError } from "./UserError.js";
@@ -57,17 +58,10 @@ function findPackageDir(name, fromDir, cache) {
     if (cache?.has(key))
         return cache.get(key);
     let foundDir = findSelfReferenceDir(name, fromDir);
-    let dir = fromDir;
-    while (foundDir === undefined) {
-        const candidate = path.join(dir, NODE_MODULES, name);
-        if (existsSync(path.join(candidate, 'package.json'))) {
-            foundDir = realpathSync(candidate);
-            break;
-        }
-        const parent = path.dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
+    if (foundDir === undefined) {
+        const match = findDirectoryChainMatch(fromDir, [path.join(NODE_MODULES, name, 'package.json')]);
+        if (match !== undefined)
+            foundDir = realpathSync(path.join(match.dir, NODE_MODULES, name));
     }
     cache?.set(key, foundDir);
     return foundDir;

package/docs/prettier.md

@@ -2,7 +2,7 @@
 
 The Prettier config that `@williamthorsen/nmr/prettier` publishes: what it formats, how it scopes the shell plugin, and how to customize and adopt it.
 
-`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.
+`prettier` is a dependency of nmr. When the repo installs its own copy, `nmr-fmt` runs that copy instead, so that the editor and the formatter agree. When Prettier does not find a config searching from the working directory, `nmr-fmt` passes this config with `--config`, which also applies it to files below that directory; `.editorconfig` still applies alongside 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
 

package/docs/scripts.md

@@ -141,7 +141,7 @@ For example, if a workspace script resolves to `my-cli --verbose`, nmr rewrites
 
 ## Default commands
 
-`nmr --help` lists every default command and the shell command to which it resolves. Repo-wide config (tier 2) and per-package overrides (tier 3) can add to or replace any of them. What the listing does not show is below.
+`nmr --help` lists every default command and the shell command to which it resolves. Repo-wide config (tier 2) and per-package overrides (tier 3) can add to or replace any of them. Under `Package scripts:`, the listing also shows each script in the current scope's `package.json` whose name the registry does not contain, a hook such as `build:pre` included; it omits npm and pnpm lifecycle scripts, such as `prepare` and `postinstall`, which the package manager runs. What the listing does not show is below.
 
 ### Build and CI
 

package/docs/utilities.md

@@ -22,7 +22,7 @@ Compile a single package's `src` tree to `dist/esm` with the TypeScript compiler
 
 **What busts the cache.** The key folds each input's content and path, the emit options, the resolved TypeScript version, and a fingerprint of the nmr running the build -- its own build digest in a workspace checkout, its package version otherwise. Upgrading nmr in a consuming repo therefore rebuilds every package that nmr compiles, and an edit to nmr's own build sources rebuilds each sibling once nmr itself has been rebuilt. A build of nmr's own package folds the version rather than the digest, which is the cache entry that this build is about to write.
 
-`typescript` is a peer dependency (`>=5.7.0 <7`); the consuming repo provides it. The floor is what `rewriteRelativeImportExtensions` requires; the ceiling exists because TypeScript 7 does not include a compiler API: Its root export is a version constant, so `nmr-compile` cannot run on it. Relative imports in source must use explicit `.ts` extensions for them to be rewritten.
+`typescript` is an optional peer dependency (`>=5.7.0 <7`), needed only by `nmr-compile`; the consuming repo provides it, and `nmr-compile` run without it fails with an error naming the peer and the version that it requires. The floor is what `rewriteRelativeImportExtensions` requires; the ceiling exists because TypeScript 7 does not include a compiler API: Its root export is a version constant, so `nmr-compile` cannot run on it. Relative imports in source must use explicit `.ts` extensions for them to be rewritten.
 
 ```bash
 nmr-compile
@@ -32,9 +32,9 @@ nmr-compile
 
 Format, or check the formatting of, the files that git reports for the working directory. Exactly one of `--check` and `--write` is required; a bare invocation prints usage and exits non-zero rather than defaulting to a mutation. `--write` also lists the files that it rewrote. This is what `fmt` and `fmt:check` resolve to, in both registries.
 
-`prettier` is an optional peer dependency (`>=3.9.5 <4`); the consuming repo provides it, and it is resolved through the module graph rather than from `PATH`, so the copy that runs is the one that the repo declares and not whichever `prettier` happens to come first. A repository's formatter has to be the one that its editor and pre-commit hook also run, which is why nmr takes it from the consumer instead of bundling a copy. It is optional because a repo can use nmr purely as a script runner; one that formats without a resolvable Prettier gets a message naming the package and the range.
+`prettier` is a dependency of nmr, but a repo's own copy takes precedence: `nmr-fmt` resolves Prettier from the working directory first and from nmr's installation second. A repository's formatter has to be the one that its editor and pre-commit hook also run, and resolution goes through the module graph rather than `PATH`, so the copy that runs is the one that the repo declares and not whichever `prettier` happens to come first. A repo that does not install Prettier, or nmr, formats with nmr's copy; when it does not have a Prettier config either, the [house config](prettier.md) applies.
 
-The floor is a currency policy, not a capability boundary. The design requires `--ignore-path` to honour every flag rather than only the last, so that a repository-root ignore file passed alongside a package-level one is not silently dropped. Prettier has done that since 3.0.0, while 2.x honoured only the final flag. The floor is at the current release because every consuming repo tracks it; lowering it to `>=3.0.0` would not affect correctness.
+A repo's own copy must be Prettier 3.0.0 or later. The design requires `--ignore-path` to honour every flag rather than only the last, so that a repository-root ignore file passed alongside a package-level one is not silently dropped, and 2.x honoured only the final flag.
 
 ```bash
 nmr-fmt --check
@@ -47,7 +47,7 @@ nmr-fmt --write packages/nmr
 
 A file that git ignores is never formatted, even when named directly. Because trailing arguments are git pathspecs rather than Prettier flags, `nmr fmt:check packages/nmr` narrows the run, while an unrecognized option and a pathspec that does not match any formattable file both fail it. Running outside a git repository fails rather than reporting a clean run.
 
-`nmr-fmt` drops paths that the index names but the filesystem does not have (a file deleted but not yet staged), and submodule gitlinks, before calling Prettier.
+`nmr-fmt` drops paths that the index names but the filesystem does not have (a file deleted but not yet staged), submodule gitlinks, and symlinks whatever they point at, before calling Prettier, which rejects a symlink named explicitly. It also skips a path that it is denied access to, such as a `.envrc` that a sandbox shields, and names each one on stderr, so that a check that passes does not hide a file that it never read. Any other failure to stat a listed path fails the run, with an error that names the path.
 
 ## `ensure-prepublish-hooks`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.40.0",
+  "version": "0.42.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -77,32 +77,32 @@
     "!docs/*.v*.md"
   ],
   "dependencies": {
-    "@williamthorsen/nmr-core": "0.13.1",
-    "@williamthorsen/toolbelt.errors": "0.8.1",
+    "@williamthorsen/nmr-core": "0.13.2",
+    "@williamthorsen/toolbelt.errors": "0.8.2",
+    "@williamthorsen/toolbelt.filesystem": "0.9.2",
     "glob": "13.0.6",
-    "prettier-plugin-sh": "0.19.0",
-    "taze": "21.1.0"
+    "prettier": "3.9.9",
+    "prettier-plugin-sh": "0.20.2",
+    "taze": "21.3.0"
   },
   "devDependencies": {
-    "@williamthorsen/toolbelt.filesystem": "0.9.1",
-    "@williamthorsen/toolbelt.testing": "0.6.1",
-    "@williamthorsen/toolbelt.vitest": "0.10.1",
+    "@williamthorsen/toolbelt.testing": "0.6.2",
+    "@williamthorsen/toolbelt.vitest": "0.10.2",
     "esbuild": "0.28.2",
-    "prettier": "3.9.9",
-    "readyup": "0.38.0",
+    "readyup": "0.40.0",
     "tinyglobby": "0.2.17",
     "typescript": "6.0.3",
     "vite": "8.3.1",
-    "vitest": "4.1.11"
+    "vitest": "4.1.11",
+    "yaml": "2.9.1"
   },
   "peerDependencies": {
-    "prettier": ">=3.9.5 <4",
     "typescript": ">=5.7.0 <7",
     "vite": ">=8.0.0 <9",
     "vitest": ">=4.0.0 <5"
   },
   "peerDependenciesMeta": {
-    "prettier": {
+    "typescript": {
       "optional": true
     },
     "vite": {