@williamthorsen/nmr 0.40.0 → 0.41.0

package/.meta/changelog.json

@@ -1,4 +1,21 @@
 [
+  {
+    "version": "0.41.0",
+    "date": "2026-10-02",
+    "sections": [
+      {
+        "title": "🎉 Features",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Adds a hint to `nmr` that, when a command fails, names any of nmr's own flags written after the command name and shows the corrected invocation, such as `nmr -q check`. (#956)",
+            "hash": "21e1759f8eb8257d81bc5bf1e533dbd496d99017",
+            "entry": 1
+          }
+        ]
+      }
+    ]
+  },
   {
     "version": "0.40.0",
     "date": "2026-10-01",

package/.readyup/kits/default.js

@@ -617,7 +617,7 @@ function formatPaths(paths) {
 ${paths.map((path2) => `      ${path2}`).join("\n")}`;
 }
 function getMinVersion() {
-  const pickedFields = { "version": "0.40.0" };
+  const pickedFields = { "version": "0.41.0" };
   if (typeof pickedFields["version"] !== "string") {
     throw new TypeError("nmr/package.json: 'version' must be a string");
   }

package/.readyup/manifest.json

@@ -16,7 +16,7 @@
           "path": "kits/default.ts"
         },
         {
-          "hash": "9c1005ba",
+          "hash": "00e9a998",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -49,7 +49,7 @@
       "readyupVersion": "0.38.0",
       "source": "kits/default.ts",
       "sourceHash": "5f7bd316",
-      "targetHash": "da11ca1f"
+      "targetHash": "69936c4f"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.41.0 — 2026-10-02
+
+### 🎉 Features
+
+- Adds a hint to `nmr` that, when a command fails, names any of nmr's own flags written after the command name and shows the corrected invocation, such as `nmr -q check`. (#956)
+
 ## 0.40.0 — 2026-10-01
 
 ### 🎉 Features

package/README.md

@@ -5,18 +5,11 @@
 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.40.0 (2026-10-01)
+## Release notes — v0.41.0 (2026-10-02)
 
 ### 🎉 Features
 
-- Makes `checkTestFileConventions` and the readyup kit's tier and placement checks skip untracked paths that git ignores, so that local build output such as a stale `.netlify/` directory no longer fails the check. (#898)
-- Excludes untracked paths that git ignores from collection in `defineVitestConfig` and `defineRootVitestConfig`, so that Vitest does not run a test file that the conventions check skips. (#898)
-- Rewords the `nmr --log` refusal for a run that the check-result cache does not cover to `the check-result cache does not apply here (NMR_DEBUG=1 reports why)`, and renames the matching `docs/check-cache.md` heading to "When the cache does not apply", which changes its anchor. (#923)
-
-### 🐛 Bug fixes
-
-- Rewords the messages printed by `nmr`, its bin wrappers, and its readyup kit, which used figures such as "sits under" and "holds", em-dashes, and "no" as a determiner, so that a diagnosis such as "-F/--filter did not match any workspace" states its condition directly. (#932)
-- Fixes the issue that the `nmr` rulebook recommended `-q` without stating that nmr reads its own flags only before the command name, which led agents to run `nmr ci -q` and fail when `nmr-fmt` rejected the flag. (#948)
+- Adds a hint to `nmr` that, when a command fails, names any of nmr's own flags written after the command name and shows the corrected invocation, such as `nmr -q check`. (#956)
 <!-- /section:release-notes -->
 
 ## Installation
@@ -66,7 +59,7 @@ nmr --recursive lint   # Lint all workspace packages
 
 `--recursive`, and a `--filter` that selects more than one package, do not give any package terminal input. An interactive command such as `test:watch` needs a filter that selects a single package.
 
-Position determines ownership: Flags before the command name are nmr's own, and everything after the command name is forwarded untouched to the resolved command.
+Position determines ownership: Flags before the command name are nmr's own, and everything after the command name is forwarded untouched to the resolved command. When a command fails and one of nmr's own flags follows its name, nmr names the flag and prints the corrected invocation.
 
 `nmr --help` lists every flag and command, with the shell command to which each command resolves. Per-package `package.json` files do not need any script entries.
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -80,7 +80,7 @@
     "@williamthorsen/nmr-core": "0.13.1",
     "@williamthorsen/toolbelt.errors": "0.8.1",
     "glob": "13.0.6",
-    "prettier-plugin-sh": "0.19.0",
+    "prettier-plugin-sh": "0.20.2",
     "taze": "21.1.0"
   },
   "devDependencies": {