@williamthorsen/nmr 2.0.0 → 2.0.1

package/dist/esm/commands/build.js

@@ -1,30 +1,24 @@
 import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
-import { readFile, rename, rm } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { formatGlyphLine, readCacheEntry, startTimer, STATUS_GLYPHS, UserError, writeCacheEntry, } from '@williamthorsen/nmr-core';
-import { describeError } from '@williamthorsen/toolbelt.errors';
-import { glob } from 'glob';
-import { NMR_GLYPHS } from "../glyphs.js";
+import { readCacheEntry, startTimer, UserError, writeCacheEntry } from '@williamthorsen/nmr-core';
 import { resolveConfigPath } from "../helpers/config-path.js";
-import { formatSaving } from "../helpers/duration.js";
 import { writeStatedOutcome } from "../stated-outcome.js";
-import { DEFAULT_ENTRY_GLOBS, DEFAULT_IGNORE_PATTERNS, DEFAULT_OUTDIR, hasExpectedBuildOutput, readEmitDuration, resolveBuildCachePath, resolveScratchDirs, resolveToolchainFingerprint, writeEmitDuration, } from "./build-output.js";
+import { DEFAULT_OUTDIR, hasExpectedBuildOutput, readEmitDuration, resolveBuildCachePath, resolveEntryPoints, resolveToolchainFingerprint, writeEmitDuration, } from "./build-output.js";
 import { assertSupportedTypeScript, formatDiagnostics, getCompiler, loadCompiler } from "./compiler.js";
-import { isWithin, rewriteSpecifiers } from "./rewrite-specifiers.js";
+import { discardScratchDirs, publishOutput, removeScratchDirs } from "./publish-output.js";
+import { rewriteSpecifiers } from "./rewrite-specifiers.js";
 import { resolveTsconfigChain } from "./tsconfig-chain.js";
 const SOURCE_ROOT = 'src';
