@williamthorsen/nmr 0.30.0 → 0.31.0

package/dist/esm/steps.d.ts

@@ -4,8 +4,15 @@ export type Step = {
 } | {
     kind: 'structural';
     argv: readonly [string, ...(readonly string[])];
+    declinesArgs?: boolean;
 };
-export declare function composeNmrStep(element: string, workspaceRoot: boolean): Step;
-export declare function findShelledNmrStep(steps: readonly Step[]): string | undefined;
+export interface NmrStepTarget {
+    command: string;
+    isDelegate: boolean;
+    isWorkspaceRoot: boolean;
+}
+export declare function composeNmrStep(element: string, workspaceRoot: boolean, declinesArgs?: boolean): Step;
+export declare function findNmrCrossing(steps: readonly Step[]): string | undefined;
 export declare function findUnexpressibleToken(element: string): string | undefined;
+export declare function readNmrStep(step: Step): NmrStepTarget | undefined;
 export declare function renderChain(steps: readonly Step[]): string;

package/dist/esm/steps.js

@@ -1,11 +1,22 @@
+const ENV_ASSIGNMENT = /^\w+=/;
+const LAUNCHERS = new Map([
+    ['bun', new Set(['x'])],
+    ['bunx', new Set()],
+    ['npm', new Set(['exec'])],
+    ['npx', new Set()],
+    ['pnpm', new Set(['dlx', 'exec'])],
+    ['yarn', new Set(['dlx', 'exec'])],
+]);
+const QUOTES = new Set(['"', "'"]);
+const SEGMENT_SEPARATORS = new Set([';', '|', '&']);
 const SHELL_SAFE_TOKEN = /^[\w@%+=:,./-]+$/;
