@williamthorsen/nmr 0.23.0 → 0.25.0

package/dist/esm/config.js

@@ -1,11 +1,34 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { createJiti } from 'jiti';
-import { isObject } from "./helpers/type-guards.js";
+import { pathToFileURL } from 'node:url';
+import { isObject, isStringRecord } from "./helpers/type-guards.js";
 const CONFIG_FILENAME = 'nmr.config.ts';
 const CONFIG_DIR = '.config';
-export function defineConfig(config) {
-    return config;
+const CONFIG_TIERS = {
+    root: {
+        label: 'a monorepo-root config',
+        honoredKeys: ['checkCache', 'devBin', 'rootScripts', 'workspaceScripts'],
+        elsewhere: "the package's own config",
+    },
+    workspace: {
+        label: 'a package config',
+        honoredKeys: ['build'],
+        elsewhere: 'the monorepo-root config',
+    },
+};
+const RECOGNIZED_KEYS = [...CONFIG_TIERS.root.honoredKeys, ...CONFIG_TIERS.workspace.honoredKeys];
+const RECOGNIZED_BUILD_KEYS = ['extraIgnorePatterns'];
+const RECOGNIZED_CHECK_CACHE_KEYS = ['enabled', 'excludeCommands', 'extraCommands'];
+export function resolveConfigPath(baseDir) {
+    return path.join(baseDir, CONFIG_DIR, CONFIG_FILENAME);
 }
 function isScriptRecord(value) {
     if (!isObject(value))
@@ -27,14 +50,52 @@ function validateScriptField(value, fieldName, configPath) {
     }
     return value[fieldName];
 }
-function isStringRecord(value) {
-    if (!isObject(value))
-        return false;
-    for (const v of Object.values(value)) {
-        if (typeof v !== 'string')
-            return false;
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function validateBuildField(value, configPath) {
+    const build = value.build;
+    if (build === undefined) {
+        return undefined;
     }
-    return true;
+    if (!isObject(build)) {
+        throw new Error(`Invalid nmr config at ${configPath}: \`build\` must be an object`);
+    }
+    assertRecognizedKeys(build, RECOGNIZED_BUILD_KEYS, configPath, 'build.');
+    const extraIgnorePatterns = build.extraIgnorePatterns;
+    if (extraIgnorePatterns !== undefined && !isStringArray(extraIgnorePatterns)) {
+        throw new Error(`Invalid nmr config at ${configPath}: \`build.extraIgnorePatterns\` must be a string[]`);
+    }
+    return extraIgnorePatterns === undefined ? {} : { extraIgnorePatterns };
+}
+function validateCheckCacheField(value, configPath) {
+    const checkCache = value.checkCache;
+    if (checkCache === undefined) {
+        return undefined;
+    }
+    if (!isObject(checkCache)) {
+        throw new Error(`Invalid nmr config at ${configPath}: \`checkCache\` must be an object`);
+    }
+    assertRecognizedKeys(checkCache, RECOGNIZED_CHECK_CACHE_KEYS, configPath, 'checkCache.');
+    const config = {};
+    const enabled = checkCache.enabled;
+    if (enabled !== undefined) {
+        if (typeof enabled !== 'boolean') {
+            throw new Error(`Invalid nmr config at ${configPath}: \`checkCache.enabled\` must be a boolean`);
+        }
+        config.enabled = enabled;
+    }
+    for (const field of ['excludeCommands', 'extraCommands']) {
+        const commands = checkCache[field];
+        if (commands === undefined) {
+            continue;
+        }
+        if (!isStringArray(commands)) {
+            throw new Error(`Invalid nmr config at ${configPath}: \`checkCache.${field}\` must be a string[]`);
+        }
+        config[field] = commands;
+    }
+    return config;
 }
 function validateStringRecordField(value, fieldName, configPath) {
     if (!(fieldName in value) || value[fieldName] === undefined) {
@@ -49,7 +110,14 @@ function validateConfig(value, configPath) {
     if (!isObject(value)) {
         throw new Error(`Invalid nmr config at ${configPath}: expected an object, got ${typeof value}`);
     }
+    assertRecognizedKeys(value, RECOGNIZED_KEYS, configPath);
     const config = {};
+    const build = validateBuildField(value, configPath);
+    if (build)
+        config.build = build;
+    const checkCache = validateCheckCacheField(value, configPath);
+    if (checkCache)
+        config.checkCache = checkCache;
     const devBin = validateStringRecordField(value, 'devBin', configPath);
     if (devBin)
         config.devBin = devBin;
@@ -61,12 +129,44 @@ function validateConfig(value, configPath) {
         config.rootScripts = rootScripts;
     return config;
 }
-export async function loadConfig(monorepoRoot) {
-    const configPath = path.join(monorepoRoot, CONFIG_DIR, CONFIG_FILENAME);
+export async function loadConfig(baseDir) {
+    const configPath = resolveConfigPath(baseDir);
     if (!existsSync(configPath)) {
         return {};
     }
-    const jiti = createJiti(path.join(monorepoRoot, 'package.json'));
-    const loaded = await jiti.import(configPath, { default: true });
+    const imported = await import(__rewriteRelativeImportExtension(pathToFileURL(configPath).href));
+    const loaded = isObject(imported) ? imported.default : undefined;
     return validateConfig(loaded, configPath);
 }
+export async function loadRootConfig(monorepoRoot) {
+    const config = await loadConfig(monorepoRoot);
+    assertTierKeys(config, CONFIG_TIERS.root, resolveConfigPath(monorepoRoot));
+    return config;
+}
+export async function loadWorkspaceConfig(packageDir) {
+    const config = await loadConfig(packageDir);
+    assertTierKeys(config, CONFIG_TIERS.workspace, resolveConfigPath(packageDir));
+    return config;
+}
+function assertRecognizedKeys(value, recognizedKeys, configPath, prefix = '') {
+    const unrecognized = Object.keys(value).filter((key) => !recognizedKeys.includes(key));
+    if (unrecognized.length === 0) {
+        return;
+    }
+    throw new Error(`Invalid nmr config at ${configPath}: unrecognized ${unrecognized.length === 1 ? 'key' : 'keys'} ` +
+        `${formatKeyList(unrecognized, prefix)}. Recognized: ${formatKeyList(recognizedKeys, prefix)}.`);
+}
+function assertTierKeys(config, tier, configPath) {
+    const unsupported = Object.keys(config).filter((key) => !tier.honoredKeys.includes(key));
+    if (unsupported.length === 0) {
+        return;
+    }
+    throw new Error(`Invalid nmr config at ${configPath}: ${tier.label} honors ${tier.honoredKeys.toSorted().join(', ')} alone, ` +
+        `not ${unsupported.toSorted().join(', ')}. Move those keys to ${tier.elsewhere}.`);
+}
+function formatKeyList(keys, prefix) {
+    return keys
+        .toSorted()
+        .map((key) => `\`${prefix}${key}\``)
+        .join(', ');
+}

package/dist/esm/context.d.ts

@@ -1,4 +1,4 @@
-import type { NmrConfig } from './config.js';
+import type { NmrConfig } from './types.js';
 export interface ResolvedContext {
     monorepoRoot: string;
     isRoot: boolean;

package/dist/esm/context.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { loadConfig } from "./config.js";
+import { loadRootConfig } from "./config.js";
 import { findMonorepoRoot, getWorkspacePackageDirs } from "./workspace.js";
 export function findContainingPackageDir(dir, workspacePackageDirs) {
     const resolved = path.resolve(dir);
@@ -17,7 +17,7 @@ export function findContainingPackageDir(dir, workspacePackageDirs) {
 export async function resolveContext(cwd) {
     const resolvedCwd = path.resolve(cwd ?? process.cwd());
     const monorepoRoot = findMonorepoRoot(resolvedCwd);
-    const config = await loadConfig(monorepoRoot);
+    const config = await loadRootConfig(monorepoRoot);
     const workspaceDirs = getWorkspacePackageDirs(monorepoRoot);
     const packageDir = findContainingPackageDir(resolvedCwd, workspaceDirs);
     return {

package/dist/esm/default-scripts.js

@@ -1,3 +1,4 @@
+const GATE_PROJECTS = '--project unit --project tool';
 export const workspaceScripts = {
     build: ['compile'],
     check: ['typecheck', 'fmt:check', 'lint:check', 'test'],
@@ -11,11 +12,12 @@ export const workspaceScripts = {
     lint: 'eslint --fix .',
     'lint:check': 'eslint .',
     'lint:strict': 'strict-lint',
-    test: "pnpm exec vitest --project '!integration'",
+    test: `pnpm exec vitest ${GATE_PROJECTS}`,
     'test:all': 'pnpm exec vitest',
-    'test:coverage': "pnpm exec vitest --project '!integration' --coverage",
-    'test:integration': 'pnpm exec vitest --project integration',
-    'test:watch': "pnpm exec vitest --project '!integration' --watch",
+    'test:coverage': `pnpm exec vitest ${GATE_PROJECTS} --coverage`,
+    'test:tool': 'pnpm exec vitest --project tool',
+    'test:unit': 'pnpm exec vitest --project unit',
+    'test:watch': `pnpm exec vitest ${GATE_PROJECTS} --watch`,
     typecheck: 'tsgo --noEmit',
     upgrade: 'nmr-taze --include-locked',
     'view-coverage': 'open coverage/index.html',
@@ -28,7 +30,7 @@ export const rootScripts = {
     check: ['typecheck', 'fmt:check', 'lint:check', 'test'],
     'check:agent-files': 'nmr-sync-agent-files --check',
     'check:strict': ['typecheck', 'fmt:check', 'lint:strict', 'test:coverage', 'check:agent-files'],
-    ci: ['build', 'check:strict', 'audit'],
+    ci: ['build', 'check:strict'],
     clean: 'nmr-clean',
     fix: ['lint', 'fmt'],
     'fix:check': ['fmt:check', 'lint:check'],
@@ -37,22 +39,25 @@ export const rootScripts = {
     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',
+    prepush: ['ci', 'audit'],
     'report-overrides': 'nmr-report-overrides',
     'root:check': ['root:typecheck', 'fmt:check', 'root:lint:check', 'root:test'],
     'root:lint': "eslint --fix --ignore-pattern 'packages/**' .",
     'root:lint:check': "eslint --ignore-pattern 'packages/**' .",
     'root:lint:strict': "strict-lint --ignore-pattern 'packages/**' .",
-    'root:test': "vitest --config ./vitest.root.config.ts --project '!integration'",
+    'root:test': `vitest --config ./vitest.root.config.ts ${GATE_PROJECTS}`,
     'root:test:all': 'vitest --config ./vitest.root.config.ts',
-    'root:test:integration': 'vitest --config ./vitest.root.config.ts --project integration',
+    'root:test:tool': 'vitest --config ./vitest.root.config.ts --project tool',
+    'root:test:unit': 'vitest --config ./vitest.root.config.ts --project unit',
     'root:typecheck': 'tsgo --noEmit',
     'root:upgrade': 'nmr-taze --include-locked',
     'sync-agent-files': 'nmr-sync-agent-files',
     test: 'nmr root:test && pnpm --recursive exec nmr test',
     'test:all': 'nmr root:test:all && pnpm --recursive exec nmr test:all',
     'test:coverage': 'nmr root:test && pnpm --recursive exec nmr test:coverage',
-    'test:integration': 'nmr root:test:integration && pnpm --recursive exec nmr test:integration',
-    'test:watch': "vitest --project '!integration' --watch",
+    'test:tool': 'nmr root:test:tool && pnpm --recursive exec nmr test:tool',
+    'test:unit': 'nmr root:test:unit && pnpm --recursive exec nmr test:unit',
+    'test:watch': `vitest ${GATE_PROJECTS} --watch`,
     typecheck: 'nmr root:typecheck && pnpm --recursive exec nmr typecheck',
     upgrade: 'nmr-report-overrides && nmr-taze --include-locked --recursive',
 };

package/dist/esm/defineConfig.d.ts

@@ -0,0 +1,3 @@
+import type { NmrConfig } from './types.js';
+export type { BuildConfig, CheckCacheConfig, NmrConfig } from './types.js';
+export declare function defineConfig(config: NmrConfig): NmrConfig;

package/dist/esm/defineConfig.js

@@ -0,0 +1,3 @@
+export function defineConfig(config) {
+    return config;
+}

package/dist/esm/help.d.ts

@@ -1,2 +1,2 @@
-import type { NmrConfig } from './config.js';
+import type { NmrConfig } from './types.js';
 export declare function generateHelp(config: NmrConfig, packageDir: string | undefined, useRoot: boolean): string;

package/dist/esm/help.js

@@ -9,6 +9,7 @@ export function generateHelp(config, packageDir, useRoot) {
         '  -R, --recursive          Run command in all packages',
         '  -w, --workspace-root     Use root scripts, running at the monorepo root',
         '  -q, --quiet              Suppress output on success; show full output on failure',
+        '      --no-cache           Run even if this tree already passed; record the result',
         '  -?, --help               Show this help',
         '  -V, --version            Show version number',
         '',

package/dist/esm/helpers/duration.d.ts

@@ -0,0 +1,2 @@
+export declare function formatDuration(milliseconds: number): string;
+export declare function formatSaving(milliseconds: number): string | undefined;

package/dist/esm/helpers/duration.js

@@ -0,0 +1,21 @@
+export function formatDuration(milliseconds) {
+    const seconds = Math.round(milliseconds / MILLISECONDS_PER_SECOND);
+    if (seconds < SECONDS_PER_MINUTE) {
+        return `${seconds}s`;
+    }
+    const minutes = Math.round(seconds / SECONDS_PER_MINUTE);
+    if (minutes < MINUTES_PER_HOUR) {
+        return `${minutes}m`;
+    }
+    return `${Math.round(minutes / MINUTES_PER_HOUR)}h`;
+}
+export function formatSaving(milliseconds) {
+    if (!Number.isFinite(milliseconds) || milliseconds < MILLISECONDS_PER_SECOND) {
+        return undefined;
+    }
+    return `${SPEED_BOOST_ICON} saved ~${formatDuration(milliseconds)}`;
+}
+const MILLISECONDS_PER_SECOND = 1000;
+const MINUTES_PER_HOUR = 60;
+const SECONDS_PER_MINUTE = 60;
+const SPEED_BOOST_ICON = '🚀';

package/dist/esm/helpers/type-guards.d.ts

@@ -1 +1,2 @@
 export declare function isObject(value: unknown): value is Record<string, unknown>;
+export declare function isStringRecord(value: unknown): value is Record<string, string>;

package/dist/esm/helpers/type-guards.js

@@ -1,3 +1,6 @@
 export function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+export function isStringRecord(value) {
+    return isObject(value) && Object.values(value).every((entry) => typeof entry === 'string');
+}

package/dist/esm/resolver.d.ts

@@ -1,5 +1,5 @@
-import type { NmrConfig } from './config.js';
 import type { ScriptRegistry, ScriptValue } from './resolve-scripts.js';
+import type { NmrConfig } from './types.js';
 export declare function applyDevBin(command: string, devBin: Record<string, string> | undefined, monorepoRoot: string): string;
 export interface ResolvedScript {
     command: string;

package/dist/esm/runCli.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { readPackageVersion, reportError } from '@williamthorsen/nmr-core';
+import { computeCacheKey, CURRENT_RUNTIME, encodeTreeSnapshot, findStaleBuildOutput, formatMisplacedNoCacheWarning, formatSkipLine, NO_CACHE_ENV_VAR, readBuildOutputState, readCheckCacheEntry, resolveCacheableCommands, resolveTreeSnapshot, TREE_SNAPSHOT_ENV_VAR, writeCheckCacheEntry, writeDebugNote, } from "./check-cache.js";
 import { resolveContext } from "./context.js";
 import { generateHelp } from "./help.js";
 import { isHookName } from "./helpers/hook-name.js";
@@ -27,16 +28,26 @@ export async function runCli(options) {
     }
     const { command } = parsed;
     const passthrough = parsed.passthrough.length > 0 ? ' ' + parsed.passthrough.map(shellQuote).join(' ') : '';
-    const runOptions = { quiet: parsed.quiet, stdout, stderr, env };
+    const snapshot = openGate({
+        command,
+        config: context.config,
+        env,
+        monorepoRoot: context.monorepoRoot,
+        passthrough: parsed.passthrough,
+        stderr,
+    });
+    const noCache = parsed.noCache || env[NO_CACHE_ENV_VAR] === '1';
+    const childEnv = buildChildEnv(env, snapshot, noCache);
+    const runOptions = { quiet: parsed.quiet, stdout, stderr, env: childEnv };
     if (parsed.filter) {
         const delegateCmd = `pnpm --filter ${shellQuote(parsed.filter)} exec nmr ${command}${passthrough}`;
         const exitCode = runCommand(delegateCmd, context.monorepoRoot, runOptions);
         return { exitCode };
     }
     if (parsed.recursive) {
-        const childEnv = { ...env, NMR_RUN_IF_PRESENT: '1' };
+        const delegateEnv = { ...childEnv, NMR_RUN_IF_PRESENT: '1' };
         const delegateCmd = `pnpm --recursive exec nmr ${command}${passthrough}`;
-        const exitCode = runCommand(delegateCmd, context.monorepoRoot, { ...runOptions, env: childEnv });
+        const exitCode = runCommand(delegateCmd, context.monorepoRoot, { ...runOptions, env: delegateEnv });
         return { exitCode };
     }
     const registry = useRoot ? buildRootRegistry(context.config) : buildWorkspaceRegistry(context.config);
@@ -52,20 +63,122 @@ export async function runCli(options) {
     if (skipExitCode !== undefined) {
         return { exitCode: skipExitCode };
     }
-    if (resolved.source === 'package' && !parsed.quiet && registry[command] !== undefined) {
-        stdout.write(`📦 ${path.basename(anchorDir)}: Using override script: ${resolved.command}\n`);
-    }
     const substitutedCommand = applyDevBin(resolved.command, context.config.devBin, context.monorepoRoot);
     const mainCommand = substitutedCommand + passthrough;
     const isHookInvocation = isHookName(command);
     const fullCommand = isHookInvocation
         ? mainCommand
         : wrapWithHooks(command, mainCommand, registry, anchorDir, parsed.workspaceRoot);
-    const exitCode = runCommand(fullCommand, anchorDir, runOptions);
+    const key = resolveCacheKey({
+        anchorDir,
+        command,
+        commandString: fullCommand,
+        env,
+        monorepoRoot: context.monorepoRoot,
+        snapshot,
+        stderr,
+        substitution: substitutedCommand === resolved.command ? undefined : substitutedCommand,
+    });
+    const exitCode = await runGated({
+        anchorDir,
+        command,
+        commandString: fullCommand,
+        config: context.config,
+        env,
+        key,
+        monorepoRoot: context.monorepoRoot,
+        noCache,
+        overrideNotice: formatOverrideNotice(resolved, registry, command, anchorDir, parsed.quiet),
+        quiet: parsed.quiet,
+        runOptions,
+        snapshot,
+        stderr,
+        stdout,
+    });
     return { exitCode };
 }
+function buildChildEnv(env, snapshot, noCache) {
+    return {
+        ...env,
+        ...(snapshot !== undefined && { [TREE_SNAPSHOT_ENV_VAR]: encodeTreeSnapshot(snapshot) }),
+        ...(noCache && { [NO_CACHE_ENV_VAR]: '1' }),
+    };
+}
+function formatOverrideNotice(resolved, registry, command, anchorDir, quiet) {
+    if (quiet || resolved.source !== 'package' || registry[command] === undefined) {
+        return undefined;
+    }
+    return `📦 ${path.basename(anchorDir)}: Using override script: ${resolved.command}\n`;
+}
+function handleSkipMessage(resolvedCommand, anchorDir, quiet, stdout) {
+    if (resolvedCommand === '') {
+        if (!quiet) {
+            stdout.write(`⛔ ${path.basename(anchorDir)}: Override script is defined but empty. Skipping.\n`);
+        }
+        return 0;
+    }
+    if (resolvedCommand === ':') {
+        if (!quiet) {
+            stdout.write(`⛔ ${path.basename(anchorDir)}: Override script is a no-op. Skipping.\n`);
+        }
+        return 0;
+    }
+    return undefined;
+}
+function hasRunnableHook(hookName, registry, anchorDir, workspaceRoot) {
+    const resolved = resolveScript(hookName, registry, anchorDir, workspaceRoot);
+    if (!resolved)
+        return false;
+    return resolved.command !== '' && resolved.command !== ':';
+}
+async function lookUpRecordedPass(options) {
+    const { anchorDir, command, env, key, monorepoRoot, stderr } = options;
+    const entry = await readCheckCacheEntry({ anchorDir, command, monorepoRoot });
+    if (entry === undefined) {
+        writeDebugNote(`running ${command}: no pass recorded for this scope`, env, stderr);
+        return undefined;
+    }
+    if (entry.key !== key) {
+        writeDebugNote(`running ${command}: the tree or its inputs changed since the last pass`, env, stderr);
+        return undefined;
+    }
+    const output = await readBuildOutputState(monorepoRoot, options.config);
+    const [missing] = output.missing;
+    if (missing !== undefined) {
+        writeDebugNote(`running ${command}: ${missing} has no build output`, env, stderr);
+        return undefined;
+    }
+    const stale = findStaleBuildOutput(entry.buildDigests, output.digests);
+    if (stale !== undefined) {
+        writeDebugNote(`running ${command}: ${stale}'s build output came from a different tree`, env, stderr);
+        return undefined;
+    }
+    return formatSkipLine(command, entry, Date.now());
+}
+function openGate(options) {
+    const { command, config, env, monorepoRoot, passthrough, stderr } = options;
+    const covered = !isHookName(command) &&
+        config.checkCache?.enabled !== false &&
+        resolveCacheableCommands(config.checkCache).has(command);
+    if (!covered) {
+        return undefined;
+    }
+    if (passthrough.includes('--no-cache')) {
+        stderr.write(`${formatMisplacedNoCacheWarning(command)}\n`);
+    }
+    if (passthrough.length > 0) {
+        return undefined;
+    }
+    const snapshot = resolveTreeSnapshot({ monorepoRoot, env });
+    if (!snapshot.ok) {
+        writeDebugNote(`gate disabled: ${snapshot.reason}`, env, stderr);
+        return undefined;
+    }
+    return snapshot.snapshot;
+}
 function parseArgs(args) {
     const parsed = {
+        noCache: false,
         quiet: false,
         recursive: false,
         workspaceRoot: false,
@@ -113,26 +226,124 @@ function parseArgs(args) {
             i++;
             continue;
         }
+        if (arg === '--no-cache') {
+            parsed.noCache = true;
+            i++;
+            continue;
+        }
         parsed.command = arg;
         parsed.passthrough = args.slice(i + 1);
         break;
     }
     return { ok: true, parsed };
 }
-function handleSkipMessage(resolvedCommand, anchorDir, quiet, stdout) {
-    if (resolvedCommand === '') {
-        if (!quiet) {
-            stdout.write(`⛔ ${path.basename(anchorDir)}: Override script is defined but empty. Skipping.\n`);
-        }
-        return 0;
+async function recordPass(options) {
+    const { anchorDir, command, env, monorepoRoot, snapshot, stderr } = options;
+    const current = resolveTreeSnapshot({ monorepoRoot, env: {} });
+    if (!current.ok) {
+        writeDebugNote(`not recording ${command}: ${current.reason}`, env, stderr);
+        return;
     }
-    if (resolvedCommand === ':') {
-        if (!quiet) {
-            stdout.write(`⛔ ${path.basename(anchorDir)}: Override script is a no-op. Skipping.\n`);
+    if (current.snapshot.hash !== snapshot.hash) {
+        writeDebugNote(`not recording ${command}: the tree changed while it ran`, env, stderr);
+        return;
+    }
+    const output = await readBuildOutputState(monorepoRoot, options.config);
+    const [missing] = output.missing;
+    if (missing !== undefined) {
+        writeDebugNote(`not recording ${command}: ${missing} has no build output`, env, stderr);
+        return;
+    }
+    try {
+        await writeCheckCacheEntry({
+            anchorDir,
+            command,
+            monorepoRoot,
+            entry: {
+                key: options.key,
+                treeHash: snapshot.hash,
+                headSha: snapshot.headSha,
+                commandString: options.commandString,
+                nmrVersion: VERSION,
+                nodeVersion: CURRENT_RUNTIME.nodeVersion,
+                durationMs: options.durationMs,
+                recordedAt: new Date().toISOString(),
+                buildDigests: output.digests,
+            },
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        writeDebugNote(`could not record ${command}: ${message}`, env, stderr);
+    }
+}
+function resolveCacheKey(options) {
+    const { env, snapshot, stderr, substitution } = options;
+    if (snapshot === undefined) {
+        return undefined;
+    }
+    if (substitution !== undefined) {
+        writeDebugNote(`gate disabled: devBin substituted \`${substitution}\``, env, stderr);
+        return undefined;
+    }
+    const result = computeCacheKey({
+        anchorDir: options.anchorDir,
+        command: options.command,
+        commandString: options.commandString,
+        env,
+        monorepoRoot: options.monorepoRoot,
+        nmrVersion: VERSION,
+        snapshot,
+    });
+    if (!result.ok) {
+        writeDebugNote(`gate disabled: ${result.reason}`, env, stderr);
+        return undefined;
+    }
+    return result.key;
+}
+async function runGated(options) {
+    const { anchorDir, command, commandString, env, key, monorepoRoot, snapshot, stderr, stdout } = options;
+    const gated = key !== undefined && snapshot !== undefined;
+    if (gated && !options.noCache) {
+        const skipLine = await lookUpRecordedPass({
+            anchorDir,
+            command,
+            config: options.config,
+            env,
+            key,
+            monorepoRoot,
+            stderr,
+        });
+        if (skipLine !== undefined) {
+            if (!options.quiet) {
+                stdout.write(`${skipLine}\n`);
+            }
+            return 0;
         }
-        return 0;
     }
-    return undefined;
+    if (options.overrideNotice !== undefined) {
+        stdout.write(options.overrideNotice);
+    }
+    const startedAt = Date.now();
+    const exitCode = runCommand(commandString, anchorDir, options.runOptions);
+    if (exitCode === 0 && gated) {
+        await recordPass({
+            anchorDir,
+            command,
+            commandString,
+            config: options.config,
+            durationMs: Date.now() - startedAt,
+            env,
+            key,
+            monorepoRoot,
+            snapshot,
+            stderr,
+        });
+    }
+    return exitCode;
+}
+function shellQuote(arg) {
+    return "'" + arg.replace(/'/g, String.raw `'\''`) + "'";
 }
 function wrapWithHooks(command, mainCommand, registry, anchorDir, workspaceRoot) {
     const segments = [];
@@ -146,12 +357,3 @@ function wrapWithHooks(command, mainCommand, registry, anchorDir, workspaceRoot)
     }
     return segments.join(' && ');
 }
-function hasRunnableHook(hookName, registry, anchorDir, workspaceRoot) {
-    const resolved = resolveScript(hookName, registry, anchorDir, workspaceRoot);
-    if (!resolved)
-        return false;
-    return resolved.command !== '' && resolved.command !== ':';
-}
-function shellQuote(arg) {
-    return "'" + arg.replace(/'/g, String.raw `'\''`) + "'";
-}

package/dist/esm/tiers.d.ts

@@ -0,0 +1,7 @@
+export declare const ALL_TEST_PATTERNS: string[];
+export declare function buildTierPatterns(tier: string): string[];
+export declare function findTestFiles(rootDir: string): string[];
+export declare function hasTierInfix(filePath: string): boolean;
+export declare const TEST_COLLECTION_EXCLUDE: string[];
+export declare const TIER_NAMES: readonly ["unit", "tool", "localhost", "remote"];
+export type TierName = (typeof TIER_NAMES)[number];