-export async function buildPackage(packageDir, options) {
+export async function buildPackage(packageDir, options = {}) {
     await loadCompiler(options.loadTypeScript);
     assertSupportedTypeScript();
     const cachePath = resolveBuildCachePath(packageDir);
     const outdir = options.outdir ?? DEFAULT_OUTDIR;
     const emitDir = resolveEmitDir(packageDir, outdir);
     const emitConfig = { outdir, declaration: true, rewriteRelativeImportExtensions: true };
-    const entryPoints = await glob(options.entryGlobs ?? DEFAULT_ENTRY_GLOBS, {
-        cwd: packageDir,
-        ignore: [...(options.ignorePatterns ?? DEFAULT_IGNORE_PATTERNS), ...(options.extraIgnorePatterns ?? [])],
-    });
+    const entryPoints = await resolveEntryPoints(packageDir, options);
     const configPath = resolveConfigPath(packageDir);
     const dependencies = [
         'package.json',
@@ -35,17 +29,19 @@ export async function buildPackage(packageDir, options) {
         compilerVersion: getCompiler().version,
         fingerprint: await resolveToolchainFingerprint(packageDir),
     };
-    const { changed, currentHash } = await detectBuildChanges(packageDir, [...entryPoints, ...dependencies], emitConfig, toolchain, cachePath, hasExpectedBuildOutput(packageDir, outdir, entryPoints), options.style);
-    if (!changed) {
-        await discardScratchDirs(resolveScratchDirs(emitDir));
-        return;
+    const { reason, currentHash } = await detectBuildChanges(packageDir, [...entryPoints, ...dependencies], emitConfig, toolchain, cachePath, hasExpectedBuildOutput(packageDir, outdir, entryPoints));
+    if (reason === 'unchanged') {
+        await discardScratchDirs(emitDir);
+        const savedMs = await recordUnchangedBuild(packageDir, currentHash, process.env);
+        return { kind: 'unchanged', ...(savedMs !== undefined && { savedMs }) };
     }
+    options.onProgress?.({ kind: reason });
     const readEmitMs = startTimer();
     const emittedFileCount = await emitPackage(packageDir, entryPoints, outdir);
     const emitMs = readEmitMs();
     await writeCacheEntry(cachePath, currentHash);
     await writeEmitDuration(packageDir, currentHash, emitMs);
-    console.info(formatGlyphLine(NMR_GLYPHS, options.style, 'package', `${path.basename(packageDir)}: ${describeEmit(emittedFileCount, outdir)}`));
+    return { kind: 'emitted', fileCount: emittedFileCount, outdir };
 }
 export async function computeBuildHash(packageDir, files, emitConfig, toolchain) {
     const hash = createHash('sha256');
@@ -67,8 +63,7 @@ async function emitPackage(packageDir, entryPoints, outdir) {
     const rootNames = entryPoints.map((entry) => path.resolve(packageDir, entry));
     const sourceRoot = path.resolve(packageDir, SOURCE_ROOT);
     const emitDir = resolveEmitDir(packageDir, outdir);
-    const scratchDirs = resolveScratchDirs(emitDir);
-    await removeScratchDirs(scratchDirs);
+    await removeScratchDirs(emitDir);
     const emittedFiles = new Map();
     function collect(fileName, text, writeByteOrderMark) {
         emittedFiles.set(fileName, { text, writeByteOrderMark });
@@ -82,13 +77,7 @@ async function emitPackage(packageDir, entryPoints, outdir) {
     for (const [fileName, file] of emittedFiles) {
         stagedFiles.set(fileName, { ...file, text: rewriteSpecifiers(fileName, file.text, compilerOptions, sourceRoot) });
     }
-    if (stagedFiles.size === 0) {
-        await rm(emitDir, { force: true, recursive: true });
-        return 0;
-    }
-    writeStagedOutput(stagedFiles, emitDir, scratchDirs.stagingDir);
-    await swapIntoPlace(emitDir, scratchDirs);
-    return stagedFiles.size;
+    return publishOutput(emitDir, stagedFiles);
 }
 function assertEmitSucceeded(result) {
     if (result.emitSkipped) {
@@ -110,17 +99,6 @@ function createCachingCompilerHost(compilerOptions) {
     };
     return host;
 }
-async function discardScratchDirs(scratchDirs) {
-    try {
-        await removeScratchDirs(scratchDirs);
-    }
-    catch {
-    }
-}
-async function removeScratchDirs(scratchDirs) {
-    await rm(scratchDirs.previousDir, { force: true, recursive: true });
-    await rm(scratchDirs.stagingDir, { force: true, recursive: true });
-}
 function resolveEmitDir(packageDir, outdir) {
     const resolvedDir = path.resolve(packageDir, outdir);
     const relativePathFromPackage = path.relative(packageDir, resolvedDir);
@@ -132,24 +110,6 @@ function resolveEmitDir(packageDir, outdir) {
     }
     return resolvedDir;
 }
-async function swapIntoPlace(emitDir, scratchDirs) {
-    const hadPreviousOutput = existsSync(emitDir);
-    if (hadPreviousOutput) {
-        await rename(emitDir, scratchDirs.previousDir);
-    }
-    try {
-        await rename(scratchDirs.stagingDir, emitDir);
-    }
-    catch (error) {
-        if (hadPreviousOutput && !existsSync(emitDir)) {
-            await rename(scratchDirs.previousDir, emitDir);
-        }
-        throw new UserError(`failed to move the built output into ${emitDir}: ${describeError(error)}`, {
-            cause: error,
-        });
-    }
-    await discardScratchDirs(scratchDirs);
-}
 function synthesizeCompilerOptions(packageDir, outdir) {
     const ts = getCompiler();
     const configPath = path.join(packageDir, 'tsconfig.json');
@@ -176,38 +136,16 @@ function synthesizeCompilerOptions(packageDir, outdir) {
         noEmitOnError: false,
     };
 }
-function writeStagedOutput(stagedFiles, emitDir, stagingDir) {
-    const ts = getCompiler();
-    for (const [fileName, file] of stagedFiles) {
-        if (!isWithin(emitDir, fileName)) {
-            throw new Error(`the compiler emitted ${fileName}, which is outside the output directory ${emitDir}. ` +
-                "Verify the resolved tsconfig's 'outDir' and 'declarationDir'.");
-        }
-        ts.sys.writeFile(path.join(stagingDir, path.relative(emitDir, fileName)), file.text, file.writeByteOrderMark);
-    }
-}
-async function detectBuildChanges(packageDir, files, emitConfig, toolchain, cachePath, isOutputPresent, style) {
-    const packageName = path.basename(packageDir);
+async function detectBuildChanges(packageDir, files, emitConfig, toolchain, cachePath, isOutputPresent) {
     const previousHash = await readCacheEntry(cachePath);
     const currentHash = await computeBuildHash(packageDir, files, emitConfig, toolchain);
-    if (previousHash === currentHash) {
-        if (isOutputPresent) {
-            const savedMs = await readEmitDuration(packageDir, currentHash);
-            await writeStatedOutcome(process.env, { kind: 'build-unchanged', ...(savedMs !== undefined && { savedMs }) });
-            const saving = formatSaving(savedMs ?? 0);
-            const savingClause = saving === undefined ? '' : `, ${saving}`;
-            console.info(`${STATUS_GLYPHS[style].skipped.text} ${packageName}: No changes detected. Skipping build${savingClause}.`);
-            return { changed: false, currentHash };
-        }
-        console.info(formatGlyphLine(NMR_GLYPHS, style, 'package', `${packageName}: Build output is missing. Rebuilding.`));
-        return { changed: true, currentHash };
+    if (previousHash !== currentHash) {
+        return { reason: 'inputs-changed', currentHash };
     }
-    console.info(formatGlyphLine(NMR_GLYPHS, style, 'package', `${packageName}: Changes detected.`));
-    return { changed: true, currentHash };
+    return { reason: isOutputPresent ? 'unchanged' : 'output-missing', currentHash };
 }
-function describeEmit(fileCount, outdir) {
-    if (fileCount === 0) {
-        return 'Did not emit any output.';
-    }
-    return `Compiled ${fileCount} files to ${outdir.replace(/\/+$/u, '')}.`;
+export async function recordUnchangedBuild(packageDir, digest, env) {
+    const savedMs = await readEmitDuration(packageDir, digest);
+    await writeStatedOutcome(env, { kind: 'build-unchanged', ...(savedMs !== undefined && { savedMs }) });
+    return savedMs;
 }

package/dist/esm/commands/clean-report.d.ts

@@ -0,0 +1,6 @@
+import { type OutputStyle } from '@williamthorsen/nmr-core';
+import type { CleanOutcome, CleanProgress } from './clean.js';
+/** Renders the line that closes a sweep, or `undefined` for a one-package clean, whose own line concludes it. */
+export declare function renderCleanOutcome(outcome: CleanOutcome, style: OutputStyle): string | undefined;
+/** Renders the line that reports a completed step of a clean. */
+export declare function renderCleanProgress(progress: CleanProgress, style: OutputStyle): string;

package/dist/esm/commands/clean-report.js

@@ -0,0 +1,20 @@
+import path from 'node:path';
+import { formatGlyphLine } from '@williamthorsen/nmr-core';
+import { NMR_GLYPHS } from "../glyphs.js";
+export function renderCleanOutcome(outcome, style) {
+    if (outcome.kind === 'package') {
+        return undefined;
+    }
+    return formatGlyphLine(NMR_GLYPHS, style, 'clean', describeSweep(outcome.cleanedDirs.length, outcome.skippedCount));
+}
+export function renderCleanProgress(progress, style) {
+    const message = progress.kind === 'check-results-removed'
+        ? 'Removed all recorded check results.'
+        : `${path.basename(progress.packageDir)}: Removed build output and cache.`;
+    return formatGlyphLine(NMR_GLYPHS, style, 'clean', message);
+}
+function describeSweep(cleanedCount, skippedCount) {
+    const packages = cleanedCount === 1 ? '1 package' : `${cleanedCount} packages`;
+    const skipClause = skippedCount === 0 ? '' : `, skipping ${skippedCount} with an empty clean override`;
+    return `Cleaned ${packages}${skipClause}.`;
+}

package/dist/esm/commands/clean.d.ts

@@ -1,18 +1,50 @@
-import { type OutputStyle } from '@williamthorsen/nmr-core';
+import type { Writable } from 'node:stream';
+/** What a clean did: one package's clean, or a sweep of every workspace package. */
+export type CleanOutcome = {
+    kind: 'package';
+    checkResultsDir: string;
+    packageDir: string;
+} | {
+    kind: 'sweep';
+    checkResultsDir: string;
+    cleanedDirs: string[];
+    skippedCount: number;
+};
+/** A step of a clean, reported as soon as it completes. */
+export type CleanProgress = {
+    kind: 'check-results-removed';
+} | {
+    kind: 'package-cleaned';
+    packageDir: string;
+};
+/** What a clean needs from its caller: a listener for its progress, and the streams for an override's output. */
+export interface CleanOptions {
+    /** Called after each step completes, so that a caller can report it before a later override runs or fails. */
+    onProgress?: (progress: CleanProgress) => void;
+    /** The stream to which a package's own `clean` override writes its errors. */
+    stderr: Writable;
+    /** The stream to which a package's own `clean` override writes its output. */
+    stdout: Writable;
+}
+/**
+ * Cleans the package containing `cwd`, or every workspace package when run from the monorepo root.
+ *
+ * From within a package this is the built-in clean itself: `nmr` has already resolved `clean` to `nmr-clean`
+ * before invoking it, so resolving again would apply the package's own override twice.
+ */
+export declare function cleanFrom(cwd: string, options: CleanOptions): Promise<CleanOutcome>;
 /**
  * Removes a package's build output and the build-cache entries that describe it, so the package does not keep
  * any state that would make the next build skip. Removal is idempotent: An already-clean package is a silent
  * no-op.
  */
-export declare function cleanPackage(packageDir: string, style: OutputStyle): Promise<void>;
+export declare function cleanPackage(packageDir: string): Promise<void>;
 /**
- * Cleans the package containing `cwd`, or every workspace package when run from the monorepo root.
- *
- * From within a package this is the built-in clean itself: `nmr` has already resolved `clean` to this bin
- * before invoking it, so resolving again would apply the package's own override twice.
+ * Runs `nmr-clean` against `argv` from `cwd` and returns the exit code to report. The command takes neither an
+ * option nor an operand, so anything but `--help` is a usage error and removes nothing.
  *
  * This is the default `clean` script, and it is published as a bin because, under pnpm's isolated layout,
  * `pnpm exec` resolves only the bins of the consuming project's direct dependencies: pnpm links nmr's own bins
  * into the consumer's `node_modules/.bin`, but not the bins of nmr's dependencies.
  */
-export declare function runClean(cwd: string, style: OutputStyle): Promise<void>;
+export declare function runClean(argv: string[], cwd: string): Promise<number>;

package/dist/esm/commands/clean.js

@@ -1,59 +1,81 @@
 import { rm } from 'node:fs/promises';
 import path from 'node:path';
-import { formatGlyphLine, UserError } from '@williamthorsen/nmr-core';
+import process from 'node:process';
+import { UserError } from '@williamthorsen/nmr-core';
+import { defineCommand, runCli } from '@williamthorsen/nmr-core/cli';
 import { NMR_CLEAN_BIN } from "../bins.js";
 import { removeCheckCache } from "../check-cache-entries.js";
 import { loadRootConfig } from "../config.js";
 import { findContainingPackageDir } from "../context.js";
-import { NMR_GLYPHS } from "../glyphs.js";
 import { reportClosing } from "../helpers/reportClosing.js";
 import { resolveChannel } from "../output-channel.js";
+import { resolveBinStyles } from "../resolveBinStyles.js";
 import { buildWorkspaceRegistry, resolveScript } from "../resolver.js";
 import { runCommand } from "../runner.js";
 import { renderChain } from "../steps.js";
 import { findMonorepoRoot, getWorkspacePackageDirs } from "../workspace.js";
 import { resolveBuildCachePath, resolveEmitDurationPath } from "./build-output.js";
+import { renderCleanOutcome, renderCleanProgress } from "./clean-report.js";
 const CLEAN_COMMAND = 'clean';
 const BUILT_IN_CLEAN = 'nmr-clean';
 const OUTPUT_ROOT = 'dist';
-export async function cleanPackage(packageDir, style) {
-    await rm(path.resolve(packageDir, OUTPUT_ROOT), { recursive: true, force: true });
-    await rm(resolveBuildCachePath(packageDir), { force: true });
-    await rm(resolveEmitDurationPath(packageDir), { force: true });
-    console.info(formatGlyphLine(NMR_GLYPHS, style, 'clean', `${path.basename(packageDir)}: Removed build output and cache.`));
-}
-export async function runClean(cwd, style) {
+export async function cleanFrom(cwd, options) {
     let monorepoRoot;
     try {
         monorepoRoot = findMonorepoRoot(cwd);
     }
     catch {
-        await clearCheckCache(cwd, style);
-        await cleanPackage(cwd, style);
-        return;
+        await clearCheckCache(cwd, options);
+        await cleanReportedPackage(cwd, options);
+        return { kind: 'package', checkResultsDir: cwd, packageDir: cwd };
     }
-    await clearCheckCache(monorepoRoot, style);
+    await clearCheckCache(monorepoRoot, options);
     const workspacePackageDirs = getWorkspacePackageDirs(monorepoRoot);
     const packageDir = findContainingPackageDir(cwd, workspacePackageDirs);
     if (packageDir !== undefined) {
-        await cleanPackage(packageDir, style);
-        return;
+        await cleanReportedPackage(packageDir, options);
+        return { kind: 'package', checkResultsDir: monorepoRoot, packageDir };
     }
-    await sweepWorkspace(monorepoRoot, workspacePackageDirs, style);
+    return sweepWorkspace(monorepoRoot, workspacePackageDirs, options);
 }
-async function clearCheckCache(scopeDir, style) {
-    await removeCheckCache(scopeDir);
-    console.info(formatGlyphLine(NMR_GLYPHS, style, 'clean', 'Removed all recorded check results.'));
+export async function cleanPackage(packageDir) {
+    await rm(path.resolve(packageDir, OUTPUT_ROOT), { recursive: true, force: true });
+    await rm(resolveBuildCachePath(packageDir), { force: true });
+    await rm(resolveEmitDurationPath(packageDir), { force: true });
+}
+export async function runClean(argv, cwd) {
+    const command = defineCommand({
+        summary: 'Remove the build output and build cache of this package, or of every package from the monorepo root',
+        run: async () => {
+            const style = resolveBinStyles().stdout;
+            const outcome = await cleanFrom(cwd, {
+                onProgress: (progress) => {
+                    console.info(renderCleanProgress(progress, style));
+                },
+                stderr: process.stderr,
+                stdout: process.stdout,
+            });
+            const closing = renderCleanOutcome(outcome, style);
+            if (closing !== undefined) {
+                reportClosing(closing);
+            }
+            return 0;
+        },
+    });
+    return runCli(argv, command, { name: NMR_CLEAN_BIN, stdout: process.stdout, stderr: process.stderr, baseDir: cwd });
 }
-function describeSweep(cleanedCount, skippedCount) {
-    const packages = cleanedCount === 1 ? '1 package' : `${cleanedCount} packages`;
-    const skipClause = skippedCount === 0 ? '' : `, skipping ${skippedCount} with an empty clean override`;
-    return `Cleaned ${packages}${skipClause}.`;
+async function cleanReportedPackage(packageDir, options) {
+    await cleanPackage(packageDir);
+    options.onProgress?.({ kind: 'package-cleaned', packageDir });
+}
+async function clearCheckCache(scopeDir, options) {
+    await removeCheckCache(scopeDir);
+    options.onProgress?.({ kind: 'check-results-removed' });
 }
-async function sweepWorkspace(monorepoRoot, workspacePackageDirs, style) {
+async function sweepWorkspace(monorepoRoot, workspacePackageDirs, options) {
     const config = await loadRootConfig(monorepoRoot);
     const registry = buildWorkspaceRegistry(config);
-    let cleanedCount = 0;
+    const cleanedDirs = [];
     let skippedCount = 0;
     for (const packageDir of workspacePackageDirs) {
         const resolvedScript = resolveScript(CLEAN_COMMAND, registry, packageDir, false);
@@ -63,18 +85,20 @@ async function sweepWorkspace(monorepoRoot, workspacePackageDirs, style) {
             continue;
         }
         if (resolvedCommand === BUILT_IN_CLEAN) {
-            await cleanPackage(packageDir, style);
-            cleanedCount++;
+            await cleanReportedPackage(packageDir, options);
+            cleanedDirs.push(packageDir);
             continue;
         }
         const { exitCode } = await runCommand(resolvedCommand, packageDir, {
             bin: NMR_CLEAN_BIN,
-            channels: { stderr: resolveChannel(process.stderr, false), stdout: resolveChannel(process.stdout, false) },
+            channels: { stderr: resolveChannel(options.stderr, false), stdout: resolveChannel(options.stdout, false) },
+            stderr: options.stderr,
+            stdout: options.stdout,
         });
         if (exitCode !== 0) {
             throw new UserError(`\`${resolvedCommand}\` failed in ${path.basename(packageDir)} with exit code ${exitCode}.`);
         }
-        cleanedCount++;
+        cleanedDirs.push(packageDir);
     }
-    reportClosing(formatGlyphLine(NMR_GLYPHS, style, 'clean', describeSweep(cleanedCount, skippedCount)));
+    return { kind: 'sweep', checkResultsDir: monorepoRoot, cleanedDirs, skippedCount };
 }

package/dist/esm/commands/compile.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Runs `nmr-compile` against `argv` for the package at `packageDir` and returns the exit code to report. The command
+ * takes neither an option nor an operand, so anything but `--help` is a usage error and compiles nothing.
+ */
+export declare function runCompile(argv: string[], packageDir: string): Promise<number>;

package/dist/esm/commands/compile.js

@@ -0,0 +1,32 @@
+import path from 'node:path';
+import process from 'node:process';
+import { defineCommand, runCli } from '@williamthorsen/nmr-core/cli';
+import { NMR_COMPILE_BIN } from "../bins.js";
+import { loadWorkspaceConfig } from "../config.js";
+import { resolveBinStyles } from "../resolveBinStyles.js";
+import { buildPackage } from "./build.js";
+import { renderBuildOutcome, renderBuildProgress } from "./build-report.js";
+export async function runCompile(argv, packageDir) {
+    const command = defineCommand({
+        summary: "Compile the package's src tree to dist/esm",
+        run: async () => {
+            const { stdout } = resolveBinStyles();
+            const { build } = await loadWorkspaceConfig(packageDir);
+            const packageName = path.basename(packageDir);
+            const outcome = await buildPackage(packageDir, {
+                onProgress: (progress) => {
+                    console.info(renderBuildProgress(progress, packageName, stdout));
+                },
+                ...(build?.extraIgnorePatterns !== undefined && { extraIgnorePatterns: build.extraIgnorePatterns }),
+            });
+            console.info(renderBuildOutcome(outcome, packageName, stdout));
+            return 0;
+        },
+    });
+    return runCli(argv, command, {
+        name: NMR_COMPILE_BIN,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        baseDir: packageDir,
+    });
+}

package/dist/esm/commands/fmt.d.ts

@@ -10,6 +10,15 @@ export type FormatMode = 'check' | 'write';
  * with `-`.
  */
 export declare function runFmt(argv: string[], cwd?: string): Promise<number>;
+/**
+ * How a spawned Prettier process ended.
+ *
+ * @internal
+ */
+export interface PrettierOutcome {
+    error?: Error | undefined;
+    status: number | null;
+}
 /** @internal */
 export interface RunPrettierOptions {
     cliPath: string;
@@ -23,6 +32,8 @@ export interface RunPrettierOptions {
     cwd: string;
     /** Overridable so that the multi-batch path is reachable without a fixture that hits the real ceiling. */
     budgetBytes?: number;
+    /** Runs the Prettier CLI as `file` with `args` in `cwd`. */
+    spawn?: (file: string, args: string[], cwd: string) => PrettierOutcome;
 }
 /**
  * Runs Prettier over the selection, returning the first non-zero exit code. Every batch runs even after

package/dist/esm/commands/fmt.js

@@ -122,7 +122,7 @@ async function findRepositoryConfig(manifestPath, cwd) {
     }
 }
 export function runPrettier(options) {
-    const { cacheLocation, cliPath, configPath, mode, files, ignorePaths, cwd, budgetBytes = ARGUMENT_BUDGET_BYTES, } = options;
+    const { cacheLocation, cliPath, configPath, mode, files, ignorePaths, cwd, budgetBytes = ARGUMENT_BUDGET_BYTES, spawn = spawnInherited, } = options;
     const prettierArgs = [
         cliPath,
         ...(configPath === undefined ? [] : ['--config', configPath]),
@@ -136,7 +136,7 @@ export function runPrettier(options) {
     ];
     let firstFailureStatus = 0;
     for (const batch of batchWithinBudget(files, budgetBytes)) {
-        const result = spawnSync(process.execPath, [...prettierArgs, ...batch], { cwd, stdio: 'inherit' });
+        const result = spawn(process.execPath, [...prettierArgs, ...batch], cwd);
         if (result.error) {
             reportError(NMR_FMT_BIN, `could not run \`${PRETTIER_PACKAGE}\` (${result.error.message}).`);
             return 1;
@@ -174,3 +174,7 @@ function resolveFrom(parent, specifier) {
         return undefined;
     }
 }
+function spawnInherited(file, args, cwd) {
+    const { error, status } = spawnSync(file, args, { cwd, stdio: 'inherit' });
+    return { error, status };
+}

package/dist/esm/commands/publish-output.d.ts

@@ -0,0 +1,40 @@
+/** The pair of directories through which a build publishes, both siblings of the emit directory. */
+export interface ScratchDirs {
+    previousDir: string;
+    stagingDir: string;
+}
+/** One file emitted by the compiler, kept in memory until the whole emit is ready to publish. */
+export interface StagedFile {
+    text: string;
+    writeByteOrderMark: boolean;
+}
+/**
+ * Removes both scratch directories of `emitDir` without failing the caller. `force` suppresses only a missing
+ * top-level path and `rm` does not retry, so a removal racing another build's leaves `ENOTEMPTY`, `EBUSY`, and
+ * `EPERM` live.
+ */
+export declare function discardScratchDirs(emitDir: string): Promise<void>;
+/**
+ * Publishes the staged emit to `emitDir` atomically: It writes the files to a staging directory and swaps that
+ * into place by rename. Returns how many files it published.
+ *
+ * An emit that produces nothing removes `emitDir` instead, because swapping an empty directory into place would
+ * leave a `dist` behind for a package whose entry points do not emit any output.
+ *
+ * A failure while staging precedes the first rename, so it leaves the previous output exactly as it was.
+ */
+export declare function publishOutput(emitDir: string, stagedFiles: Map<string, StagedFile>): Promise<number>;
+/** Removes both scratch directories of `emitDir`, tolerating their absence. */
+export declare function removeScratchDirs(emitDir: string): Promise<void>;
+/**
+ * Resolves the two scratch directories through which a build publishes: `staging`, which the emit is written to,
+ * and `previous`, which the outgoing output is renamed aside to. Both are siblings of the emit directory, so a
+ * rename between them never crosses a filesystem, and both are dot-prefixed so that a leftover stays out of the
+ * globs that select sources.
+ *
+ * The names are fixed rather than unique because the build removes both before use. A unique name would need a
+ * sweep to accomplish that removal, and a sweep cannot tell a directory orphaned by a killed run from one that a
+ * concurrent build is still writing. Because a directory left behind by a failed build is cleared the same way,
+ * the failure path does not need any cleanup of its own.
+ */
+export declare function resolveScratchDirs(emitDir: string): ScratchDirs;

package/dist/esm/commands/publish-output.js

@@ -0,0 +1,66 @@
+import { existsSync } from 'node:fs';
+import { rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { UserError } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { getCompiler } from "./compiler.js";
+import { isWithin } from "./rewrite-specifiers.js";
+export async function discardScratchDirs(emitDir) {
+    try {
+        await removeScratchDirs(emitDir);
+    }
+    catch {
+    }
+}
+export async function publishOutput(emitDir, stagedFiles) {
+    if (stagedFiles.size === 0) {
+        await rm(emitDir, { force: true, recursive: true });
+        return 0;
+    }
+    writeStagedOutput(stagedFiles, emitDir);
+    await swapIntoPlace(emitDir);
+    return stagedFiles.size;
+}
+export async function removeScratchDirs(emitDir) {
+    const { previousDir, stagingDir } = resolveScratchDirs(emitDir);
+    await rm(previousDir, { force: true, recursive: true });
+    await rm(stagingDir, { force: true, recursive: true });
+}
+export function resolveScratchDirs(emitDir) {
+    const parent = path.dirname(emitDir);
+    const name = path.basename(emitDir);
+    return {
+        previousDir: path.join(parent, `.${name}.previous`),
+        stagingDir: path.join(parent, `.${name}.staging`),
+    };
+}
+async function swapIntoPlace(emitDir) {
+    const { previousDir, stagingDir } = resolveScratchDirs(emitDir);
+    const hadPreviousOutput = existsSync(emitDir);
+    if (hadPreviousOutput) {
+        await rename(emitDir, previousDir);
+    }
+    try {
+        await rename(stagingDir, emitDir);
+    }
+    catch (error) {
+        if (hadPreviousOutput && !existsSync(emitDir)) {
+            await rename(previousDir, emitDir);
+        }
+        throw new UserError(`failed to move the built output into ${emitDir}: ${describeError(error)}`, {
+            cause: error,
+        });
+    }
+    await discardScratchDirs(emitDir);
+}
+function writeStagedOutput(stagedFiles, emitDir) {
+    const ts = getCompiler();
+    const { stagingDir } = resolveScratchDirs(emitDir);
+    for (const [fileName, file] of stagedFiles) {
+        if (!isWithin(emitDir, fileName)) {
+            throw new Error(`the compiler emitted ${fileName}, which is outside the output directory ${emitDir}. ` +
+                "Verify the resolved tsconfig's 'outDir' and 'declarationDir'.");
+        }
+        ts.sys.writeFile(path.join(stagingDir, path.relative(emitDir, fileName)), file.text, file.writeByteOrderMark);
+    }
+}

package/dist/esm/commands/report-catalog.d.ts

@@ -8,3 +8,8 @@ import { type OutputStyle } from '@williamthorsen/nmr-core';
  * pass runs, to keep the reader from taking that result to mean that every dependency is up to date.
  */
 export declare function reportCatalog(cwd: string, style: OutputStyle): void;
+/**
+ * Runs `nmr-report-catalog` against `argv` from `cwd` and returns the exit code to report. The command takes neither
+ * an option nor an operand, so anything but `--help` is a usage error and reports nothing.
+ */
+export declare function runReportCatalog(argv: string[], cwd: string): Promise<number>;

package/dist/esm/commands/report-catalog.js

@@ -1,8 +1,12 @@
+import process from 'node:process';
 import { formatGlyphLine } from '@williamthorsen/nmr-core';
+import { defineCommand, runCli } from '@williamthorsen/nmr-core/cli';
+import { NMR_REPORT_CATALOG_BIN } from "../bins.js";
 import { findContainingPackageDir } from "../context.js";
 import { NMR_GLYPHS } from "../glyphs.js";
 import { DEPENDENCY_FIELDS, readPackageJson } from "../helpers/package-json.js";
 import { reportClosing } from "../helpers/reportClosing.js";
+import { resolveBinStyles } from "../resolveBinStyles.js";
 import { findMonorepoRoot, getWorkspacePackageDirs } from "../workspace.js";
 const CATALOG_PROTOCOL = 'catalog:';
 export function reportCatalog(cwd, style) {
@@ -21,6 +25,21 @@ export function reportCatalog(cwd, style) {
     }
     reportClosing(formatGlyphLine(NMR_GLYPHS, style, 'catalog', describeCatalog(dependencies.length, monorepoRoot)), console.warn);
 }
+export async function runReportCatalog(argv, cwd) {
+    const command = defineCommand({
+        summary: 'Report the catalogued dependencies that a package-scoped upgrade does not read',
+        run: () => {
+            reportCatalog(cwd, resolveBinStyles().stderr);
+            return 0;
+        },
+    });
+    return runCli(argv, command, {
+        name: NMR_REPORT_CATALOG_BIN,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        baseDir: cwd,
+    });
+}
 function describeCatalog(count, monorepoRoot) {
     const subject = count === 1 ? '1 catalogued dependency went' : `${count} catalogued dependencies went`;
     const object = count === 1 ? 'it' : 'them';

package/dist/esm/commands/report-overrides.d.ts

@@ -4,3 +4,8 @@ import { type OutputStyle } from '@williamthorsen/nmr-core';
  * `pnpm.overrides` block left behind in the root `package.json`.
  */
 export declare function reportOverrides(monorepoRoot: string, style: OutputStyle): void;
+/**
+ * Runs `nmr-report-overrides` against `argv` for the monorepo containing `cwd` and returns the exit code to report.
+ * The command takes neither an option nor an operand, so anything but `--help` is a usage error and reports nothing.
+ */
+export declare function runReportOverrides(argv: string[], cwd: string): Promise<number>;