-export function composeNmrStep(element, workspaceRoot) {
+export function composeNmrStep(element, workspaceRoot, declinesArgs = false) {
     const flags = workspaceRoot ? ['-w'] : [];
-    return { kind: 'structural', argv: ['nmr', ...flags, ...tokenize(element)] };
+    return { kind: 'structural', argv: ['nmr', ...flags, ...tokenize(element)], ...(declinesArgs && { declinesArgs }) };
 }
-export function findShelledNmrStep(steps) {
+export function findNmrCrossing(steps) {
     for (const step of steps) {
-        if (step.kind === 'opaque' && tokenize(step.command)[0] === 'nmr') {
+        if (step.kind === 'opaque' && splitSegments(step.command).some(reachesNmr)) {
             return step.command;
         }
     }
@@ -14,18 +25,120 @@ export function findShelledNmrStep(steps) {
 export function findUnexpressibleToken(element) {
     return tokenize(element).find((token) => !SHELL_SAFE_TOKEN.test(token));
 }
+export function readNmrStep(step) {
+    if (step.kind !== 'structural') {
+        return undefined;
+    }
+    const [file, ...rest] = step.argv;
+    if (file !== 'nmr') {
+        return undefined;
+    }
+    let isDelegate = false;
+    let isWorkspaceRoot = false;
+    let index = 0;
+    while (index < rest.length) {
+        const token = rest[index] ?? '';
+        switch (token) {
+            case '-F':
+            case '--filter':
+                isDelegate = true;
+                index += 2;
+                break;
+            case '-R':
+            case '--recursive':
+                isDelegate = true;
+                index += 1;
+                break;
+            case '-w':
+            case '--workspace-root':
+                isWorkspaceRoot = true;
+                index += 1;
+                break;
+            default:
+                if (!token.startsWith('-')) {
+                    return { command: token, isDelegate, isWorkspaceRoot };
+                }
+                index += 1;
+        }
+    }
+    return undefined;
+}
 export function renderChain(steps) {
     return steps.map(renderStep).join(' && ');
 }
+function dropLeadingAssignments(tokens) {
+    const start = tokens.findIndex((token) => !ENV_ASSIGNMENT.test(token));
+    return start === -1 ? [] : tokens.slice(start);
+}
 function quoteToken(token) {
     if (SHELL_SAFE_TOKEN.test(token)) {
         return token;
     }
     return "'" + token.replaceAll("'", String.raw `'\''`) + "'";
 }
+function reachesNmr(segment) {
+    const [head, ...rest] = dropLeadingAssignments(tokenize(segment));
+    if (head === undefined) {
+        return false;
+    }
+    if (head === 'nmr') {
+        return true;
+    }
+    const subcommands = LAUNCHERS.get(head);
+    if (subcommands === undefined) {
+        return false;
+    }
+    if (subcommands.size === 0) {
+        return rest.find((token) => !token.startsWith('-')) === 'nmr';
+    }
+    const subcommandIndex = rest.findIndex((token) => subcommands.has(token));
+    return subcommandIndex !== -1 && rest[subcommandIndex + 1] === 'nmr';
+}
 function renderStep(step) {
     return step.kind === 'opaque' ? step.command : step.argv.map(quoteToken).join(' ');
 }
+function splitSegments(command) {
+    const segments = [];
+    let current = '';
+    let quote;
+    let index = 0;
+    while (index < command.length) {
+        const char = command[index] ?? '';
+        if (quote !== undefined) {
+            if (char === '\\' && quote === '"') {
+                current += char + (command[index + 1] ?? '');
+                index += 2;
+                continue;
+            }
+            current += char;
+            if (char === quote)
+                quote = undefined;
+            index += 1;
+            continue;
+        }
+        if (char === '\\') {
+            current += char + (command[index + 1] ?? '');
+            index += 2;
+            continue;
+        }
+        if (QUOTES.has(char)) {
+            quote = char;
+            current += char;
+            index += 1;
+            continue;
+        }
+        if (SEGMENT_SEPARATORS.has(char)) {
+            index += command[index + 1] === char ? 2 : 1;
+            segments.push(current);
+            current = '';
+            continue;
+        }
+        current += char;
+        index += 1;
+    }
+    segments.push(current);
+    return segments;
+}
 function tokenize(element) {
     return element.split(/\s+/).filter((token) => token.length > 0);
 }

package/dist/esm/types.d.ts

@@ -1,3 +1,7 @@
+import type { ScriptValue } from './default-scripts.js';
+import type { CommandVerbosity } from './verbosity.js';
+export type { ScriptValue, StepSpec } from './default-scripts.js';
+export type { CommandVerbosity } from './verbosity.js';
 export interface BuildConfig {
     extraIgnorePatterns?: string[];
 }
@@ -6,10 +10,15 @@ export interface CheckCacheConfig {
     excludeCommands?: string[];
     extraCommands?: string[];
 }
+export interface OutputConfig {
+    commandVerbosity?: CommandVerbosity;
+    extraAgentEnvVars?: string[];
+}
 export interface NmrConfig {
     build?: BuildConfig;
     checkCache?: CheckCacheConfig;
     devBin?: Record<string, string>;
-    workspaceScripts?: Record<string, string | string[]>;
-    rootScripts?: Record<string, string | string[]>;
+    output?: OutputConfig;
+    workspaceScripts?: Record<string, ScriptValue>;
+    rootScripts?: Record<string, ScriptValue>;
 }

package/dist/esm/verbosity.d.ts

@@ -1,11 +1,22 @@
-export declare const COMMAND_VERBOSITY_ENV_VAR = "NMR_COMMAND_VERBOSITY";
+import type { OutputConfig } from './types.js';
+export declare const AGENT_ENV_VARS: readonly ["CLAUDECODE", "ROVODEV_CLI", "ROVO_CLI"];
 export declare const COMMAND_VERBOSITIES: readonly ["full", "quiet"];
+export declare const COMMAND_VERBOSITY_ENV_VAR = "NMR_COMMAND_VERBOSITY";
 export type CommandVerbosity = (typeof COMMAND_VERBOSITIES)[number];
-export type VerbosityResolution = {
+export declare function formatVerbosityRejection(source: string, value: string): string;
+export declare function isCommandVerbosity(value: string): value is CommandVerbosity;
+export declare function readVerbosityEnv(env: NodeJS.ProcessEnv): VerbosityRead;
+export interface ResolveVerbosityOptions {
+    env: NodeJS.ProcessEnv;
+    envVerbosity: CommandVerbosity | undefined;
+    output: OutputConfig | undefined;
+    quietFlag: boolean;
+}
+export declare function resolveVerbosity(options: ResolveVerbosityOptions): CommandVerbosity;
+export type VerbosityRead = {
     ok: true;
-    verbosity: CommandVerbosity;
+    verbosity?: CommandVerbosity;
 } | {
     ok: false;
     error: string;
 };
-export declare function resolveVerbosity(env: NodeJS.ProcessEnv, quietFlag: boolean): VerbosityResolution;

package/dist/esm/verbosity.js

@@ -1,17 +1,37 @@
-export const COMMAND_VERBOSITY_ENV_VAR = 'NMR_COMMAND_VERBOSITY';
+export const AGENT_ENV_VARS = ['CLAUDECODE', 'ROVODEV_CLI', 'ROVO_CLI'];
 export const COMMAND_VERBOSITIES = ['full', 'quiet'];
-export function resolveVerbosity(env, quietFlag) {
-    const raw = env[COMMAND_VERBOSITY_ENV_VAR];
-    const inherited = raw === undefined || raw === '' ? 'full' : raw;
-    if (!isCommandVerbosity(inherited)) {
-        return {
-            ok: false,
-            error: `${COMMAND_VERBOSITY_ENV_VAR} is \`${inherited}\`, which is not one of: ${COMMAND_VERBOSITIES.join(', ')}`,
-        };
-    }
-    return { ok: true, verbosity: quietFlag ? 'quiet' : inherited };
+export const COMMAND_VERBOSITY_ENV_VAR = 'NMR_COMMAND_VERBOSITY';
+export function formatVerbosityRejection(source, value) {
+    return `${source} is \`${value}\`, which is not one of: ${COMMAND_VERBOSITIES.join(', ')}`;
 }
-function isCommandVerbosity(value) {
+export function isCommandVerbosity(value) {
     const names = COMMAND_VERBOSITIES;
     return names.includes(value);
 }
+export function readVerbosityEnv(env) {
+    const raw = env[COMMAND_VERBOSITY_ENV_VAR];
+    if (raw === undefined || raw === '') {
+        return { ok: true };
+    }
+    if (!isCommandVerbosity(raw)) {
+        return { ok: false, error: formatVerbosityRejection(COMMAND_VERBOSITY_ENV_VAR, raw) };
+    }
+    return { ok: true, verbosity: raw };
+}
+export function resolveVerbosity(options) {
+    const { env, envVerbosity, output, quietFlag } = options;
+    if (quietFlag)
+        return 'quiet';
+    if (envVerbosity !== undefined)
+        return envVerbosity;
+    if (output?.commandVerbosity !== undefined)
+        return output.commandVerbosity;
+    return hasAgentMarker(env, output?.extraAgentEnvVars) ? 'quiet' : 'full';
+}
+function hasAgentMarker(env, extraNames) {
+    const names = extraNames === undefined ? AGENT_ENV_VARS : [...AGENT_ENV_VARS, ...extraNames];
+    return names.some((name) => {
+        const value = env[name];
+        return value !== undefined && value !== '';
+    });
+}

package/dist/esm/verdict.d.ts

@@ -0,0 +1,29 @@
+import type { Writable } from 'node:stream';
+import type { ReplayLine } from './check-cache.js';
+import type { ReportFormat } from './report-format.js';
+export declare const VERDICT_LINE_LIMIT = 512;
+export type Verdict = {
+    command: string;
+    scope: string;
+} & VerdictOutcome;
+export type VerdictOutcome = {
+    detail?: string;
+} & ({
+    outcome: 'passed';
+    durationMs: number;
+} | {
+    outcome: 'failed';
+    durationMs: number;
+    exitCode: number;
+} | {
+    outcome: 'recalled';
+    ageMs: number;
+    savedMs: number;
+    replay?: ReplayLine[];
+} | {
+    outcome: 'no-op';
+    reason: 'empty-override' | 'noop-override';
+});
+export declare function renderVerdict(verdict: Verdict): string;
+export declare function serializeVerdict(verdict: Verdict): string;
+export declare function writeVerdict(verdict: Verdict, stream: Writable, format: ReportFormat): void;

package/dist/esm/verdict.js

@@ -0,0 +1,150 @@
+import { clampToBytes, TRUNCATION_MARK } from "./helpers/clampToBytes.js";
+import { formatDuration, formatSaving } from "./helpers/duration.js";
+export const VERDICT_LINE_LIMIT = 512;
+export function renderVerdict(verdict) {
+    const { icon, phrase } = describeOutcome(verdict);
+    const detail = flattenDetail(verdict.detail ?? renderReplay(verdict) ?? '');
+    const detailClause = detail === '' ? '' : ` — ${detail}`;
+    return clampToBytes(`${icon} ${verdict.scope}: ${verdict.command}: ${phrase}${detailClause}`, LINE_BUDGET_BYTES);
+}
+export function serializeVerdict(verdict) {
+    const rendered = JSON.stringify(verdict);
+    return isWithinBudget(rendered) ? rendered : renderWithinBudget(verdict);
+}
+export function writeVerdict(verdict, stream, format) {
+    const line = format === 'json' ? serializeVerdict(verdict) : renderVerdict(verdict);
+    stream.write(`${line}\n`);
+}
+const NEWLINE_BYTES = 1;
+const LINE_BUDGET_BYTES = VERDICT_LINE_LIMIT - NEWLINE_BYTES;
+const MIN_CUT_BYTES = Buffer.byteLength(TRUNCATION_MARK);
+const REPLAY_MARKER = 'replayed:';
+function describeOutcome(verdict) {
+    switch (verdict.outcome) {
+        case 'passed':
+            return { icon: '✅', phrase: `passed in ${formatDuration(verdict.durationMs)}` };
+        case 'failed':
+            return {
+                icon: '❌',
+                phrase: `failed in ${formatDuration(verdict.durationMs)} (exit ${verdict.exitCode})`,
+            };
+        case 'recalled': {
+            const saving = formatSaving(verdict.savedMs);
+            const savingClause = saving === undefined ? '' : `, ${saving}`;
+            return { icon: '⏭️', phrase: `passed ${formatDuration(verdict.ageMs)} ago on this tree${savingClause}` };
+        }
+        case 'no-op':
+            return {
+                icon: '⛔',
+                phrase: `skipped, the override is ${verdict.reason === 'empty-override' ? 'empty' : 'a no-op'}`,
+            };
+        default: {
+            const unhandled = verdict;
+            throw new Error(`Unhandled verdict outcome: ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+function renderReplay(verdict) {
+    if (verdict.outcome !== 'recalled' || verdict.replay === undefined || verdict.replay.length === 0) {
+        return undefined;
+    }
+    const [first] = verdict.replay;
+    if (verdict.replay.length === 1 && first?.command === verdict.command && first.scope === verdict.scope) {
+        return `${REPLAY_MARKER} ${first.excerpt}`;
+    }
+    const lines = verdict.replay.map((line) => `${line.scope}: ${line.command}: ${line.excerpt}`);
+    return `${REPLAY_MARKER} ${lines.join('; ')}`;
+}
+function flattenDetail(detail) {
+    return detail.replaceAll(/[\r\n]+/gu, ' ').trim();
+}
+function findCutTarget(sizes, longest, overrunBytes) {
+    const below = sizes.filter((size) => size < longest && size > MIN_CUT_BYTES);
+    const share = Math.ceil(overrunBytes / sizes.filter((size) => size === longest).length);
+    const target = below.length === 0 ? longest - share : Math.max(...below, longest - overrunBytes);
+    return Math.max(MIN_CUT_BYTES, target);
+}
+function isWithinBudget(rendered) {
+    return Buffer.byteLength(rendered) <= LINE_BUDGET_BYTES;
+}
+function readAttribution(verdict) {
+    if (verdict.outcome !== 'recalled' || verdict.replay === undefined) {
+        return [];
+    }
+    return verdict.replay.map((line) => ({ command: line.command, scope: line.scope }));
+}
+function readCuttableText(verdict) {
+    const excerpts = verdict.outcome === 'recalled' && verdict.replay !== undefined ? verdict.replay.map((line) => line.excerpt) : [];
+    return [verdict.detail ?? '', ...excerpts];
+}
+function renderClamped(record) {
+    const clamped = { ...record };
+    let rendered = JSON.stringify(clamped);
+    while (!isWithinBudget(rendered)) {
+        const fields = ['command', 'scope'];
+        const sizes = fields.map((field) => Buffer.byteLength(typeof clamped[field] === 'string' ? clamped[field] : ''));
+        const longest = Math.max(...sizes);
+        if (longest <= MIN_CUT_BYTES) {
+            return rendered;
+        }
+        const target = findCutTarget(sizes, longest, Buffer.byteLength(rendered) - LINE_BUDGET_BYTES);
+        const field = fields[sizes.indexOf(longest)] ?? 'command';
+        clamped[field] = clampToBytes(typeof clamped[field] === 'string' ? clamped[field] : '', target);
+        rendered = JSON.stringify(clamped);
+    }
+    return rendered;
+}
+function renderWithinBudget(verdict) {
+    const shortened = shortenCuttableText(verdict);
+    const shortenedLine = JSON.stringify(shortened);
+    if (isWithinBudget(shortenedLine)) {
+        return shortenedLine;
+    }
+    const record = { ...shortened };
+    delete record['detail'];
+    const attribution = readAttribution(shortened);
+    for (let kept = attribution.length; kept > 0; kept--) {
+        record['replay'] = attribution.slice(0, kept);
+        const rendered = JSON.stringify(record);
+        if (isWithinBudget(rendered)) {
+            return rendered;
+        }
+    }
+    delete record['replay'];
+    const bare = JSON.stringify(record);
+    return isWithinBudget(bare) ? bare : renderClamped(record);
+}
+function shortenCuttableText(verdict) {
+    let candidate = verdict;
+    let rendered = JSON.stringify(candidate);
+    while (!isWithinBudget(rendered)) {
+        const shortened = shortenLongestText(candidate, Buffer.byteLength(rendered) - LINE_BUDGET_BYTES);
+        if (shortened === undefined) {
+            return candidate;
+        }
+        candidate = shortened;
+        rendered = JSON.stringify(candidate);
+    }
+    return candidate;
+}
+function shortenLongestText(verdict, overrunBytes) {
+    const texts = readCuttableText(verdict);
+    const sizes = texts.map((text) => Buffer.byteLength(text));
+    const longest = Math.max(...sizes);
+    if (longest <= MIN_CUT_BYTES) {
+        return undefined;
+    }
+    const index = sizes.indexOf(longest);
+    const target = findCutTarget(sizes, longest, overrunBytes);
+    return writeCuttableText(verdict, index, clampToBytes(texts[index] ?? '', target));
+}
+function writeCuttableText(verdict, index, value) {
+    if (index === 0) {
+        return { ...verdict, detail: value };
+    }
+    if (verdict.outcome !== 'recalled' || verdict.replay === undefined) {
+        return verdict;
+    }
+    const replay = verdict.replay.map((line, position) => (position === index - 1 ? { ...line, excerpt: value } : line));
+    return { ...verdict, replay };
+}

package/dist/esm/workspace.d.ts

@@ -1,2 +1,4 @@
+export declare function isMonorepoRoot(dir: string): boolean;
 export declare function findMonorepoRoot(startDir?: string): string;
 export declare function getWorkspacePackageDirs(monorepoRoot: string): string[];
+export declare function readWorkspaceOverrides(monorepoRoot: string): Record<string, string> | undefined;

package/dist/esm/workspace.js

@@ -1,18 +1,23 @@
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { parse } from 'yaml';
+import { readStringValues } from "./helpers/readStringValues.js";
 import { isObject } from "./helpers/type-guards.js";
 import { resolvePackageDirs } from "./helpers/workspace-patterns.js";
+import { UserError } from "./UserError.js";
 const WORKSPACE_MANIFEST = 'pnpm-workspace.yaml';
+export function isMonorepoRoot(dir) {
+    return existsSync(path.join(dir, WORKSPACE_MANIFEST));
+}
 export function findMonorepoRoot(startDir) {
     let dir = path.resolve(startDir ?? process.cwd());
     for (;;) {
-        if (existsSync(path.join(dir, WORKSPACE_MANIFEST))) {
+        if (isMonorepoRoot(dir)) {
             return dir;
         }
         const parent = path.dirname(dir);
         if (parent === dir) {
-            throw new Error(`Could not find monorepo root: no ${WORKSPACE_MANIFEST} found in any parent directory`);
+            throw new UserError(`Could not find monorepo root: no ${WORKSPACE_MANIFEST} found in any parent directory`);
         }
         dir = parent;
     }
@@ -20,7 +25,7 @@ export function findMonorepoRoot(startDir) {
 export function getWorkspacePackageDirs(monorepoRoot) {
     const workspaceFile = path.join(monorepoRoot, WORKSPACE_MANIFEST);
     if (!existsSync(workspaceFile)) {
-        throw new Error(`Not a monorepo root: no ${WORKSPACE_MANIFEST} in ${monorepoRoot}`);
+        throw new UserError(`Not a monorepo root: no ${WORKSPACE_MANIFEST} in ${monorepoRoot}`);
     }
     const content = readFileSync(workspaceFile, 'utf8');
     const parsed = parse(content);
@@ -30,6 +35,18 @@ export function getWorkspacePackageDirs(monorepoRoot) {
     }
     return resolvePackageDirs(monorepoRoot, packages);
 }
+export function readWorkspaceOverrides(monorepoRoot) {
+    const workspaceFile = path.join(monorepoRoot, WORKSPACE_MANIFEST);
+    if (!existsSync(workspaceFile)) {
+        return undefined;
+    }
+    const parsed = parse(readFileSync(workspaceFile, 'utf8'));
+    if (!isObject(parsed)) {
+        return undefined;
+    }
+    const overrides = parsed['overrides'];
+    return isObject(overrides) ? readStringValues(overrides) : undefined;
+}
 function getPackagesFromParsedYaml(parsed) {
     if (!isObject(parsed))
         return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -20,6 +20,9 @@
   },
   "license": "ISC",
   "author": "William Thorsen <william@thorsen.dev> (https://github.com/williamthorsen)",
+  "sideEffects": [
+    "./dist/esm/cli*.js"
+  ],
   "type": "module",
   "exports": {
     "./config": {
@@ -53,6 +56,7 @@
     "nmr-clean": "bin/nmr-clean.js",
     "nmr-compile": "bin/nmr-compile.js",
     "nmr-fmt": "bin/nmr-fmt.js",
+    "nmr-report-catalog": "bin/nmr-report-catalog.js",
     "nmr-report-overrides": "bin/nmr-report-overrides.js",
     "nmr-taze": "bin/nmr-taze.js"
   },
@@ -64,16 +68,18 @@
     "dist"
   ],
   "dependencies": {
+    "@williamthorsen/toolbelt.errors": "0.4.0",
     "glob": "13.0.6",
     "prettier-plugin-sh": "0.19.0",
-    "taze": "19.17.1",
+    "taze": "20.0.0",
     "yaml": "2.9.0",
-    "@williamthorsen/nmr-core": "0.9.3"
+    "@williamthorsen/nmr-core": "0.10.0"
   },
   "devDependencies": {
     "prettier": "3.9.6",
-    "readyup": "0.26.0",
+    "readyup": "0.27.0",
     "tinyglobby": "0.2.17",
+    "typescript": "6.0.3",
     "vitest": "4.1.10"
   },
   "peerDependencies": {
@@ -90,7 +96,8 @@
     }
   },
   "engines": {
-    "node": ">=24.16.0"
+    "node": ">=24.16.0",
+    "pnpm": ">=11"
   },
   "publishConfig": {
     "access": "public"